tessl/npm-nock

HTTP server mocking and expectations library for Node.js testing environments

0.98x

Overview

Eval results

Files

Request Interception

Name: tessl/npm-nock
Rating: 0.67 (1 reviews)
Author: tessl

This document covers the core functionality for creating scopes and intercepting HTTP requests with nock.

Creating Scopes

The main nock function creates a scope that defines the base URL and configuration for intercepting requests.

function nock(basePath: string | RegExp | Url | URL, options?: Options): Scope;

Parameters

basePath: The base URL, hostname, or pattern to intercept. Can be:
- String URL: "https://api.example.com"
- RegExp pattern: /api\.example\.com/
- URL object: new URL("https://api.example.com")
options: Optional configuration for the scope

Examples

// Basic hostname interception
const scope = nock("https://api.example.com");

// Intercept all subdomains
const scope = nock(/.*\.example\.com/);

// With options
const scope = nock("https://api.example.com", {
  allowUnmocked: true,
  encodedQueryParams: true
});

HTTP Method Interceptors

The Scope provides methods for intercepting different HTTP verbs.

interface Scope extends NodeJS.EventEmitter {
  get(uri: string | RegExp | ((uri: string) => boolean), requestBody?: RequestBodyMatcher, options?: Options): Interceptor;
  post(uri: string | RegExp | ((uri: string) => boolean), requestBody?: RequestBodyMatcher, options?: Options): Interceptor;
  put(uri: string | RegExp | ((uri: string) => boolean), requestBody?: RequestBodyMatcher, options?: Options): Interceptor;
  head(uri: string | RegExp | ((uri: string) => boolean), requestBody?: RequestBodyMatcher, options?: Options): Interceptor;
  patch(uri: string | RegExp | ((uri: string) => boolean), requestBody?: RequestBodyMatcher, options?: Options): Interceptor;
  merge(uri: string | RegExp | ((uri: string) => boolean), requestBody?: RequestBodyMatcher, options?: Options): Interceptor;
  delete(uri: string | RegExp | ((uri: string) => boolean), requestBody?: RequestBodyMatcher, options?: Options): Interceptor;
  options(uri: string | RegExp | ((uri: string) => boolean), requestBody?: RequestBodyMatcher, options?: Options): Interceptor;
}

Parameters

uri: The path portion of the URL to match. Can be:
- String path: "/users/123"
- RegExp pattern: /\/users\/\d+/
- Function predicate: (uri) => uri.includes("users")
requestBody: Optional body matcher for POST/PUT/PATCH requests
options: Optional interceptor-specific options

Examples

// GET request
nock("https://api.example.com")
  .get("/users")
  .reply(200, [{ id: 1, name: "Alice" }]);

// POST request with body matching
nock("https://api.example.com")
  .post("/users", { name: "Bob", email: "bob@example.com" })
  .reply(201, { id: 2, name: "Bob", email: "bob@example.com" });

// Dynamic path matching
nock("https://api.example.com")
  .get(/\/users\/\d+/)
  .reply(200, (uri) => {
    const id = uri.split("/").pop();
    return { id: parseInt(id), name: `User ${id}` };
  });

// Function-based URI matching
nock("https://api.example.com")
  .get((uri) => uri.includes("search"))
  .reply(200, { results: [] });

Generic Interceptor

For custom HTTP methods or more control over interception:

intercept(
  uri: string | RegExp | ((uri: string) => boolean),
  method: string,
  requestBody?: RequestBodyMatcher,
  options?: Options
): Interceptor;

Examples

// Custom HTTP method
nock("https://api.example.com")
  .intercept("/data", "PURGE")
  .reply(204);

// Case-insensitive method
nock("https://api.example.com")
  .intercept("/users", "get") // lowercase also works
  .reply(200, []);

Scope Configuration

Scopes can be configured with default behaviors that apply to all interceptors in that scope.

Default Reply Headers

defaultReplyHeaders(headers: ReplyHeaders): this;

Set headers that will be included in all responses from this scope.

const scope = nock("https://api.example.com")
  .defaultReplyHeaders({
    "Content-Type": "application/json",
    "X-API-Version": "1.0"
  });

scope.get("/users").reply(200, []); // Will include the default headers

Persistence

persist(flag?: boolean): this;

Makes the scope persistent, meaning interceptors can be matched multiple times.

// Persist all interceptors in this scope
const scope = nock("https://api.example.com")
  .persist()
  .get("/users")
  .reply(200, []);

// This interceptor can now be called multiple times

Content Length and Date Headers

replyContentLength(): this;
replyDate(d?: Date): this;

Automatically add Content-Length and Date headers to responses.

const scope = nock("https://api.example.com")
  .replyContentLength()
  .replyDate(new Date("2023-01-01"))
  .get("/users")
  .reply(200, []);

Scope State Management

Completion Checking

interface Scope {
  done(): void;
  isDone(): boolean;
  pendingMocks(): string[];
  activeMocks(): string[];
}

done(): Asserts that all interceptors in this scope have been satisfied. Throws if any are pending.
isDone(): Returns true if all interceptors in this scope have been satisfied
pendingMocks(): Returns array of string descriptions of pending interceptors in this scope
activeMocks(): Returns array of string descriptions of active interceptors in this scope

Examples

const scope = nock("https://api.example.com")
  .get("/users")
  .reply(200, [])
  .post("/users")
  .reply(201, { id: 1 });

console.log(scope.isDone()); // false
console.log(scope.pendingMocks()); // ["GET https://api.example.com:443/users", "POST https://api.example.com:443/users"]

// After making the GET request
console.log(scope.pendingMocks()); // ["POST https://api.example.com:443/users"]

// After making both requests
scope.done(); // Passes without throwing

Options Interface

interface Options {
  allowUnmocked?: boolean;
  reqheaders?: Record<string, RequestHeaderMatcher>;
  badheaders?: string[];
  filteringScope?: (scope: string) => boolean;
  encodedQueryParams?: boolean;
}

Option Details

allowUnmocked: Allow requests to this scope that don't match any interceptor to pass through to the real server
reqheaders: Require specific headers to be present in requests
badheaders: Headers that must NOT be present in requests
filteringScope: Function to filter/transform the scope string for matching
encodedQueryParams: Whether query parameters should be matched in encoded form

Examples

// Allow unmatched requests to pass through
const scope = nock("https://api.example.com", { allowUnmocked: true })
  .get("/users")
  .reply(200, []);

// Require authentication header
const scope = nock("https://api.example.com", {
  reqheaders: {
    authorization: "Bearer token123"
  }
});

// Reject requests with certain headers
const scope = nock("https://api.example.com", {
  badheaders: ["x-debug-mode"]
});

Install with Tessl CLI

npx tessl i tessl/npm-nock

tessl/npm-nock