Skip to main content

createHttpInterceptor

Creates an HTTP interceptor. All requests and responses are typed by default with a schema, including methods, paths, status codes, arguments, and bodies.

createHttpInterceptor<Schema>(options);

Arguments:

  1. options: HttpInterceptorOptions

    The options to create an HTTP interceptor.

    • type: 'local' | 'remote' | undefined (default: 'local')

      The type of the HTTP interceptor, either local or remote.

    • baseURL: string

      Represents the URL that should be matched by the interceptor. Any request starting with this base URL will be intercepted if a matching handler exists. For remote interceptors, this base URL should point to an interceptor server, optionally including path discriminators.

    • requestSaving: Partial<HttpInterceptorRequestSaving> | undefined

      Configures if the intercepted requests are saved and how they are handled.

      • enabled: boolean | undefined (default: process.env.NODE_ENV === 'test')

        Whether request handlers should save their intercepted requests in memory and make them accessible through handler.requests.

        If you are using interceptor.checkTimes() or handler.checkTimes() during tests, consider enabling this option to get more detailed information in TimesCheckError errors.

        INFO: Clearing the interceptor when saving requests

        If request saving is enabled, make sure to regularly clear the interceptor to avoid requests accumulating in memory. A common practice is to call interceptor.clear() after each test.

      • safeLimit: number | undefined (default: 1000)

        The safe number of requests to save in memory before logging warnings in the console. If requestSaving.enabled is true and the interceptor is not regularly cleared with interceptor.clear(), the requests may accumulate in memory and cause performance issues. This option does not limit the number of requests saved in memory, only when to log warnings.

    • onUnhandledRequest: UnhandledRequestStrategy | undefined

      The strategy to use for unhandled requests. If a request starts with the base URL of the interceptor, but no matching handler exists, this strategy will be used. If a function is provided, it will be called with the unhandled request.

      • action: 'bypass' | 'reject'

        The action to take when an unhandled request is intercepted. When set to 'bypass', the request will be allowed to pass through and reach the real network. When set to 'reject', the request will be rejected with a network error. Local interceptor can use bypass or reject, while remote interceptors only support reject, since unhandled requests that reach an interceptor server cannot be bypassed.

      • log: boolean (default: true)

        Whether to log unhandled requests to the console.

    • auth: HttpInterceptorAuthOptions | undefined

      The options to authenticate a remote interceptor when connecting to an interceptor server. This is required if the interceptor server was started with the --tokens-dir option.

      • token: string

        The authentication token to use.

Type arguments:

  1. Schema: HttpSchema

    The HTTP schema to use for the interceptor.

Returns: HttpInterceptor<Schema>

An HTTP interceptor typed with the provided schema.

import { createHttpInterceptor } from '@zimic/interceptor/http';

const interceptor = createHttpInterceptor<Schema>({
  type: 'local',
  baseURL: 'http://localhost:3000',
});

Related: