Skip to content
Mentoss

Extended Response Patterns

The second argument of any route method in method in a MockServer instance is the response pattern. This pattern can be a number (the HTTP status to return), an object specifying additional data to return with the response, or a function. This is helpful when you’re making requests that expect a specific response format.

Extended response pattern keys

The following keys can be used in the response pattern object:

  • status (required) - the HTTP status code to return.
  • headers - HTTP headers to return with the response.
  • body - the body of the response to return. This can be a string, an object (which is treated as JSON), or an ArrayBuffer.
  • delay - the number of milliseconds to wait before returning the response.

The response pattern keys are used to create a new Response object that is returned when the associated request pattern matches the request.

Respond with a specific status code

If you’d like to respond to a request with a specific status code, you can use the status key in the response pattern object. Here’s an example:

import { MockServer } from "mentoss";


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


server.get("/users", {
  status: 200,
});

This route will respond to any GET request to /users with a status code of 200. Of course, if you are only returning a status code, you can pass the status code as the second argument to the route method:

server.get("/users", 200);

Respond with specific headers

If you’d like to respond to a request with specific headers, you can use the headers key in the response pattern object. Here’s an example that simulates a redirect:

import { MockServer } from "mentoss";


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


server.get("/redirect", {
  status: 301,
  headers: {
    Location: "https://example.com",
  },
});

This route will respond to any GET request to /redirect with a status code of 301 and a Location header that redirects the client to https://example.com.

Respond with a specific body

If you’d like to respond to a request with a specific body, you can use the body key in the response pattern object. Here’s an example:

import { MockServer } from "mentoss";


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


server.get("/users", {
  status: 200,
  body: {
    id: 123,
    name: "Alice",
  },
});

This route will respond to any GET request to /users with a status code of 200 and a JSON response body containing an id and name property. There’s no need to call JSON.stringify on the object; Mentoss will handle that for you.

Respond with a specific body and headers

You can combine the headers and body keys in the response pattern object to respond to a request with specific headers and a specific body. Here’s an example:

import { MockServer } from "mentoss";


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


server.get("/users", {
  status: 200,
  headers: {
    "Content-Type": "application/json",
  },
  body: {
    id: 123,
    name: "Alice",
  },
});

This route will respond to any GET request to /users with a status code of 200, a Content-Type header of application/json, and a JSON response body containing an id and name property.

Delay the response

If you’d like to delay the response to a request, you can use the delay key in the response pattern object. The delay property is the number of milliseconds to wait before returning the response. Here’s an example:

import { MockServer } from "mentoss";


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


server.get("/users", {
  status: 200,
  delay: 1000, // delay the response by 1 second
});

This route will respond to any GET request to /users with a status code of 200, but it will wait for 1 second before returning the response.

Use functions for dynamic responses

If you’d like to respond to a request with a dynamic value, you can use a function as the response pattern. The function will receive the request object as its only argument and should return a response pattern object. Here’s an example:

import { MockServer } from "mentoss";


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


server.get("/users/123", request => {


  console.log(`Received request: ${request.id}`);


  return {
    status: 200,
    body: {
      id: "123",
      name: "Alice",
    },
  };
});

This route will respond to any GET request to /users/123 with a status code of 200 and a JSON response body containing an id and name property. The response is generated dynamically based on the request object. The request object contains information about the request, such as the URL, headers, and body, and contains an additional id property that is a unique identifier for the request.

Response creator functions can also by asynchronous, so you can use await to wait for a promise to resolve before returning the response pattern object. Here’s an example:

import { MockServer } from "mentoss";


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


server.get("/users/123", async request => {
  await new Promise(resolve => setTimeout(resolve, 1000));


  return {
    status: 200,
    body: {
      id: "123",
      name: "Alice",
    },
  };
});

This route will respond to any GET request to /users/123 with a status code of 200 and a JSON response body containing an id and name property, but it will wait for 1 second before returning the response. You can use this to simulate network latency or other asynchronous behavior when the delay key is not sufficient.

Access request context in response creators

Response creator functions receive a second argument that provides access to additional request context information. This object contains:

  • cookies - A Map containing any cookies sent with the request
  • params - An object containing any URL parameters matched in the route pattern
  • query - A URLSearchParams object containing any query string parameters

Here’s an example showing how to use this context:

import { MockServer } from "mentoss";


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


// Match URLs like /users/123
server.get("/users/:id", (request, { cookies, params, query }) => {


    // Access cookies
    const sessionId = cookies.get("sessionId");


    // Access URL parameters
    const userId = params.id;


    // Access query string parameters
  const format = query.get("format") ?? "json";


    return {
        status: 200,
        body: {
            userId,
            sessionId,
            format
        }
    };
});

The context argument makes it easy to implement realistic API behaviors that depend on these request details.