Nock HTTP Mocking for Node.js

Common errors

• Nock: No match for request

  cause 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

  cause 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

  cause 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)

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

Warnings

• breaking Nock 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`.
• breaking Nock 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.
• breaking When 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')`).
• gotcha Nock 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.
• gotcha By 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.

Install

• npm install nock npm
• yarn add nock yarn
• pnpm add nock pnpm

Imports

• nock
  wrong:

  const nock = require('nock').default;

  correct:

  import nock from 'nock';

  The primary Nock object is the default export. For CommonJS, `require('nock')` directly provides the `nock` object, not `require('nock').default`.
• Scope
  wrong:

  import { Scope } from 'nock';

  correct:

  import type { Scope } from 'nock';

  Use `import type` for importing TypeScript types to prevent bundling issues and ensure types are stripped at compile time.
• nock.cleanAll
  wrong:

  import { cleanAll } from 'nock'; cleanAll();

  correct:

  nock.cleanAll();

  Utility methods like `cleanAll`, `isDone`, `activate`, and `restore` are properties of the default `nock` object and are not named exports.

Quickstart

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