Nock

Notice

We have introduced experimental support for fetch. Please share your feedback with us. You can install it by:

npm install --save-dev nock@beta

HTTP server mocking and expectations library for Node.js

Nock can be used to test modules that perform HTTP requests in isolation.

For instance, if a module performs HTTP requests to a CouchDB server or makes HTTP requests to the Amazon API, you can test that module in isolation.

Table of Contents

<!-- toc -->

• How does it work?
• Install
  • Node version support
• Usage
  • READ THIS! - About interceptors
  • Specifying hostname
  • Specifying path
  • Specifying request body
  • Specifying request query string
  • Specifying replies
    • Access original request and headers
    • Replying with errors
  • Specifying headers
    • Header field names are case-insensitive
    • Specifying Request Headers
    • Specifying Reply Headers
    • Default Reply Headers
    • Including Content-Length Header Automatically
    • Including Date Header Automatically
  • HTTP Verbs
  • Support for HTTP and HTTPS
  • Non-standard ports
  • Repeat response n times
  • Delay the response
    • Delay the connection
      • Technical Details
    • Delay the response body
      • Technical Details
  • Chaining
  • Scope filtering
  • Conditional scope filtering
  • Path filtering
  • Request Body filtering
  • Request Headers Matching
  • Optional Requests
  • Allow unmocked requests on a mocked hostname
• Expectations
  • .isDone()
  • .cleanAll()
  • .abortPendingRequests()
  • .persist()
  • .pendingMocks()
  • .activeMocks()
  • .isActive()
  • .clone()
• Restoring
• Activating
• Turning Nock Off (experimental!)
• Enable/Disable real HTTP requests
  • Disabling requests
  • Enabling requests
  • Resetting NetConnect
• Recording
  • dont_print option
  • output_objects option
  • enable_reqheaders_recording option
  • logging option
  • use_separator option
  • .removeInterceptor()
• Events
  • Global no match event
• Nock Back
  • Setup
    • Options
  • Usage
    • Options
      • Example
  • Modes
  • Verifying recorded fixtures
    • Example
• Common issues
  • Axios
  • Memory issues with Jest
• Debugging
• Contributing
• Contributors
• Sponsors
• License

<!-- tocstop -->

How does it work?

Nock works by overriding Node's http.request function. Also, it overrides http.ClientRequest too to cover for modules that use it directly.

Install

$ npm install --save-dev nock

Node version support

The latest version of nock supports all currently maintained Node versions, see Node Release Schedule

Here is a list of past nock versions with respective node version support

node	nock
0.10	up to 8.x
0.11	up to 8.x
0.12	up to 8.x
4	up to 9.x
5	up to 8.x
6	up to 10.x
7	up to 9.x
8	up to 11.x
9	up to 9.x

Usage

On your test, you can setup your mocking object like this:

const nock = require('nock')

const scope = nock('https://api.github.com')
  .get('/repos/atom/atom/license')
  .reply(200, {
    license: {
      key: 'mit',
      name: 'MIT License',
      spdx_id: 'MIT',
      url: 'https://api.github.com/licenses/mit',
      node_id: 'MDc6TGljZW5zZTEz',
    },
  })

This setup says that we will intercept every HTTP call to https://api.github.com.

It will intercept an HTTPS GET request to /repos/atom/atom/license, reply with a status 200, and the body will contain a (partial) response in JSON.

READ THIS! - About interceptors

When you setup an interceptor for a URL and that interceptor is used, it is removed from the interceptor list. This means that you can intercept 2 or more calls to the same URL and return different things on each of them. It also means that you must setup one interceptor for each request you are going to have, otherwise nock will throw an error because that URL was not present in the interceptor list. If you don’t want interceptors to be removed as they are used, you can use the .persist() method.

Specifying hostname

The request hostname can be a string, URL, or a RegExp.

const scope = nock('http://www.example.com')
  .get('/resource')
  .reply(200, 'domain matched')

const scope = nock(new URL('http://www.example.com'))
  .get('/resource')
  .reply(200, 'domain matched')

const scope = nock(/example\.com/)
  .get('/resource')
  .reply(200, 'domain regex matched')

Note: You can choose to include or not the protocol in the hostname matching.

Specifying path

The request path can be a string, a RegExp or a filter function and you can use any HTTP verb.

Using a string:

const scope = nock('http://www.example.com')
  .get('/resource')
  .reply(200, 'path matched')

Using a regular expression:

const scope = nock('http://www.example.com')
  .get(/source$/)
  .reply(200, 'path using regex matched')

Using a function:

const scope = nock('http://www.example.com')
  .get(uri => uri.includes('cats'))
  .reply(200, 'path using function matched')

Specifying request body

You can specify the request body to be matched as the second argument to the get, post, put or delete specifications. There are five types of second argument allowed:

String: nock will exact match the stringified request body with the provided string

nock('http://www.example.com')
  .post('/login', 'username=pgte&password=123456')
  .reply(200, { id: '123ABC' })

Buffer: nock will exact match the stringified request body with the provided buffer

nock('http://www.example.com')
  .post('/login', Buffer.from([0xff, 0x11]))
  .reply(200, { id: '123ABC' })

RegExp: nock will test the stringified request body against the provided RegExp

nock('http://www.example.com')
  .post('/login', /username=\w+/gi)
  .reply(200, { id: '123ABC' })

JSON object: nock will exact match the request body with the provided object. In order to increase flexibility, nock also supports RegExp as an attribute value for the keys:

