Client

API Reference

Client

Registering a route handler

API Reference

Client.route

Registering a route handler allows you to intercept requests and modify the response in various ways via the Route class passed as an argument to the handler.

TypeScript

// Matching URL's with glob patterns
client.route("**/api", (route) => {
    return route.fulfill(...);
});

// Matching URL's with regular expressions
client.route(/^.*?\/api$/, (route) => {
    return route.fulfill(...);
});

// Matching URL's with a custom function
client.route((url: URL) => {
    return url.pathname.startsWith("/api");
}, (route) => {
    return route.fulfill(...);
});

JavaScript

// Matching URL's with glob patterns
client.route("**/api", (route) => {
    return route.fulfill(...);
});

// Matching URL's with regular expressions
client.route(/^.*?\/api$/, (route) => {
    return route.fulfill(...);
});

// Matching URL's with a custom function
client.route((url) => {
    return url.pathname.startsWith("/api");
}, (route) => {
    return route.fulfill(...);
});

Mock n times

API Reference

Client.route

The route handler will be removed once its been executed n times.

TypeScript

// Once the route handler is matched 3 times it will be removed from the client
client.route("**/api", (route) => {
  return route.fulfill(...);
}, { times: 3 });

JavaScript

// Once the route handler is matched 3 times it will be removed from the client
client.route("**/api", (route) => {
  return route.fulfill(...);
}, { times: 3 });

Mock client and server side requests (default behaviour)

API Reference

Client.route

RouteOptions.type defaults to "both" when not explicitly set.

TypeScript

// The route handler will handle requests that originate from the client or server side
client.route("**/api", (route) => {
  return route.fulfill(...);
}, { type: "both" });

JavaScript

// The route handler will handle requests that originate from the client or server side
client.route("**/api", (route) => {
  return route.fulfill(...);
}, { type: "both" });

Only mock server side requests

API Reference

Client.route

Setting RouteOptions.type to "server-only" will only mock server side requests. This is useful if you differentiate between client and server side requests. For example, authentication strategies can be different between client and server side.

TypeScript

// The route handler will handle requests that originate from the server only
client.route("**/api", (route) => {
  return route.fulfill(...);
}, { type: "server-only" });

JavaScript

// The route handler will handle requests that originate from the server only
client.route("**/api", (route) => {
  return route.fulfill(...);
}, { type: "server-only" });

Only mock client side requests

API Reference

Client.route

Setting RouteOptions.type to "client-only" will only mock client side requests. This is useful if you differentiate between client and server side requests. For example, authentication strategies can be different between client and server side.

This is the equivalent of Playwright's page.route or Cypress' cy.intercept. This is a convenient interface that allows you to mock requests across the stack without having to call different functions.

TypeScript

// The route handler will handle requests that originate from the client (browser) only
client.route("**/api", (route) => {
  return route.fulfill(...);
}, { type: "client-only" });

JavaScript

// The route handler will handle requests that originate from the client (browser) only
client.route("**/api", (route) => {
  return route.fulfill(...);
}, { type: "client-only" });

Unregistering a route handler

API Reference

Client.unroute

If you want to disable a route handler, you can use the unroute method:

TypeScript

const routeHandlerId = client.route("**/api", (route) => {
    return route.fulfill(...);
});

client.unroute(routeHandlerId);

JavaScript

const routeHandlerId = client.route("**/api", (route) => {
    return route.fulfill(...);
});

client.unroute(routeHandlerId);

Unregistering all route handlers

API Reference

Client.unrouteAll

Used to unregister all route handlers registered on the client.

TypeScript

client.unrouteAll();

JavaScript

client.unrouteAll();

Waiting for a request

API Reference

Client.waitForRequest

When you need to wait for a request to be made, you can use client.waitForRequest.

tip

Use client.waitForRequest to assert on the request being sent on the server.

TypeScript

const requestPromise = client.waitForRequest("**/api");

// Run code that triggers the request, i.e. loading a page

// Await the request
const request = await requestPromise;

// Assert on the request
expect(request.headers.get("Authorization")).toBeDefined();

JavaScript

const requestPromise = client.waitForRequest();

// Run code that triggers the request, i.e. loading a page

// Await the request
const request = await requestPromise;

// Assert on the request
expect(request.headers.get("Authorization")).toBeDefined();

Waiting for a request on the client only or the server only

API Reference

Client.waitForRequest

Similar to Client.route you can scope waiting for requests to the client, server, or both. The default behavior is to wait for requests on both the client and the server. The resolved request is the first request to be made.

TypeScript

const requestPromise = client.waitForRequest("**/api", {
  // Allows you to scope waiting for requests to the client, server, or both.
  // "server-only" | "client-only" | "both"
  type: "client-only",
});

// Run code that triggers the request, i.e. loading a page

// Await the request
const request = await requestPromise;

// Assert on the request
expect(request.headers.get("Authorization")).toBeDefined();

JavaScript

const requestPromise = client.waitForRequest();

// Run code that triggers the request, i.e. loading a page

// Await the request
const request = await requestPromise;

// Assert on the request
expect(request.headers.get("Authorization")).toBeDefined();