Scripting API

test

A function that runs a named check and records whether it passed.

Declaration

test(name: string, fn?: (done?: Function) => any): relay
relay.test(name: string, fn?: (done?: Function) => any): relay

Overview

A test runs fn and records a result under its name in the Tests section of the response inspector's Tests tab. The test passes when fn returns without throwing, and fails when it throws, such as when an expect assertion inside it fails. Tests work in both phases, but most belong in a post-response script.

test("Status is 200", () => {
  relay.response.to.have.status(200);
});

test("Lists at least one order", () => {
  const { orders } = relay.response.json();
  expect(orders.length).toBeGreaterThan(0);
});

Parameters

Prop

Type

Return Value

The relay object, so you can chain another call such as .test(…).

Topics

Skipping tests

skip(name, fn)

test.skip(name: string, fn?: Function): relay

Lists a test as skipped without running it.

Discussion

Async tests

When fn returns a promise, such as when it's an async function, the test finishes when the promise settles: it passes when the promise resolves and fails when it rejects. A script isn't finished until its async tests have finished.

test("The order can be fetched", async () => {
  const id = relay.response.json().id;
  const order = await relay.sendRequest(relay.variables.replaceIn(`{{baseUrl}}/orders/${id}`));
  expect(order.code).toBe(200);
});

When fn takes a parameter, Relay passes it a done function, as in Postman and Mocha. The test finishes when you call done(), and fails if you pass it an error.

Results

Each result shows its name, whether it passed, failed or was skipped, how long it took, and for a failure, the error's message. A link at the end of the row shows the line in the script that called test. Relay keeps up to 1,000 results from each phase.

A test failing doesn't stop the script: the code after the test call still runs. An error thrown outside a test does stop the script.

Legacy tests object

Postman's older tests object also records results. Assigning tests["Status is 200"] = responseCode.code === 200 records a test that passes when the value is truthy.

See Also

  • 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.
  • Testing responses: Check responses automatically with tests and assertions.