Mock HTTP Request/Response for Node.js

Common errors

• TypeError: mock.Request is not a constructor

  cause Attempting to instantiate `Request` or `Response` from an incorrectly imported `mock` object, or the `mock` object is undefined.
  fix Ensure you are importing the library correctly using named imports (`import { Request, Response } from 'mock-http';`) or a namespace import (`import * as mock from 'mock-http';`) and then referencing `mock.Request` or `mock.Response`.

• AssertionError: test never reaches here

  cause The middleware being tested did not call `res.end()` or `next()`, which prevents the test's `onEnd` callback or the subsequent middleware function from executing.
  fix Verify the middleware logic correctly handles all execution paths, ensuring `res.end()` or `next()` is called under expected test conditions, especially for asynchronous operations.

• Error: write after end

  cause The middleware attempted to write to the response stream (e.g., `res.write()`) after `res.end()` had already been called, which is not allowed by the `http.ServerResponse` contract.
  fix Review the middleware logic to prevent multiple calls to `res.end()` or any write operations to the response stream after the response has been finalized.

Warnings

• gotcha This library provides mock implementations of `http.IncomingMessage` and `http.ServerResponse`, meaning it does not involve actual network sockets. Functionality typically handled by the underlying socket, such as low-level `net.Socket` events or properties like `remoteAddress`, will not be accurately mimicked or may not function as expected in a real HTTP server environment.
  Fix: Design tests to focus on HTTP protocol-level interactions (headers, body, status codes) rather than direct socket manipulation or properties that depend on a live network connection.
• gotcha When testing asynchronous middleware, particularly those that process request bodies (e.g., `req.on('data')`, `req.on('end')`), it's crucial to ensure your test harness properly waits for the middleware's asynchronous operations to complete before asserting on the mock response state. Failure to do so can lead to flaky tests or incorrect assertions.
  Fix: For `mock.Response`, use the `onEnd` callback to trigger test assertions. For `mock.Request`, ensure all 'data' and 'end' event listeners have processed their input before concluding the test.
• gotcha The library exposes an `_internal` property on `mock.Response` for querying states like `headers`, `buffer`, and `ended`. While useful for testing, relying on the exact structure of this private property directly might be fragile if future major versions change its internal representation without explicit API changes.
  Fix: Prefer using public methods like `res.statusCode`, `res.getHeader()`, and `res.hasEnded()` where possible. If `_internal` is necessary, be prepared for potential adjustments during major version upgrades.

Install

• npm install mock-http npm
• yarn add mock-http yarn
• pnpm add mock-http pnpm

Imports

• Request, Response
  wrong:

  import Request from 'mock-http';

  correct:

  import { Request, Response } from 'mock-http';

  This is the modern way to import the mock classes in ES Modules or TypeScript. The package includes its own type definitions for `IncomingMessageMock` and `ServerResponseMock`.
• mock (namespace)
  wrong:

  import mock from 'mock-http';

  correct:

  import * as mock from 'mock-http';

  Imports the entire module as a namespace object, allowing access to `mock.Request` and `mock.Response`. Useful when you want to explicitly refer to the module context.
• Request (CJS), Response (CJS)
  wrong:

  const mockHttp = require('mock-http'); const Request = mockHttp.Request;

  correct:

  const { Request, Response } = require('mock-http');

  The standard way to import the mock classes in CommonJS Node.js environments. While the verbose `mockHttp.Request` is functionally correct, destructuring is often preferred for conciseness.

Quickstart

Demonstrates mocking HTTP requests and responses to test a simple Connect-style middleware function, verifying headers, body, status, and middleware chaining behavior.

import * as mock from 'mock-http';
import { strict as assert } from 'assert';

describe('mock-http example', function(){
    // a middleware function under test
    var middleware = function(req, res, next) {
        var regex = /^(?:\/test)(\/.*|$)/;
        req.params = '';

        req.on('data', function(data){
            req.params += data; // a simple body parser
        });
        req.on('end', function(){
            if (regex.test(req.url)) {
                req.url = req.url.replace(regex, '$1') || '/';
                res.writeHead(200, { 'Cache-Control': 'max-age=300'});
                res.write('this is a test');
                res.end();
            }
            else {
                next && next();
            }
        });
    };

    it('shall respond with a 200', function(done){
        var req = new mock.Request({
                    url: '/test',
                    method: 'POST',
                    buffer: Buffer.from('name=mock&version=first')
                });
        var res = new mock.Response({
                onEnd: function() {
                    // the test ends here
                    assert.equal(req.url, '/');
                    assert.equal(req.params, 'name=mock&version=first');
                    assert.equal(res.statusCode, 200);
                    assert.equal(res.headersSent, true);
                    assert.equal(res.getHeader('Cache-Control'), 'max-age=300');
                    assert.equal(res.hasEnded(), true);
                    done();
                }
            });
        middleware(req, res, function(){
            done(new Error('Next middleware should not have been called'));
        });
    });

    it('shall call next middleware', function(done){
        var req = new mock.Request({
                    url: '/other',
                    method: 'POST',
                    buffer: Buffer.from('data=something')
                });
        var res = new mock.Response({
                onEnd: function() {
                    done(new Error('Response should not have ended, next middleware should be called'));
                }
            });
        middleware(req, res, function(){
            // This is the expected path for this test case
            assert.equal(res.hasEnded(), false); // Ensure response was not ended by this middleware
            done();
        });
    });
});