Testing responses
Check responses automatically with tests and assertions.
Overview
Tests turn the checks you'd make by eye into code that runs every time you send a request. You write them in a post-response script, and Relay shows the results in the response inspector's Tests tab: which tests passed, which failed and why.
A test is a named function that passes when it runs without an error. Inside it, you make assertions with expect, which combines chai's assertions, Jest's matchers and checks written for responses. For quick checks that don't need a name, use assert outside a test.
Write a test
Call test with a name and a function, then make assertions inside the function. When an assertion fails, it throws an error, the test fails and the script carries on with the next test.
test("Status is 200", () => {
relay.response.to.have.status(200);
});
test("Returns JSON", () => {
relay.response.to.be.json;
relay.response.to.have.header("Content-Type", /application\/json/);
});
test("Responds within 500 ms", () => {
expect(relay.response.responseTime).toBeLessThan(500);
});pm.test and relay.test are the same function, so tests written for Postman run unchanged.
Check the response body
Read the body with relay.response.json(), or relay.response.text() for other formats, and check its values with expect. You can write assertions in chai's style or Jest's, whichever you prefer.
const body = relay.response.json();
test("Returns the requested user", () => {
expect(body.id).to.equal(relay.variables.get("userId"));
expect(body.email).to.match(/@example\.com$/);
expect(body.roles).to.include("admin");
});
test("Has a complete address", () => {
expect(body.address).toMatchObject({ country: "GB" });
expect(body.address).toHaveProperty("postcode");
});The response assertions check common things in one line:
relay.response.to.have.jsonBody("data.items");
relay.response.to.have.jsonBody("data.total", 3);
relay.response.to.have.body(/Welcome/);
relay.response.to.be.success;
relay.response.to.not.be.error;For every assertion, see expect.
Validate a JSON schema
To check the shape of a whole response, describe it with a JSON Schema and assert that the body matches. Relay validates with Ajv, using JSON Schema draft-07, and the failure message lists every mismatch.
const schema = {
type: "object",
required: ["id", "name", "price"],
properties: {
id: { type: "string" },
name: { type: "string" },
price: { type: "number", minimum: 0 },
tags: { type: "array", items: { type: "string" } }
}
};
test("Product matches the schema", () => {
relay.response.to.have.jsonSchema(schema);
});Test something asynchronous
When a test's function is async, or returns a promise, the test passes when the promise resolves and fails when it rejects. Relay waits for every async test before the script finishes.
test("The new order can be fetched", async () => {
const { id } = relay.response.json();
const order = await relay.sendRequest({
url: relay.variables.replaceIn(`{{baseUrl}}/orders/${id}`),
header: { Authorization: relay.variables.replaceIn("Bearer {{token}}") }
});
expect(order.code).toBe(200);
expect(order.json().status).toBe("pending");
});A test function that takes a parameter receives a done function, as in Postman, and finishes when you call it.
Skip a test
To keep a test in the script without running it, use test.skip. It appears in the results as skipped.
test.skip("Returns pagination links", () => {
relay.response.to.have.jsonBody("links.next");
});Make assertions outside a test
Outside a test, assert records each check as a row in the Assertions section of the Tests tab, and a failed check doesn't stop the script. This suits a list of quick checks:
assert.equal(relay.response.code, 200);
assert.isArray(relay.response.json().items, "Items is an array");
assert.isBelow(relay.response.responseTime, 1000);A row is named after the message you pass, or else after its line of the script. Inside a test, assert fails the test like expect does. After an await in an async test, assert records a row instead, so use expect in async tests.
Read the results
After you send the request, click Tests in the response inspector. The tab's name shows how many tests passed, such as 3/4, in red when one fails.
At the top of the tab, a red box lists any errors that stopped a script, and scripts that ran out of time. Below it are these sections:
- Tests: Each test, with whether it passed, failed or was skipped, how long it took and, for a failure, the reason.
- Assertions: The checks you made with
assertoutside a test. - Console: The messages scripts wrote with
console.logand its relatives, and Relay's warnings about them.
At the end of each row, a link names the request, folder or collection the script belongs to and the line. Click it to show that line in the script.
To show only some results, click the menu at the top left of the tab and choose All, Passed, Failed or Skipped. To see the failures at a glance, click the counts at the top right of the tab; in the Failures popover, click Show in List to filter the tab to them. To copy every result and the console output as text, click the Copy Results button.
Test results are kept with the response in history, so you can look back at them later.
Test every request in a collection
A post-response script on a collection or folder runs after each of its requests' responses, so you can write checks once for a whole API:
// Collection post-response script
test("Responds within a second", () => {
relay.response.to.have.responseTime(1000);
});
if (relay.response.headers.get("Content-Type")?.includes("json")) {
test("Returns valid JSON", () => {
relay.response.to.be.json;
});
}Each result's link shows which script it came from.
See Also
- test: A function that runs a named check and records whether it passed.
- expect: A function that starts a chai or Jest-style assertion about a value.
- assert: chai's assert functions, recorded as soft assertions outside a test.
- Inspecting responses: Read a response's status, body and headers, and copy or save what you need.