API Mock Testing With Nock in Node.js

What Is Nock and Why It Matters

Testing code that makes HTTP calls presents a unique challenge in modern web development. External services can be slow, unreliable, or cost money per request. Nock, an HTTP server mocking library designed specifically for Node.js, intercepts requests before they leave your process, enabling complete test isolation with predictable, fast execution.

Unlike browser-based mocking solutions or service virtualization platforms, Nock operates at the Node.js HTTP level, providing complete control over request and response details, the ability to simulate network conditions, and deterministic test execution that runs in milliseconds rather than seconds or minutes.

When building applications with frameworks like Next.js, where server-side rendering and API routes are fundamental to performance and SEO strategies, having predictable test execution becomes crucial. Nock allows you to simulate various API scenarios--success responses, error conditions, network timeouts, rate limiting--ensuring your code handles every outcome gracefully.

According to the Nock GitHub Repository, the library provides flexible, expressive APIs that mirror HTTP protocol structure while offering powerful features like request body matching, header verification, and response body customization.

Installation and Setup

Getting started with Nock is straightforward, with support for all major Node.js package managers:

npm install nock
# or
yarn add nock
# or
pnpm add nock
# or
bun add nock

After installation, importing Nock into your test files follows standard JavaScript module patterns. The library supports both ES6 imports and CommonJS require syntax, ensuring compatibility regardless of your project's module system configuration. For teams working with TypeScript, the library provides excellent type definitions that integrate seamlessly with modern IDEs--check out our guide on comparing TypeScript IDEs to set up your development environment for optimal testing workflows.

Nock requires Node.js version 14 or higher and works seamlessly with modern build tools including Webpack, Vite, and Rollup. TypeScript users will be pleased to discover that type definitions are included directly in the package, providing full IDE support without additional installation steps.

The library's dependencies--propagate, @mswjs/interceptors, and json-stringify-safe--handle the low-level work of request interception and response generation. These dependencies are managed automatically during installation and shouldn't require direct attention in most use cases. The MIT license ensures Nock can be used freely in commercial and open-source projects alike.

Before diving into mock definitions, understanding Nock's configuration options helps ensure your tests run reliably. The enableNetConnect option, when set to false, throws an error if your code attempts to make an HTTP request that hasn't been mocked--catching test suite misconfigurations early and preventing tests from accidentally hitting real services instead of your mocks.

For Next.js applications built with our team, we typically configure Nock in the test setup file to prevent real network calls during unit tests while allowing selective network access for integration tests.

Basic Mocking Patterns

The fundamental Nock workflow involves defining a mock--intercepting a specific URL pattern and specifying the response to return. At its simplest, a mock requires the base URL, HTTP method, and response body.

Simple GET Requests

nock('https://api.example.com')
 .get('/users/123')
 .reply(200, {
 id: 123,
 name: 'John Doe',
 email: '[email protected]'
 });

This mock intercepts any GET request to https://api.example.com/users/123 and returns the specified JSON response with a 200 status code. Your application code can then make the API call as normal, receiving the mocked response without any network involvement.

Error Response Simulation

nock('https://api.example.com')
 .get('/users/999')
 .reply(404, {
 error: 'User not found',
 message: 'No user exists with ID 999'
 });

Beyond simple success responses, Nock excels at simulating error conditions that are difficult to trigger with real services. Simulating a 404 error ensures your error handling code works correctly, while 500 errors test your application's resilience to server failures.

Simulating Network Latency

nock('https://api.example.com')
 .get('/users')
 .delay(2000) // 2 second delay
 .reply(200, users);

Response timing is another powerful tool Nock provides. The .delay() method simulates network latency, helping you test loading states and timeout handling in your application. This pattern proves particularly valuable for Next.js applications where loading states affect user experience and SEO metrics. By simulating slow API responses, you can verify your loading skeletons, suspense fallbacks, and timeout logic function as expected.

As demonstrated in the LogRocket guide on API mock testing, these basic patterns form the foundation for comprehensive API testing strategies.

Request Matching and Verification

Real-world API interactions often involve headers, query parameters, and request bodies. Nock provides rich matching capabilities to ensure your mocks accurately represent the requests your application sends.

Query Parameter Matching

nock('https://api.example.com')
 .get('/users')
 .query({ page: 1, limit: 10 })
 .reply(200, { users: [...], total: 100 });

Header Matching

