Registry / testing / nock
library0.2.1jsnpmunverified

Nock is a robust HTTP server mocking and expectations library designed specifically for Node.js environments. It enables developers to test modules that make outbound HTTP/HTTPS requests in isolation by intercepting network traffic and responding with predefined data. The current stable release series is v14, with v14.0.12 being the latest as of April 2026. An actively developed v15 beta series introduces new features such as `passthrough()` for granular control over unmocked requests and improved error handling, but is not yet recommended for production use due to an accidental v15.0.0 release that was later deprecated. Nock maintains an active release cadence, frequently publishing bug fixes and beta updates. Its key differentiators include comprehensive control over request matching (by host, path, query, body, headers, and HTTP verb), the ability to define repeatable or one-time responses, and functionalities for recording and playing back HTTP interactions using 'nock-back' for fixture-based testing. It aims to provide deep control over the network layer to facilitate reliable unit and integration testing without relying on actual network connectivity.

npm install nock
INSTALL
IMPORT
SIG · NOCK
N
nock
testingjavascriptv0.2.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

nock
import nock from 'nock';
const nock = require('nock').default;
The primary Nock object is the default export. For CommonJS, `require('nock')` directly provides the `nock` object, not `require('nock').default`.
Scope
import type { Scope } from 'nock';
import { Scope } from 'nock';
Use `import type` for importing TypeScript types to prevent bundling issues and ensure types are stripped at compile time.
nock.cleanAll
nock.cleanAll();
import { cleanAll } from 'nock'; cleanAll();
Utility methods like `cleanAll`, `isDone`, `activate`, and `restore` are properties of the default `nock` object and are not named exports.

This quickstart demonstrates how to mock an HTTP GET request using Nock. It sets up an interceptor for a specific URL, path, and header, defines a mock JSON response, makes a request using `fetch`, and then asserts both the received data and that all Nock expectations were met for that specific scope, finally cleaning up the mocks.

import nock from 'nock'; import { strict as assert } from 'node:assert'; // Define the base URL for the API to mock const API_BASE_URL = 'http://api.example.com'; const FAKE_API_PATH = '/users/123'; async function getUserData(userId: string) { const response = await fetch(`${API_BASE_URL}/users/${userId}`, { headers: { 'Accept': 'application/json' } }); if (!response.ok) { throw new Error(`HTTP error! Status: ${response.status}`); } return response.json(); } async function runTest() { // 1. Set up the Nock interceptor for a GET request const scope = nock(API_BASE_URL) .matchHeader('Accept', 'application/json') .get(FAKE_API_PATH) .reply(200, { id: '123', name: 'Nock User', email: 'user@example.com' }, { 'Content-Type': 'application/json', 'X-Nock-Mocked': 'true', 'Cache-Control': 'no-cache' }); try { // 2. Make the HTTP request that Nock will intercept console.log('Fetching user data...'); const userData = await getUserData('123'); // 3. Assert the response data matches the mock assert.deepStrictEqual(userData, { id: '123', name: 'Nock User', email: 'user@example.com' }, 'User data should match mock payload.'); console.log('Successfully received mocked user data.'); // 4. Assert that all Nock expectations were met for this scope assert(scope.isDone(), 'Nock scope should be done, all expectations met.'); console.log('Nock expectations met for the defined scope.'); } catch (error) { console.error('Test failed:', error); process.exit(1); } finally { // 5. Clean up Nock mocks to prevent interference with other tests nock.cleanAll(); console.log('Nock mocks cleaned up.'); } } // Ensure Nock is active; often implicit after import, but good for clarity nock.activate(); runTest();
Debug
Known issues
breakingNock v15.0.0 was released by accident and contains known issues. It has been immediately deprecated. Users should avoid installing v15.0.0 directly and instead continue using the latest v14 stable releases (e.g., v14.0.12) or explicitly use the v15 beta series (e.g., v15.0.0-beta.10) for pre-release features.
fix
Downgrade to the latest v14 stable version or specify a v15 beta version in your `package.json`.
affects: 15.0.0
breakingNock now strictly enforces Node.js engine compatibility. Versions older than Node.js 18.20.0 or specific patches within Node.js 20 may not be supported, potentially leading to runtime errors or unexpected behavior.
fix
Ensure your Node.js environment meets the minimum requirement of `>=18.20.0 <20 || >=20.12.1` as specified in the package's `engines` field.
affects: >=14.0.0
breakingWhen using `replyWithError()`, Nock v14.0.10 and later expect an actual `Error` object as the argument, not a plain JavaScript object. Providing a plain object will no longer be treated as an error and may lead to unexpected behavior.
fix
Refactor calls to `replyWithError(errorObject)` to ensure `errorObject` is an instance of `Error` (e.g., `new Error('Something went wrong')`).
affects: >=14.0.10
gotchaNock interceptors are active immediately upon creation. To prevent unintended side effects or test pollution, always call `nock.cleanAll()` in your test teardown hooks (e.g., `afterEach`, `afterAll`) to remove all pending and active mocks.
fix
Add `afterEach(() => nock.cleanAll());` to your test suite setup to ensure a clean state before each test.
affects: all
gotchaBy default, Nock intercepts all HTTP/HTTPS requests once activated. If you need to allow specific 'real' network requests (e.g., to a local API or specific external services) while mocking others, you must explicitly configure `nock.enableNetConnect()`.
fix
Use `nock.enableNetConnect('localhost')` or `nock.enableNetConnect('*.my-real-service.com')` to allow specified hostnames to make real network requests.
affects: all
Errors
Common errors & fixes
Nock: No match for request
The actual outgoing HTTP request did not precisely match any defined Nock interceptor's criteria (URL, path, method, headers, query, or body).
fix
Carefully review the `nock` definition and the actual outgoing request. Use `nock.pendingMocks()` to identify unmatched scopes or `nock.on('request')` and `nock.recorder.rec()` for debugging mismatch details. Ensure all parameters (host, path, method, query, body, headers) align exactly.
TypeError: nock is not a function
This typically occurs in CommonJS environments if `require('nock').default` is used instead of `require('nock')`, or if `nock` is mistakenly treated as a named import in some ESM setups.
fix
For CommonJS, use `const nock = require('nock');`. For ESM, ensure `import nock from 'nock';` is used, as `nock` is the default export. Methods like `cleanAll()` are accessed via `nock.cleanAll()`.
Error: Aborted
ETIMEDOUT
A mocked request either timed out waiting for a Nock response, or the Nock interceptor itself has a `delayConnection()` or `delay()` option set that is longer than the client's timeout, or fake timers are not advanced.
fix
Verify that `nock` mocks are responding within expected timeframes. If using `delay()` or `delayConnection()`, adjust them or ensure your test runner's fake timers (e.g., `jest.runAllTimers()`) are correctly advancing.
Error: Request failed with status code 404 (or other non-mocked status)
This usually indicates that `nock` was not active, the specific mock was already consumed (not persistent), or the request was not intercepted by Nock at all, leading to a real network request (which then failed).
fix
Ensure `nock.activate()` has been called. If the mock should apply to multiple requests, add `.persist()` to the interceptor definition. Check `nock.isDone()` before assertions to confirm all mocks were consumed, or `nock.pendingMocks()` for unfulfilled expectations. Reconfirm the URL/path of the request and mock.
Upgrade
Version history
0.2.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
7 hits · last 30 days
node
6
Amazon
1
Resources