Scripting API

relay.response

The response a post-response script checks, with its status, headers and body.

Declaration

relay.response: Response | undefined

Overview

Post-response scripts only. In a pre-request script, relay.response is undefined. When a request fails without a response, such as when the server can't be reached, post-response scripts don't run.

const user = relay.response.json();

test("Returns the user", () => {
  relay.response.to.have.status(200);
  relay.response.to.have.header("Content-Type", /application\/json/);
  expect(user.email).toMatch(/@example\.com$/);
});

console.log(`Took ${relay.response.responseTime} ms`);

Responses that relay.sendRequest passes back have the same members.

Topics

Status

code

relay.response.code: number

The HTTP status code, such as 200.

status

relay.response.status: string

The status text, such as "OK".

reason()

relay.response.reason(): string

Returns the status text, such as "OK".

Headers and cookies

headers

relay.response.headers: PropertyList

The response's headers, matched without regard to case. The list is read-only. See PropertyList.

cookies

relay.response.cookies: PropertyList

Cookies the response set. See relay.cookies.

Body

text()

relay.response.text(): string

Returns the body as text.

json(path)

relay.response.json(path?: string): any

Parses the body as JSON, throwing if it isn't valid. With a path such as "data.items[0].id", returns the value at that path, or undefined when there's none.

events()

relay.response.events(): { event: string, data: string, id: string | null, retry: number | null, time: number }[]

Returns a streamed response's server-sent events, or an empty array when the response didn't stream. time is the number of milliseconds after the stream opened that the event arrived.

dataURI()

relay.response.dataURI(): string

Returns the body as a Base64 data: URI with the response's MIME type.

Timing and size

responseTime

relay.response.responseTime: number

How long the response took to arrive, in milliseconds.

responseSize

relay.response.responseSize: number

The size of the response body, in bytes.

size()

relay.response.size(): { body: number, header: number, total: number }

Returns the body, header and total sizes, in bytes.

Assertions

to

relay.response.to: Assertion

Starts an assertion about the response, such as relay.response.to.have.status(200). See Response assertions.

Serialization

toJSON()

relay.response.toJSON(): object

Returns the response's code, status, header, responseTime and responseSize as a plain object.

Unsupported members

stream

relay.response.stream

Reading it throws an error. Use text(), or events() for an event stream.

Discussion

text(), json() and events() throw an error when the body or the events are larger than 50 MB. json() throws a JSONError that says when the body is empty.

status is the standard reason phrase for the status code, even when the server sent a different one.

See Also

  • expect: A function that starts a chai or Jest-style assertion about a value.
  • relay.request: The request being sent, which pre-request scripts can change.
  • Testing responses: Check responses automatically with tests and assertions.
  • Receiving server-sent events: Watch an event stream as it arrives, filter its events and stop it when you're done.