nock('https://api.example.com')
 .get('/users')
 .matchHeader('Authorization', 'Bearer valid-token')
 .matchHeader('Accept', 'application/json')
 .reply(200, users);

Request Body Matching

nock('https://api.example.com')
 .post('/users', {
 name: 'John Doe',
 email: '[email protected]'
 })
 .reply(201, { id: 123, ...userData });

For scenarios where exact matching isn't appropriate--such as generating unique IDs or timestamps--Nock provides match functions that receive the actual value and return whether it matches expectations. This flexibility enables testing complex validation logic without strict equality requirements. When working with array data filtering in your tests, understanding array filter methods in JavaScript can help you construct precise matching logic for your mock responses.

Request Verification

const scope = nock('https://api.example.com')
 .post('/users', { name: 'John' })
 .reply(201, { id: 123 });

// After your test, verify the request was made
scope.done(); // Throws if request wasn't made

Nock isn't only about defining responses--it also tracks whether mocked endpoints were actually called. The scope.done() call ensures all expectations defined on that scope were satisfied. If your application failed to make the expected request--perhaps due to a validation bug or conditional logic--the test fails immediately. This pattern prevents subtle bugs where code paths bypass API calls entirely.

For more granular verification, you can inspect the scope object after your test runs to check intercepted requests and request counts, as documented in the Nock GitHub Repository.

Advanced Features and Techniques

Moving beyond basic mocking, Nock's advanced features enable sophisticated testing scenarios that closely simulate production environments.

Rate Limiting Simulation

nock('https://api.example.com')
 .get('/data')
 .reply(429, {
 error: 'Too Many Requests',
 retryAfter: 60
 })
 .get('/data')
 .reply(200, { data: 'success' });

This pattern tests your retry logic thoroughly, ensuring your application handles rate-limited responses correctly by waiting before retrying. Combined with .delay(), you can simulate the full retry-with-backoff experience your users might encounter.

Persisting Mocks

nock('https://api.example.com')
 .get('/health')
 .reply(200, { status: 'ok' })
 .persist(); // Remains active across multiple requests

The .persist() method creates a mock that remains active across multiple requests, suiting health check endpoints or static resources that your application polls repeatedly. Without persistency, Nock mocks consume themselves after a single match, requiring redefinition for each request.

Dynamic Response Generation

nock('https://api.example.com')
 .get(/\/users\/\d+/)
 .reply((uri) => {
 const id = uri.match(/\/users\/(\d+)/)[1];
 const user = mockUsers.find(u => u.id === parseInt(id));
 return user ? [200, user] : [404, { error: 'Not found' }];
 });

For advanced scenarios, Nock allows dynamic response generation using functions. This approach is particularly useful when testing with large datasets or when responses need to vary based on the request parameters. As noted in the Generalist Programmer Nock Guide, this flexibility makes Nock suitable for virtually any mocking scenario in Node.js applications.

When implementing these patterns in enterprise applications, we often create centralized mock factories that encapsulate complex mocking logic for reuse across test suites. For applications that leverage AI-powered features, combining Nock with AI automation services can help you test complex multi-step workflows without external dependencies.

Performance Considerations

One of Nock's most significant advantages is test execution speed. By eliminating network latency, tests that might take seconds with real API calls complete in milliseconds. This speed enables testing strategies that would otherwise be impractical.

Performance Best Practices

• Use nock.cleanAll() between tests to prevent mock accumulation
• Define mocks in beforeAll hooks when possible rather than individual tests
• Use regular expressions for URL matching instead of multiple specific mocks
• Disable Nock entirely for unit tests that don't make HTTP calls

// Clean up between tests
afterEach(() => {
 nock.cleanAll();
});

Performance Benchmarking

it('completes user fetch in under 50ms', async () => {
 const start = performance.now();

 nock('https://api.example.com')
 .get('/users')
 .reply(200, users);

 await fetchUsers();

 const duration = performance.now() - start;
 expect(duration).toBeLessThan(50);
});

Consider measuring test suite performance to quantify Nock's impact. This pattern ensures tests remain fast over time and catches regressions that might introduce unnecessary latency. As covered in the LogRocket performance guide, well-organized mocks can reduce test suite execution time by orders of magnitude compared to live API calls.

For large-scale applications with extensive test suites, these optimizations compound significantly--potentially reducing CI/CD pipeline times from hours to minutes while improving test reliability.

Best Practices and Common Patterns

Effective Nock usage follows established patterns that maximize test reliability and maintainability.

Always Clean Up

