Nock

Nock 14.x → 15.x ​

Nock 15 modernizes its request and response APIs and is distributed as a pure ES module. See the v15.0.0 release notes.

Requirements and Installation ​

Nock 15 requires Node.js >=20.12.1:

sh
npm install --save-dev nock@15

Nock is an ES module. In an ES module, import it as usual:

js
import nock from 'nock'

CommonJS projects running Node.js >=20.19 or >=22.12 can use Node's built-in require(esm) support:

js
const { default: nock } = require('nock')

For CommonJS projects on earlier supported Node versions, use dynamic import() or migrate the project to ESM.

Reply Callbacks Receive a Request ​

Reply callbacks now receive a Web Request instead of (uri, body). Read the body asynchronously when needed:

js
// Before
.reply(200, (uri, body) => body)

// After
.reply(200, async request => await request.text())

WARNING

The single-function form, .reply(fn), must return a [status, body, headers] array. Use .reply(200, fn) when the callback returns only a body.

The this.req property has also been removed. Use the callback's request argument:

js
// Before
.reply(200, function () {
  return this.req.headers
})

// After
.reply(200, request => Object.fromEntries(request.headers.entries()))

Body matcher functions now receive only the body; remove any second request argument:

js
// Before
.post('/', (body, request) => body.includes('test'))

// After
.post('/', body => body.includes('test'))

Reply Header Functions ​

Reply header functions receive the request and response body. They no longer receive a response object:

js
// Before
.reply(200, 'Hello', {
  'Content-Length': (request, response, body) => body.length,
})

// After
.reply(200, 'Hello', {
  'Content-Length': (request, body) => body.length,
})

Request and No-Match Events ​

The request and replied scope events now receive a Web Request as their first argument. The global no match event also receives a Request; mismatch details are supplied as an optional second argument when available.

js
nock.emitter.on('no match', request => {
  console.log(request.url)
})

scope.on('replied', (request, interceptor) => {
  console.log(request.url, interceptor.method)
})

Unmatched Mocked Requests Return 501 ​

An unmatched request to a mocked origin now receives a response with status 501 and a JSON body whose code is ERR_NOCK_NO_MATCH. Update tests that expected Nock to throw for this case:

js
import assert from 'node:assert/strict'

const response = await fetch('https://api.example.test/not-mocked')
const body = await response.json()

assert.equal(response.status, 501)
assert.equal(body.code, 'ERR_NOCK_NO_MATCH')

This is distinct from a request to an unmocked origin that is blocked by network-connect rules.

Delay API ​

The .delayBody() and .delayConnection() methods have been removed. Replace them with .delay(ms), which delays response-body completion:

js
// Before
.delayBody(200)

// After
.delay(200)

Host Header Matching ​

The Host header is no longer specially ignored; when request headers are being matched, it is treated like other headers. Review mocks that specify reqheaders and relied on the old Host behavior.

URL Input ​

The legacy url.parse() result is no longer supported as a scope argument. Pass a URL string or a WHATWG URL instead:

js
// Before
nock(url.parse('http://example.test'))

// After
nock('http://example.test')
nock(new URL('http://example.test'))

TypeScript ​

Nock is now written in TypeScript, and its type declarations are generated and shipped with the package. Public types are unchanged apart from minor fixes.

For all details, consult the official Nock 15 migration notes.