Testing Helpers: Fetch Mocker

The fetch mocker provides several methods to help verify that your requests were made as expected.

Verifying Route Calls

Tracking which routes have been called is a key part of many tests. The fetch mocker provides several methods and properties to help with this.

allRoutesCalled()

The allRoutesCalled() method checks if all routes have been called on all servers. It returns true if all routes have been called at least once, and false otherwise:

import { MockServer, FetchMocker } from "mentoss";

const server1 = new MockServer("https://api1.example.com");
const server2 = new MockServer("https://api2.example.com");
const mocker = new FetchMocker({ servers: [server1, server2] });

server1.get("/users", 200);
server2.post("/users", 200);

console.log(mocker.allRoutesCalled()); // false

await mocker.fetch("https://api1.example.com/users");
console.log(mocker.allRoutesCalled()); // false

await mocker.fetch("https://api2.example.com/users", { method: "POST" });
console.log(mocker.allRoutesCalled()); // true

In this example, the allRoutesCalled() method first returns false because neither the GET nor the POST /users route has been called yet. After both routes have been called, the method returns true.

assertAllRoutesCalled()

The assertAllRoutesCalled() method is an assertion that checks if all routes have been called. It throws an error if any routes have not been called:

import { MockServer, FetchMocker } from "mentoss";

const server1 = new MockServer("https://api1.example.com");
const server2 = new MockServer("https://api2.example.com");
const mocker = new FetchMocker({ servers: [server1, server2] });

server1.get("/users", 200);
server2.post("/users", 200);

await mocker.fetch("https://api1.example.com/users");
server.assertAllRoutesCalled(); // Error!

The thrown error contains a message with information about the uncalled routes.

called()

The called() method checks if a specific route has been called. You can pass either a URL string (which defaults to a GET request) or a request pattern object:

import { MockServer, FetchMocker } from "mentoss";

const server1 = new MockServer("https://api1.example.com");
const server2 = new MockServer("https://api2.example.com");
const mocker = new FetchMocker({ servers: [server1, server2] });

server1.post(
  {
    url: "/users",
    body: {
      name: "John Doe",
    },
  },
  200,
);

console.log(mocker.called("https://api1.example.com/users")); // false

await mocker.fetch("https://api1.example.com/users", {
    method: "POST",
    body: {
        name: "John Doe",
    },
});

console.log(mocker.called("https://api1.example.com/users")); // true

console.log(mocker.called({
    url: "https://api1.example.com/users",
    method: "POST",
    body: {
        name: "John Doe",
    },
})); // true

In this example, the called() method returns false because the /users route has not been called yet. The matching is done using the same comparison logic as if a fetch() request was made to the route.

uncalledRoutes

The uncalledRoutes property returns an array with information about uncalled routes. You can use this property to check if any routes have not been called:

import { MockServer, FetchMocker } from "mentoss";

const server1 = new MockServer("https://api1.example.com");
const server2 = new MockServer("https://api2.example.com");
const mocker = new FetchMocker({ servers: [server1, server2] });

server1.get("/users", 200);
server2.post("/users", 200);

await mocker.fetch("https://api1.example.com/users");

console.log(mocker.uncalledRoutes); // ["🚧 [Route: POST https://api2.example.com/users -> 200]"]

The uncalledRoutes property is helpful when you want to format your own error messages or assertions.

Tip

The MockServer class also supports allRoutesCalled(), assertAllRoutesCalled(), and called() methods, as well as the uncalledRoutes property. These methods and property work similarly to the FetchMocker equivalents except they only check routes on the given server.

Additional Helpers

clearAll()

The clearAll() method removes all routes from all servers so you can reuse the same server for multiple tests.

import { MockServer, FetchMocker } from "mentoss";

const server1 = new MockServer("https://api1.example.com");
const server2 = new MockServer("https://api2.example.com");
const mocker = new FetchMocker({ servers: [server1, server2] });

server1.get("/users", 200);
server2.post("/users", 200);

mocker.clearAll();

await mocker.fetch("https://api1.example.com/users"); // Error!