// Good: Clean up after each test
afterEach(() => {
 nock.cleanAll();
});

Failing to clean up mocks between tests causes hard-to-diagnose failures. The nock.cleanAll() function removes all active mocks, preventing interference between tests.

Use Descriptive Mock Names

const userApi = nock('https://api.example.com')
 .get('/users')
 .reply(200, users);

userApi.done(); // Clear error message on failure

When debugging test failures, descriptive scopes help identify which mocks failed and why.

Test Both Success and Failure Paths

it('handles 404 errors', async () => {
 nock('https://api.example.com')
 .get('/users/999')
 .reply(404, { error: 'Not found' });

 await expect(fetchUser(999)).rejects.toThrow('User not found');
});

Comprehensive test coverage includes error scenarios. Don't just test happy paths--verify your code handles edge cases and error conditions correctly.

Centralized Mock Definition

Create a dedicated module for mock definitions:

// mocks/api.js
export function setupUserMocks() {
 nock('https://api.example.com')
 .get('/users')
 .reply(200, mockUsers);
}

Defining all mocks in a dedicated module promotes consistency and reduces duplication. Your test files then import and activate these mocks, ensuring consistent mock data across tests and simplifying updates when API responses change. This approach is essential for maintaining test reliability in production applications.

Integrating With Testing Frameworks

Nock works seamlessly with all major Node.js testing frameworks including Jest, Mocha, and Vitest.

Jest Configuration

// jest.setup.js
beforeAll(() => {
 nock.disableNetConnect();
});

afterAll(() => {
 nock.restore();
});

Jest requires no special configuration for Nock, but setup files help ensure consistent behavior across your test suite. The disableNetConnect() method prevents real network calls by default, catching tests that accidentally make unmocked requests.

React Testing Library

import { render, screen, waitFor } from '@testing-library/react';

it('displays user data after loading', async () => {
 nock('https://api.example.com')
 .get('/users/123')
 .reply(200, { name: 'Alice', email: '[email protected]' });

 render(<UserProfile userId="123" />);

 await waitFor(() => {
 expect(screen.getByText('Alice')).toBeInTheDocument();
 });
});

Nock works with React Testing Library, Vue Test Utils, and other component testing utilities. By mocking API responses at the HTTP level, you can test component behavior without relying on external services. When testing React applications with large lists, consider combining Nock with React windowing techniques to optimize both your test performance and runtime rendering.

Environment-Specific Configuration

Next.js applications often distinguish between server-side and client-side code, each with different testing requirements. Organize mocks by environment to prevent client-side code from accidentally accessing mocks intended only for server contexts and vice versa.

This integration approach ensures your testing strategy scales with your application complexity while maintaining the speed and reliability benefits of mock testing.

Common Pitfalls and Solutions

Even experienced developers encounter challenges with Nock. Here are the most common issues and their solutions.

Request Not Being Mocked

Problem: "Nock: No match for request"

Solution: Verify query parameters and headers match exactly

// Solution: Include query parameters
nock('https://api.example.com')
 .get('/users')
 .query({ page: 1, limit: 10 })
 .reply(200, users);

When tests fail with "Nock: No match for request," check that your mock definition matches exactly what your application sends--including query parameters, headers, and request body.

Mocks Consumed After Single Use

Solution: Use .persist() for multiple matches

nock('https://api.example.com')
 .get('/users')
 .reply(200, users)
 .persist();

Each Nock mock matches once by default. If your code makes multiple requests to the same endpoint, use .persist() to allow repeated matches.

Real Requests Leaking Through

Solution: Check URL protocol (http vs https)

nock('https://api.example.com') // vs http://api.example.com

When enableNetConnect is false but real requests succeed, Nock isn't intercepting correctly. The most common cause is a protocol mismatch between your mock and the actual request.

Interference Between Tests

Solution: Clean up between tests

afterEach(() => {
 nock.cleanAll();
});

Tests can affect each other through shared Nock scope. Always clean up between tests to ensure test isolation and prevent hard-to-diagnose failures.

As documented in the Generalist Programmer troubleshooting guide, these patterns cover the majority of issues developers encounter when starting with Nock.

Sources

1. LogRocket: API mock testing with Nock for Node.js apps - Comprehensive tutorial on using Nock for mocking HTTP requests in Node.js applications
2. Nock GitHub Repository - Official repository with documentation, examples, and API reference
3. Generalist Programmer: Nock Guide - Installation guide, best practices, and use cases for Nock