mock-http

library1.0jsnpmunverified

mock-http is a Node.js library that provides robust mock implementations of the core `http.IncomingMessage` and `http.ServerResponse` classes. This enables developers to conduct isolated unit testing of HTTP server-side logic, such as Connect, Express, or Koa middleware, without the overhead of creating a real HTTP server or managing network sockets. The library ensures full API compatibility with Node.js's native `http` module interfaces, allowing middleware to be tested in an environment closely mirroring production. Currently stable at version 1.1.1, its release cadence is generally aligned with Node.js LTS cycles for compatibility updates, rather than frequent feature additions, indicating a mature and maintenance-focused project. Its key differentiator is the faithful emulation of the standard HTTP objects, providing a reliable and predictable testing surface for complex server-side components.

testing http-networking web-framework

npm install mock-http

github ↗package ↗

INSTALL

IMPORT

SIG · MOCK-HTTP

mock-http

testingjavascriptv1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Request, Response

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

✗ import Request 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)

✓ import * as mock from 'mock-http';

✗ import 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)

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

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

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.

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(); }); }); });

Debug

Known issues

gotchaThis 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.

affects: >=1.0.0

gotchaWhen 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.

affects: >=1.0.0

gotchaThe 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.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: mock.Request is not a constructor

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

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

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.

Upgrade

Version history

1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/commenthol/mock-http ↗

packagehttps://www.npmjs.com/package/mock-http ↗