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): AssertionOverview
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): AssertionStarts an assertion about value.
expect.fail(message)
expect.fail(message?: string): neverFails with message.
Chains and flags
Language chains
to be been is that which and has have with at of same but does still alsoChain words for readability, which don't change the assertion.
not
assertion.not: AssertionNegates the assertions that follow.
deep
assertion.deep: AssertionMakes the assertions that follow compare contents recursively instead of by identity.
nested
assertion.nested: AssertionLets the property and include assertions that follow use dotted paths.
own
assertion.own: AssertionMakes the property and include assertions that follow ignore inherited properties.
ordered
assertion.ordered: AssertionMakes the members assertion that follows require the same order.
any
assertion.any: AssertionMakes the keys assertion that follows pass with at least one of the keys.
all
assertion.all: AssertionMakes the keys assertion that follows require all of the keys and no others.
Value checks
ok
assertion.okAsserts 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.NaNAsserts that the value is true, false, null, undefined or NaN.
exist
assertion.existAsserts that the value is neither null nor undefined.
empty
assertion.emptyAsserts 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.jsonAsserts that the response body is valid JSON.
withBody
response.to.be.withBodyAsserts that the response has a body.
Status classes
response.to.be.successEach of these properties asserts that the response's status is in a class or is one code.
| Property | Status |
|---|---|
ok | 200 |
success | 2xx |
info | 1xx |
redirection | 3xx |
clientError | 4xx |
serverError | 5xx |
error | 4xx or 5xx |
accepted | 202 |
badRequest | 400 |
unauthorized | 401 |
forbidden | 403 |
notFound | 404 |
rateLimited | 429 |
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.