Scripting API

expect

A function that starts a chai or Jest-style assertion about a value.

Declaration

expect(value: any, message?: string): Assertion
relay.expect(value: any, message?: string): Assertion

Overview

expect is chai's expect, with Jest's matchers and Postman's response assertions added. An assertion that fails throws an error, so put assertions inside a test to record them as a result rather than stop the script.

test("Returns a page of users", () => {
  const body = relay.response.json();

  // chai style
  expect(body.users).to.be.an("array").that.is.not.empty;
  expect(body.page).to.equal(1);

  // Jest style
  expect(body.users[0]).toHaveProperty("email");
  expect(body.total).toBeGreaterThanOrEqual(body.users.length);
});

Pass message to put your own text at the start of the failure message. Every chai 4 assertion works, including ones not listed here.

Topics

Starting an assertion

expect(value, message)

expect(value: any, message?: string): Assertion

Starts an assertion about value.

expect.fail(message)

expect.fail(message?: string): never

Fails with message.

Chains and flags

Language chains

to be been is that which and has have with at of same but does still also

Chain words for readability, which don't change the assertion.

not

assertion.not: Assertion

Negates the assertions that follow.

deep

assertion.deep: Assertion

Makes the assertions that follow compare contents recursively instead of by identity.

nested

assertion.nested: Assertion

Lets the property and include assertions that follow use dotted paths.

own

assertion.own: Assertion

Makes the property and include assertions that follow ignore inherited properties.

ordered

assertion.ordered: Assertion

Makes the members assertion that follows require the same order.

any

assertion.any: Assertion

Makes the keys assertion that follows pass with at least one of the keys.

all

assertion.all: Assertion

Makes the keys assertion that follows require all of the keys and no others.

Value checks

ok

assertion.ok

Asserts that the value is truthy. For a response, asserts that its status is 200.

true, false, null, undefined, NaN

assertion.true
assertion.false
assertion.null
assertion.undefined
assertion.NaN

Asserts that the value is true, false, null, undefined or NaN.

exist

assertion.exist

Asserts that the value is neither null nor undefined.

empty

assertion.empty

Asserts that a string, array, map, set or object has no contents.

Comparisons

equal(value)

assertion.equal(value: any)

Asserts that the value === value, or has equal contents after deep.

eql(value)

assertion.eql(value: any)

Asserts that the value has contents equal to value, compared recursively.

include(value)

assertion.include(value: any)

Asserts that a string, array or object includes value. contain(value) does the same.

a(type)

assertion.a(type: string)

Asserts that the value's type is type, such as "string" or "array". an(type) does the same.

property(name, value)

assertion.property(name: string, value?: any)

Asserts that the value has the named property, equal to value when given.

lengthOf(length)

assertion.lengthOf(length: number)

Asserts that the value's length or size is length.

match(regexp)

assertion.match(regexp: RegExp)

Asserts that the value matches regexp.

string(text)

assertion.string(text: string)

Asserts that the string contains text.

keys(…keys)

assertion.keys(...keys: string[])

Asserts that the object has exactly the given keys, or some of them after any.

members(list)

assertion.members(list: any[])

Asserts that the array has the same members as list.

oneOf(list)

assertion.oneOf(list: any[])

Asserts that the value is one of the items in list.

above(number)

assertion.above(number: number)

Asserts that the value is greater than number.

below(number)

assertion.below(number: number)

Asserts that the value is less than number.

least(number)

assertion.least(number: number)

Asserts that the value is greater than or equal to number.

most(number)

assertion.most(number: number)

Asserts that the value is less than or equal to number.

within(start, finish)

assertion.within(start: number, finish: number)

Asserts that the value is between start and finish, inclusive.

closeTo(expected, delta)

assertion.closeTo(expected: number, delta: number)

Asserts that the value is within delta of expected.

instanceOf(constructor)

assertion.instanceOf(constructor: Function)

Asserts that the value is an instance of constructor.

satisfy(fn)

assertion.satisfy(fn: (value: any) => boolean)

Asserts that fn returns true for the value.

throw(error)

assertion.throw(error?: Error | Function | string | RegExp)

Asserts that the function throws, optionally a matching error.

Jest matchers

toBe(value)

expect(actual).toBe(value: any)

Expects the value to be value, compared with Object.is.

toEqual(value)

expect(actual).toEqual(value: any)

Expects the value to have contents equal to value, compared recursively and ignoring properties that are undefined.

