Mentoss

When using CookieCredentials with FetchMocker, cookies are automatically included in requests if they meet these criteria:

1. Domain: The request domain must match or be a subdomain of the cookie's domain.
2. Path: The request path must match or be under the cookie's path.
3. Security: For cookies with secure: true, the request must use https.
4. SameSite: The request must match the cookie's sameSite policy (if set).

const credentials = new CookieCredentials("https://example.com");

credentials.setCookie({
    name: "adminSession",
    value: "xyz789",
    path: "/admin",
    secure: true
});

// MATCHES: domain, path, and protocol match
await fetch("https://example.com/admin/users");

// FAILS: wrong protocol (http instead of https)
await fetch("http://example.com/admin/users");

// FAILS: wrong path
await fetch("https://example.com/user/profile");

// MATCHES: subdomain is allowed
await fetch("https://sub.example.com/admin/users");

Mentoss matches incoming requests against registered routes by comparing request details in a specific order. When a match is found, the server returns a Response object; otherwise, it returns undefined.

Matching Priority Order:

1. Path: The URL path (e.g., /api/users).
2. Method: The HTTP method (e.g., GET, POST).
3. URL Parameters: Dynamic segments in the path (e.g., :id in /api/users/:id).
4. Query Parameters: The query string (e.g., ?id=123).
5. Headers: Request headers.
6. Body: The request body content.

Note on Query Parameters: If you do not explicitly provide a query object in your route definition, the server ignores all query parameters in the request. For example, a route for /api/users will match both /api/users and /api/users?sort=asc unless a query object is specified.

import { MockServer } from "mentoss";

const server = new MockServer("https://api.example.com");

// Matches any GET to /api/users/:id, ignoring query params
server.get("/api/users/:id", 200);

// Matches only GET to /api/users/:id if query param profile=full is present
server.get(
	{
		url: "/api/users/:id",
		query: {
			profile: "full",
		},
	},
	200,
);

Mentoss uses three primary abstractions to handle mocking:

1. MockServer: The core configuration object where you define your mocked routes, request matching criteria (URL, headers, body), and responses (status, body, headers).
2. FetchMocker: A utility used in browser or Node.js environments to create a new fetch() function that routes requests to one or more MockServer instances. It can also overwrite the global fetch via .mockGlobal().
3. MockAgent: An undici Dispatcher designed for Node.js. It intercepts undici requests and routes them to MockServer instances.

To use Mentoss, you typically define a MockServer first, then pass it to either a FetchMocker or a MockAgent depending on your runtime and HTTP client.

import { MockServer, FetchMocker } from "mentoss";

const server = new MockServer("https://api.example.com");
server.get("/foo/bar", 200);

const mocker = new FetchMocker({ servers: [server] });
const { fetch } = mocker;

For preflighted requests (e.g., requests with custom headers like Content-Type: application/json), Mentoss automatically sends an OPTIONS request before the actual request.

To mock this successfully, you must:

1. Define an OPTIONS route on your MockServer that returns the appropriate Access-Control-Allow-Origin and Access-Control-Allow-Headers.
2. Define the actual method route (e.g., GET, POST) with the same CORS headers.

If the OPTIONS response lacks the required headers, the original request will fail.

import { MockServer, FetchMocker } from "mentoss";

const BASE_URL = "https://api.example.com";

describe("My API", () => {
	const server = new MockServer("https://www.example.com");
	const mocker = new FetchMocker({
		servers: [server],
		baseUrl: BASE_URL,
	});

	const myFetch = mocker.fetch;

	it("should return a 200 status code", async () => {
		// Preflight request setup
		server.options("/ping", {
			status: 200,
			headers: {
				"Access-Control-Allow-Origin": BASE_URL,
				"Access-Control-Allow-Headers": "Content-Type",
			},
		});

		// Actual request setup
		server.get("/ping", {
			status: 200,
			headers: {
				"Access-Control-Allow-Origin": BASE_URL,
			},
			body: { message: "pong" },
		});

		const response = await myFetch("https://www.example.com/ping", {
			headers: {
				"Content-Type": "application/json",
			},
		});

		expect(response.status).to.equal(200);
	});
});

To mock fetch() calls, create a MockServer with a base URL, define your routes, and then use FetchMocker to generate a mocked fetch function or to overwrite the global one.

import { MockServer, FetchMocker } from "mentoss";

// 1. Create a server with a base URL
const server = new MockServer("https://api.example.com");

// 2. Define routes
// Simple route
server.get("/foo/bar", 200);

// Route with specific response body and headers
server.post("/foo/baz", {
	status: 200,
	body: { message: "Success" },
	headers: {
		"Content-Type": "application/json",
	},
});

// Route with advanced matching (URL, headers, and body)
server.post(
	{
		url: "/foo/boom",
		headers: {
			"Content-type": "application/json",
		},
		body: {
			test: true,
		},
	},
	404,
);

// 3. Create the mocker
const mocker = new FetchMocker({
	servers: [server],
});

// 4. Use the mocked fetch
const { fetch } = mocker;
// OR: mocker.mockGlobal();

const response = await fetch("https://api.example.com/foo/bar");

// 5. Assertions and cleanup
assert(mocker.called("https://api.example.com/foo/bar"));
assert(mocker.allRoutesCalled());

server.clear(); // Clears routes on the server
mocker.clearAll(); // Clears everything in the mocker