# node-mocks-http > Mock 'http' objects for testing Express, Next.js and Koa routing functions Latest version **1.18.1** (published 2026-07-16) · MIT license · 0 weekly downloads ## Install ```sh npm install node-mocks-http pnpm add node-mocks-http yarn add node-mocks-http bun add node-mocks-http ``` ## Health **Score 65/100 (B)** — status: active. Positive: has types; no vulnerabilities; recently updated; high maintenance score; high quality score. Warnings: low downloads; no esm support. ## Facts | | | |---|---| | Version | 1.18.1 | | Published | 2026-07-16 | | First published | 2012-02-18 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | CommonJS | | Node | >=14 | | Dependencies | 9 | | Unpacked size | 84.3 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 771 | | Author | Howard Abrams | | Maintainers | eugef | | Keywords | mock, stub, dummy, nodejs, js, testing, test, http, http mock | ## Links - npm: https://www.npmjs.com/package/node-mocks-http - Repository: https://github.com/eugef/node-mocks-http - Issues: https://github.com/eugef/node-mocks-http/issues - npm.io page: https://npm.io/package/node-mocks-http ## Dependencies (9) - [depd](https://npm.io/package/depd.md) ^1.1.0 - [mime](https://npm.io/package/mime.md) ^1.3.4 - [fresh](https://npm.io/package/fresh.md) ^0.5.2 - [accepts](https://npm.io/package/accepts.md) ^1.3.7 - [methods](https://npm.io/package/methods.md) ^1.1.2 - [type-is](https://npm.io/package/type-is.md) ^1.6.18 - [range-parser](https://npm.io/package/range-parser.md) ^1.2.0 - [merge-descriptors](https://npm.io/package/merge-descriptors.md) ^1.0.1 - [content-disposition](https://npm.io/package/content-disposition.md) ^0.5.3 ## Alternatives - [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads - [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads - [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads - [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads - [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads ## Recent versions - 1.18.1 (latest) — 2026-07-16 - 1.18.0 — 2026-07-07 - 1.17.2 — 2025-05-02 - 1.17.1 — 2025-05-01 - 1.17.0 — 2025-04-27 - 1.16.2 — 2024-12-10 - 1.16.1 — 2024-10-04 - 1.16.0 — 2024-09-09 - 1.15.1 — 2024-07-31 - 1.15.0 — 2024-06-21 - 1.14.1 — 2024-01-03 - 1.14.0 — 2023-12-12 - 1.13.0 — 2023-08-14 - 1.12.2 — 2023-03-13 - 1.12.1 — 2022-11-11 - … 55 more at https://npm.io/package/node-mocks-http/versions ## README [![Logo](https://user-images.githubusercontent.com/895071/227720269-37e34019-eba0-4768-80ab-1a4dad043043.png)](https://github.com/eugef/node-mocks-http) --- [![NPM version][npm-badge]][npm-url] Mock 'http' objects for testing [Express][express-url], [Next.js][nextjs-url] and [Koa][koa-url] routing functions, but could be used for testing any [Node.js][node-url] web server applications that have code that requires mockups of the `request` and `response` objects. ## Installation This project is available as a [NPM package][npm-url]. ```bash $ npm install node-mocks-http --save-dev $ npm install @types/node @types/express --save-dev # when using TypeScript ``` or ```bash $ yarn add node-mocks-http --dev $ yarn add @types/node @types/express --dev # when using TypeScript ``` After installing the package include the following in your test files: ```js const httpMocks = require('node-mocks-http'); ``` ## Usage Suppose you have the following Express route: ```js app.get('/user/:id', routeHandler); ``` And you have created a function to handle that route's call: ```js const routeHandler = function( request, response ) { ... }; ``` You can easily test the `routeHandler` function with some code like this using the testing framework of your choice: ```js exports['routeHandler - Simple testing'] = function (test) { const request = httpMocks.createRequest({ method: 'GET', url: '/user/42', params: { id: 42 } }); const response = httpMocks.createResponse(); routeHandler(request, response); const data = response._getJSONData(); // short-hand for JSON.parse( response._getData() ); test.equal('Bob Dog', data.name); test.equal(42, data.age); test.equal('bob@dog.com', data.email); test.equal(200, response.statusCode); test.ok(response._isEndCalled()); test.ok(response._isJSON()); test.ok(response._isUTF8()); test.done(); }; ``` ### TypeScript typings The typings for TypeScript are bundled with this project. In particular, the `.createRequest()`, `.createResponse()` and `.createMocks()` methods are typed and are generic. Unless specified explicitly, they will be return an Express-based request/response object: ```ts it('should handle expressjs requests', () => { const mockExpressRequest = httpMocks.createRequest({ method: 'GET', url: '/user/42', params: { id: 42 } }); const mockExpressResponse = httpMocks.createResponse(); routeHandler(request, response); const data = response._getJSONData(); test.equal('Bob Dog', data.name); test.equal(42, data.age); test.equal('bob@dog.com', data.email); test.equal(200, response.statusCode); test.ok(response._isEndCalled()); test.ok(response._isJSON()); test.ok(response._isUTF8()); test.done(); }); ``` The expected type parameter in the mock request and response expects any type that extends the NodeJS `http.IncomingRequest` interface or Fetch API `Request` class. This means you can also mock requests coming from other frameworks too. An example for NextJS request will look like this: ```ts it('should handle nextjs requests', () => { const mockExpressRequest = httpMocks.createRequest({ method: 'GET', url: '/user/42', params: { id: 42 } }); const mockExpressResponse = httpMocks.createResponse(); // ... the rest of the test as above. }); ``` It is also possible to mock requests from the NextJS new AppRouter: ```ts it('should handle nextjs app reouter requests', () => { const mockExpressRequest = httpMocks.createRequest({ method: 'GET', url: '/user/42', params: { id: 42 } }); const mockExpressResponse = httpMocks.createResponse(); // ... the rest of the test as above. }); ``` ## API ### .createRequest() ``` httpMocks.createRequest(options) ``` Where options is an object hash with any of the following values: | option | description | default value | | --------------- | -------------------------------- | ------------- | | `method` | request HTTP method | 'GET' | | `url` | request URL | '' | | `originalUrl` | request original URL | `url` | | `baseUrl` | request base URL | `url` | | `path` | request path | '' | | `params` | object hash with params | {} | | `session` | object hash with session values | `undefined` | | `cookies` | object hash with request cookies | {} | | `socket` | object hash with request socket | {} | | `signedCookies` | object hash with signed cookies | `undefined` | | `headers` | object hash with request headers | {} | | `body` | object hash with body | {} | | `query` | object hash with query values | {} | | `files` | object hash with values | {} | The object returned from this function also supports the [Express request](http://expressjs.com/en/4x/api.html#req) functions ([`.accepts()`](http://expressjs.com/en/4x/api.html#req.accepts), [`.is()`](http://expressjs.com/en/4x/api.html#req.is), [`.get()`](http://expressjs.com/en/4x/api.html#req.get), [`.range()`](http://expressjs.com/en/4x/api.html#req.range), etc.). Please send a PR for any missing functions. ### .createResponse() ```js httpMocks.createResponse(options); ``` Where options is an object hash with any of the following values: | option | description | default value | | ---------------- | ----------------------------------------------- | -------------------- | | `locals` | object that contains `response` local variables | `{}` | | `eventEmitter` | event emitter used by `response` object | `mockEventEmitter` | | `writableStream` | writable stream used by `response` object | `mockWritableStream` | | `req` | Request object being responded to | null | > NOTE: The out-of-the-box mock event emitter included with `node-mocks-http` is > not a functional event emitter and as such does not actually emit events. If you > wish to test your event handlers you will need to bring your own event emitter. > Here's an example: ```js const httpMocks = require('node-mocks-http'); const res = httpMocks.createResponse({ eventEmitter: require('events').EventEmitter }); // ... it('should do something', function(done) { res.on('end', function() { assert.equal(...); done(); }); }); // ... ``` > This is an example to send request body and trigger it's 'data' and 'end' events: ```js const httpMocks = require('node-mocks-http'); const req = httpMocks.createRequest(); const res = httpMocks.createResponse({ eventEmitter: require('events').EventEmitter }); // ... it('should do something', function (done) { res.on('end', function () { expect(response._getData()).to.equal('data sent in request'); done(); }); route(req, res); req.send('data sent in request'); }); function route(req, res) { let data = []; req.on('data', (chunk) => { data.push(chunk); }); req.on('end', () => { data = Buffer.concat(data); res.write(data); res.end(); }); } // ... ``` ### .createMocks() ```js httpMocks.createMocks(reqOptions, resOptions); ``` Merges `createRequest` and `createResponse`. Passes given options object to each constructor. Returns an object with properties `req` and `res`. ## Design Decisions We wanted some simple mocks without a large framework. We also wanted the mocks to act like the original framework being mocked, but allow for setting of values before calling and inspecting of values after calling. ## For Developers We are looking for more volunteers to bring value to this project, including the creation of more objects from the [HTTP module][node-http-module-url]. This project doesn't address all features that must be mocked, but it is a good start. Feel free to send pull requests, and a member of the team will be timely in merging them. If you wish to contribute please read our [Contributing Guidelines](CONTRIBUTING.md). ## Release Notes Most releases fix bugs with our mocks or add features similar to the actual `Request` and `Response` objects offered by Node.js and extended by Express. See the [Release History](HISTORY.md) for details. [release-notes]: https://github.com/eugef/node-mocks-http/releases ## License Licensed under [MIT](LICENSE). [npm-badge]: https://badge.fury.io/js/node-mocks-http.png [npm-url]: https://www.npmjs.com/package/node-mocks-http [express-url]: https://expressjs.com [nextjs-url]: https://nextjs.org [koa-url]: https://koajs.com [node-url]: http://www.nodejs.org [node-http-module-url]: http://nodejs.org/docs/latest/api/http.html --- _Source: https://npm.io/package/node-mocks-http · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._