toStrictEqual(value)

expect(actual).toStrictEqual(value: any)

Expects the value to equal value, also comparing undefined properties and types.

toContain(item)

expect(actual).toContain(item: any)

Expects a string or array to contain item.

toContainEqual(item)

expect(actual).toContainEqual(item: any)

Expects an array to contain an element with contents equal to item.

toBeTruthy(), toBeFalsy()

expect(actual).toBeTruthy()
expect(actual).toBeFalsy()

Expects the value to be truthy, or falsy.

toBeNull(), toBeUndefined(), toBeDefined(), toBeNaN()

expect(actual).toBeNull()
expect(actual).toBeUndefined()
expect(actual).toBeDefined()
expect(actual).toBeNaN()

Expects the value to be null, to be undefined, not to be undefined, or to be NaN.

toBeInstanceOf(constructor)

expect(actual).toBeInstanceOf(constructor: Function)

Expects the value to be an instance of constructor.

toHaveProperty(path, value)

expect(actual).toHaveProperty(path: string | string[], value?: any)

Expects the object to have a property at path, such as "data.items[0].id", equal to value when given.

toMatch(pattern)

expect(actual).toMatch(pattern: RegExp | string)

Expects the string to match a regular expression or contain a string.

toMatchObject(object)

expect(actual).toMatchObject(object: object)

Expects the object to contain object's properties, compared recursively.

toBeGreaterThan(number), toBeGreaterThanOrEqual(number)

expect(actual).toBeGreaterThan(number: number)
expect(actual).toBeGreaterThanOrEqual(number: number)

Expects the value to be greater than, or greater than or equal to, number.

toBeLessThan(number), toBeLessThanOrEqual(number)

expect(actual).toBeLessThan(number: number)
expect(actual).toBeLessThanOrEqual(number: number)

Expects the value to be less than, or less than or equal to, number.

toBeCloseTo(number, digits)

expect(actual).toBeCloseTo(number: number, digits?: number)

Expects the value to equal number, rounded to digits decimal places (2 by default).

toHaveLength(length)

expect(actual).toHaveLength(length: number)

Expects the value's length to be length.

toThrow(error)

expect(fn).toThrow(error?: string | RegExp | Function | Error)

Expects the function to throw, optionally an error whose message contains a string, matches a regular expression, or that's an instance of a class.

Put .not before a Jest matcher to negate it, as in expect(value).not.toBeNull().

Response assertions

These assertions apply to a response, such as relay.response or a response from relay.sendRequest. Write them after relay.response.to or expect(response).to, with chain words such as have and be.

relay.response.to.have.status(201);
relay.response.to.be.json;
relay.response.to.have.jsonBody("data.id");
relay.response.to.not.be.error;

status(code)

response.to.have.status(code: number | string)

Asserts that the response's status code is code, or its status text when given a string.

header(name, value)

response.to.have.header(name: string, value?: string | RegExp)

Asserts that the response has the header name, equal to value or matching it when given.

body(value)

response.to.have.body(value?: string | RegExp | object)

Asserts that the response has a body. With a string, asserts that the body is that text; with a regular expression, that the body matches it; and with an object, that the JSON body equals it.

jsonBody(path, value)

response.to.have.jsonBody(path?: string | object, value?: any)

Asserts that the body is valid JSON. With a path, asserts that the JSON body has a value at path, equal to value when given. With an object, asserts that the JSON body equals it.

jsonSchema(schema, options)

response.to.have.jsonSchema(schema: object, options?: object)

Asserts that the JSON body is valid against a JSON Schema, checked with Ajv 6 (draft-07). options are Ajv options; the failure message lists every error.

responseTime(ms)

response.to.have.responseTime(ms: number)

Asserts that the response took at most ms milliseconds.

json

response.to.be.json

Asserts that the response body is valid JSON.

withBody

response.to.be.withBody

Asserts that the response has a body.

Status classes

response.to.be.success

Each of these properties asserts that the response's status is in a class or is one code.

PropertyStatus
ok200
success2xx
info1xx
redirection3xx
clientError4xx
serverError5xx
error4xx or 5xx
accepted202
badRequest400
unauthorized401
forbidden403
notFound404
rateLimited429

See Also

  • test: A function that runs a named check and records whether it passed.
  • assert: chai's assert functions, recorded as soft assertions outside a test.
  • Testing responses: Check responses automatically with tests and assertions.