Core route definition methods for mocking HTTP requests with flexible matching and response configuration. Routes are the fundamental building blocks of fetch-mock, defining how requests should be matched and what responses should be generated.
The primary method for defining routes with full configuration options.
/**
* Define a route that matches requests and generates responses
* @param matcher - URL pattern, function, or full route configuration
* @param response - Response definition (optional if matcher includes response)
* @param options - Additional configuration options
* @returns FetchMock instance for chaining
*/
route(matcher: RouteMatcher | UserRouteConfig, response?: RouteResponse, options?: UserRouteConfig | string): FetchMock;Usage Examples:
import fetchMock from "fetch-mock";
// Simple URL and response
fetchMock.route("https://api.example.com/users", { status: 200, body: [] });
// Configuration object approach
fetchMock.route({
url: "https://api.example.com/users",
method: "POST",
response: { status: 201, body: { id: 1 } },
name: "create-user"
});
// With additional options
fetchMock.route(
"https://api.example.com/data",
{ body: "success" },
{ method: "GET", repeat: 1 }
);Convenience methods for common HTTP verbs.
/**
* Mock GET requests
* @param matcher - URL pattern or matching criteria
* @param response - Response definition
* @param options - Additional configuration options
* @returns FetchMock instance for chaining
*/
get(matcher: RouteMatcher, response: RouteResponse, options?: UserRouteConfig | string): FetchMock;
/**
* Mock POST requests
* @param matcher - URL pattern or matching criteria
* @param response - Response definition
* @param options - Additional configuration options
* @returns FetchMock instance for chaining
*/
post(matcher: RouteMatcher, response: RouteResponse, options?: UserRouteConfig | string): FetchMock;
/**
* Mock PUT requests
* @param matcher - URL pattern or matching criteria
* @param response - Response definition
* @param options - Additional configuration options
* @returns FetchMock instance for chaining
*/
put(matcher: RouteMatcher, response: RouteResponse, options?: UserRouteConfig | string): FetchMock;
/**
* Mock DELETE requests
* @param matcher - URL pattern or matching criteria
* @param response - Response definition
* @param options - Additional configuration options
* @returns FetchMock instance for chaining
*/
delete(matcher: RouteMatcher, response: RouteResponse, options?: UserRouteConfig | string): FetchMock;
/**
* Mock HEAD requests
* @param matcher - URL pattern or matching criteria
* @param response - Response definition
* @param options - Additional configuration options
* @returns FetchMock instance for chaining
*/
head(matcher: RouteMatcher, response: RouteResponse, options?: UserRouteConfig | string): FetchMock;
/**
* Mock PATCH requests
* @param matcher - URL pattern or matching criteria
* @param response - Response definition
* @param options - Additional configuration options
* @returns FetchMock instance for chaining
*/
patch(matcher: RouteMatcher, response: RouteResponse, options?: UserRouteConfig | string): FetchMock;Usage Examples:
// HTTP method shortcuts
fetchMock.get("/api/users", [{ id: 1, name: "Alice" }]);
fetchMock.post("/api/users", { status: 201, body: { id: 2 } });
fetchMock.put("/api/users/1", { status: 200 });
fetchMock.delete("/api/users/1", { status: 204 });HTTP method shortcuts that match exactly once.
/**
* Mock GET requests that match exactly once
* @param matcher - URL pattern or matching criteria
* @param response - Response definition
* @param options - Additional configuration options
* @returns FetchMock instance for chaining
*/
getOnce(matcher: RouteMatcher, response: RouteResponse, options?: UserRouteConfig | string): FetchMock;
/**
* Mock POST requests that match exactly once
* @param matcher - URL pattern or matching criteria
* @param response - Response definition
* @param options - Additional configuration options
* @returns FetchMock instance for chaining
*/
postOnce(matcher: RouteMatcher, response: RouteResponse, options?: UserRouteConfig | string): FetchMock;
/**
* Mock PUT requests that match exactly once
* @param matcher - URL pattern or matching criteria
* @param response - Response definition
* @param options - Additional configuration options
* @returns FetchMock instance for chaining
*/
putOnce(matcher: RouteMatcher, response: RouteResponse, options?: UserRouteConfig | string): FetchMock;
/**
* Mock DELETE requests that match exactly once
* @param matcher - URL pattern or matching criteria
* @param response - Response definition
* @param options - Additional configuration options
* @returns FetchMock instance for chaining
*/
deleteOnce(matcher: RouteMatcher, response: RouteResponse, options?: UserRouteConfig | string): FetchMock;
/**
* Mock HEAD requests that match exactly once
* @param matcher - URL pattern or matching criteria
* @param response - Response definition
* @param options - Additional configuration options
* @returns FetchMock instance for chaining
*/
headOnce(matcher: RouteMatcher, response: RouteResponse, options?: UserRouteConfig | string): FetchMock;
/**
* Mock PATCH requests that match exactly once
* @param matcher - URL pattern or matching criteria
* @param response - Response definition
* @param options - Additional configuration options
* @returns FetchMock instance for chaining
*/
patchOnce(matcher: RouteMatcher, response: RouteResponse, options?: UserRouteConfig | string): FetchMock;Special route types for common patterns.
/**
* Create a route that matches exactly once
* @param matcher - URL pattern or matching criteria
* @param response - Response definition
* @param options - Additional configuration options
* @returns FetchMock instance for chaining
*/
once(matcher: RouteMatcher, response: RouteResponse, options?: UserRouteConfig | string): FetchMock;
/**
* Create a route that persists through removeRoutes() calls
* @param matcher - URL pattern or matching criteria
* @param response - Response definition
* @param options - Additional configuration options
* @returns FetchMock instance for chaining
*/
sticky(matcher: RouteMatcher, response: RouteResponse, options?: UserRouteConfig | string): FetchMock;
/**
* Match any URL (wildcard route)
* @param response - Response definition
* @param options - Additional configuration options
* @returns FetchMock instance for chaining
*/
any(response: RouteResponse, options?: UserRouteConfig | string): FetchMock;
/**
* Match any URL exactly once
* @param response - Response definition
* @param options - Additional configuration options
* @returns FetchMock instance for chaining
*/
anyOnce(response: RouteResponse, options?: UserRouteConfig | string): FetchMock;Usage Examples:
// One-time routes
fetchMock.getOnce("/api/users", { body: [] });
fetchMock.postOnce("/api/login", { status: 401 });
// Special route types
fetchMock.once("/api/temp", { body: "temporary" });
fetchMock.sticky("/api/health", { body: "ok" }); // Persists through reset
fetchMock.any({ status: 404 }); // Fallback for any unmatched URLDefault route for unmatched requests.
/**
* Define a fallback route for unmatched requests
* @param response - Response definition (defaults to empty 200 response)
* @returns FetchMock instance for chaining
*/
catch(response?: RouteResponse): FetchMock;Usage Examples:
// Default fallback
fetchMock.catch(); // Returns empty 200 response
// Custom fallback
fetchMock.catch({ status: 404, body: "Not found" });Routes that pass requests through to the network while recording call history.
/**
* Create a spy route that passes requests to the real network
* @param matcher - Optional URL pattern to spy on specific routes
* @param name - Optional route name for identification
* @returns FetchMock instance for chaining
*/
spy(matcher?: RouteMatcher | UserRouteConfig, name?: RouteName): FetchMock;Usage Examples:
// Spy on all requests
fetchMock.spy();
// Spy on specific URL
fetchMock.spy("https://api.example.com/analytics");
// Named spy route
fetchMock.spy("/api/logs", "log-spy");interface UserRouteConfig {
name?: string;
method?: string;
headers?: { [key: string]: string | number };
missingHeaders?: string[];
query?: { [key: string]: string };
params?: { [key: string]: string };
body?: object;
matcherFunction?: RouteMatcherFunction;
url?: RouteMatcherUrl;
response?: RouteResponse | RouteResponseFunction;
repeat?: number;
delay?: number;
waitFor?: RouteName | RouteName[];
sticky?: boolean;
includeContentLength?: boolean;
matchPartialBody?: boolean;
allowRelativeUrls?: boolean;
}
class RouteConfigWrapper implements UserRouteConfig {
constructor(config: UserRouteConfig);
}