nock('http://www.example.com')
  .post('/login', { username: 'pgte', password: /.+/i })
  .reply(200, { id: '123ABC' })

Function: nock will evaluate the function providing the request body object as first argument. Return true if it should be considered a match:

nock('http://www.example.com')
  .post('/login', body => body.username && body.password)
  .reply(200, { id: '123ABC' })

In case you need to perform a partial matching on a complex, nested request body you should have a look at libraries like lodash.matches. Indeed, partial matching can be achieved as:

nock('http://www.example.com')
  .post('/user', _.matches({ address: { country: 'US' } }))
  .reply(200, { id: '123ABC' })

Specifying request query string

Nock understands query strings. Search parameters can be included as part of the path:

nock('http://example.com').get('/users?foo=bar').reply(200)

Instead of placing the entire URL, you can specify the query part as an object:

nock('http://example.com')
  .get('/users')
  .query({ name: 'pedro', surname: 'teixeira' })
  .reply(200, { results: [{ id: 'pgte' }] })

Nock supports array-style/object-style query parameters. The encoding format matches with request module.

nock('http://example.com')
  .get('/users')
  .query({
    names: ['alice', 'bob'],
    tags: {
      alice: ['admin', 'tester'],
      bob: ['tester'],
    },
  })
  .reply(200, { results: [{ id: 'pgte' }] })

A URLSearchParams instance can be provided.

const params = new URLSearchParams({ foo: 'bar' })

nock('http://example.com').get('/').query(params).reply(200)

Nock supports passing a function to query. The function determines if the actual query matches or not.

nock('http://example.com')
  .get('/users')
  .query(actualQueryObject => {
    // do some compare with the actual Query Object
    // return true for matched
    // return false for not matched
    return true
  })
  .reply(200, { results: [{ id: 'pgte' }] })

To mock the entire url regardless of the passed query string:

nock('http://example.com')
  .get('/users')
  .query(true)
  .reply(200, { results: [{ id: 'pgte' }] })

A query string that is already URL encoded can be matched by passing the encodedQueryParams flag in the options when creating the Scope.

nock('http://example.com', { encodedQueryParams: true })
  .get('/users')
  .query('foo%5Bbar%5D%3Dhello%20world%21')
  .reply(200, { results: [{ id: 'pgte' }] })

Specifying replies

You can specify the return status code for a path on the first argument of reply like this:

const scope = nock('http://myapp.iriscouch.com').get('/users/1').reply(404)

You can also specify the reply body as a string:

const scope = nock('http://www.google.com')
  .get('/')
  .reply(200, 'Hello from Google!')

or as a JSON-encoded object:

const scope = nock('http://myapp.iriscouch.com').get('/').reply(200, {
  username: 'pgte',
  email: 'pedro.teixeira@gmail.com',
  _id: '4324243fsd',
})

or even as a file:

const scope = nock('http://myapp.iriscouch.com')
  .get('/')
  .replyWithFile(200, __dirname + '/replies/user.json', {
    'Content-Type': 'application/json',
  })

Instead of an object or a buffer you can also pass in a callback to be evaluated for the value of the response body:

const scope = nock('http://www.google.com')
  .post('/echo')
  .reply(201, (uri, requestBody) => requestBody)

In Nock 11.x it was possible to invoke .reply() with a status code and a function that returns an array containing a status code and body. (The status code from the array would take precedence over the one passed directly to reply.) This is no longer allowed. In Nock 12 and later, either call .reply() with a status code and a function that returns the body, or call it with a single argument: a function that returns an array containing both the status code and body.

An asynchronous function that gets an error-first callback as its last argument also works:

const scope = nock('http://www.google.com')
  .post('/echo')
  .reply(201, (uri, requestBody, cb) => {
    fs.readFile('cat-poems.txt', cb) // Error-first callback
  })

In Nock 11 and later, if an error is passed to the callback, Nock will rethrow it as a programmer error. In Nock 10 and earlier, the error was sent in the response body, with a 500 HTTP response status code.

You can also return the status code and body using just one function:

const scope = nock('http://www.google.com')
  .post('/echo')
  .reply((uri, requestBody) => {
    return [
      201,
      'THIS IS THE REPLY BODY',
      { header: 'value' }, // optional headers
    ]
  })

or, use an error-first callback that also gets the status code:

const scope = nock('http://www.google.com')
  .post('/echo')
  .reply((uri, requestBody, cb) => {
    setTimeout(() => cb(null, [201, 'THIS IS THE REPLY BODY']), 1000)
  })

A Stream works too:

const scope = nock('http://www.google.com')
  .get('/cat-poems')
  .reply(200, (uri, requestBody) => {
    return fs.createReadStream('cat-poems.txt')
  })

Access original request and headers

If you're using the reply callback style, you can access the original client request using this.req like this:

const scope = nock('http://www.google.com')
  .get('/cat-poems')
  .reply(function (uri, requestBody) {
    console.log('path:', this.req.path)
    console.log('headers:', this.req.headers)
    // ...
  })

Note: Remember to use normal function in that case, as arrow functions are using enclosing scope for this binding.

Replying with errors

You can reply with an error like this:

nock('http://www.google.com')
  .get('/cat-poems')
  .replyWithError('something awful happened')

JSON error responses are allowed too:

nock('http://www.google.com').get('/cat-poems').replyWithError({
  message: 'something awful happened',
  code: 'AWFUL_ERROR',
})

Note: This will emit an error event on the request object, not the reply.

Specifying headers

Header field names are case-insensitive

Per [HTTP/1.1 4.2 Message