Nock (HTTP mocking)

Nock (HTTP mocking)
Name	Nock
Title	Nock (HTTP mocking)
Author	Diego Netto
Developer	Node.js community
Released	2011
Programming language	JavaScript
Operating system	Cross-platform
License	MIT License

Nock (HTTP mocking) is a JavaScript library for HTTP mocking and expectations used primarily with Node.js, npm, Express.js, Koa (web framework), and testing frameworks such as Mocha (testing framework), Jest (framework), Jasmine (testing framework), Tape (software) and AVA (test runner). It intercepts outbound HTTP requests at the Node.js networking layer and provides deterministic responses for unit tests, integration tests, and continuous integration pipelines used by projects hosted on GitHub and published via npm. Nock is widely used in open source projects, enterprise stacks, and serverless applications developed for AWS Lambda, Azure Functions, and Google Cloud Functions.

Overview

Nock was created to address the need for reliable network isolation in test suites that interact with external services such as Stripe, Twilio, GitHub, Twitter, Facebook, Salesforce, Slack, SendGrid, and Shopify. It replaces live calls to remote APIs by mocking HTTP requests made with http.ClientRequest, axios, request (software), superagent, and native fetch polyfills in Node.js. Nock operates by overriding core networking primitives in Node.js and offers features for recording live interactions to fixtures consumable by CI systems like Travis CI, CircleCI, and GitHub Actions as well as test reporting in tools like Karma (test runner).

Features

Nock provides declarative request matching for method, path, headers, body, and query parameters, with support for response status codes, headers, response delays, and streaming bodies. It supports persistent and one-time interceptors, request body filtering, regular expression matching, and response templating compatible with tools such as Sinon.JS and Chai (assertion library). Advanced features include replaying recorded HTTP interactions, filtering sensitive data for PCI DSS or GDPR compliance in recorded fixtures, and integration hooks for test lifecycle managers like Jenkins and Azure DevOps. Nock also exposes utilities to assert that all expected requests were made, and to restore the original Node.js networking behavior for test teardown.

Usage

Typical usage involves requiring Nock in test setup files and defining expectations before invoking code under test. With Mocha (testing framework) or Jest (framework), users create fixtures that mock endpoints of services such as Stripe, SendGrid, GitHub, or AWS by specifying the base URL, HTTP verb, route pattern, and the response body and status. Developers often combine Nock with assertion libraries like Chai (assertion library) and spies from Sinon.JS to validate side effects and request payloads. Nock’s recorder can capture live interactions from integration tests calling Heroku apps or Azure endpoints, producing JSON fixture files that can be committed to repositories alongside code in GitHub organizations.

Comparison with alternatives

Compared to service virtualization platforms such as WireMock, Nock is lightweight, in-process, and tailored to Node.js, unlike WireMock which runs as a standalone JVM process. Other JavaScript-centric alternatives include fetch-mock, which focuses on intercepting fetch calls, and msw (Mock Service Worker), which operates at the browser service worker level for React (web framework), Angular (web framework), and Vue.js applications. For end-to-end testing, tools like Cypress (software) and Puppeteer provide broader browser automation where network stubbing is a complement rather than a replacement. Nock’s in-process interception makes it preferable for fast unit tests in continuous integration environments like CircleCI and GitHub Actions where spawning JVM services or Docker containers for mocks (e.g., Mountebank) would add complexity.

Architecture and implementation

Nock patches the http and https modules by wrapping the native request creation and response handling pathways, using event emitters from Node.js core to simulate incoming data and end events. Internally, it maintains a registry of interceptors keyed by host, method, and path, and employs pattern matching via regular expressions and custom predicate functions. Response bodies can be streamed using ReadableStream-compatible interfaces and delayed using timers integrated with test runners. Nock’s recorder serializes request and response metadata into JSON fixtures suitable for replay; the library is implemented in modern JavaScript and published on npm under the MIT License, with source hosted on GitHub and contributions coordinated through GitHub issues and pull requests.

Examples

Example patterns include mocking a POST to Stripe to return a payment intent, stubbing a GET from GitHub to return repository metadata, or faking a webhook POST from Twilio with a signed payload. In tests using Mocha (testing framework), developers set up nock scopes in before hooks and assert scope completion in after hooks. Recorded fixtures are often used in conjunction with tools like Sinon.JS for spying on internal function calls and Chai (assertion library) for expressive assertions. Teams integrating with AWS Lambda commonly use Nock to simulate third-party APIs invoked by serverless handlers.

Adoption and ecosystem

Nock is used by numerous open source projects, SDKs from Stripe, Twilio, Heroku, and community libraries for AWS and Firebase. It has an ecosystem of helpers, fixture utilities, and integrations maintained in community repositories on GitHub and distributed via npm. Prominent organizations and projects relying on Nock include contributors from Mozilla, Microsoft, Google, and various startups building microservices architectures. The project’s community collaborates through GitHub issues, contributor guidelines, and continuous integration pipelines using Travis CI, CircleCI, and GitHub Actions.

Category:JavaScript libraries