Namespace: async-matchers

Asynchronous matchers that operate on an actual value which is a promise, and return a promise.

Most async matchers will wait indefinitely for the promise to be resolved or rejected, resulting in a spec timeout if that never happens. If you expect that the promise will already be resolved or rejected at the time the matcher is called, you can use the async-matchers#already modifier to get a faster failure with a more helpful message.

Note: Specs must await the result of each async matcher, return the promise returned by the matcher, or return a promise that's derived from the one returned by the matcher. Otherwise the matcher will not be evaluated before the spec completes.

Examples

// Good
await expectAsync(aPromise).toBeResolved();

// Good
return expectAsync(aPromise).toBeResolved();

// Good
return expectAsync(aPromise).toBeResolved()
 .then(function() {
   // more spec code
 });

// Bad
expectAsync(aPromise).toBeResolved();

Members

already :async-matchers

Fail as soon as possible if the actual is pending. Otherwise evaluate the matcher.

Type:

async-matchers

Since:

3.8.0

Examples

await expectAsync(myPromise).already.toBeResolved();

return expectAsync(myPromise).already.toBeResolved();

not :async-matchers

Invert the matcher following this expectAsync

Type:

async-matchers

Examples

await expectAsync(myPromise).not.toBeResolved();

return expectAsync(myPromise).not.toBeResolved();

Methods

(async) toBePending()

Expect a promise to be pending, i.e. the promise is neither resolved nor rejected.

Since:

Example

await expectAsync(aPromise).toBePending();

(async) toBeRejected()

Expect a promise to be rejected.

Since:

3.1.0

Examples

await expectAsync(aPromise).toBeRejected();

return expectAsync(aPromise).toBeRejected();

(async) toBeRejectedWith(expected)

Expect a promise to be rejected with a value equal to the expected, using deep equality comparison.

Parameters:

Name	Type	Description
`expected`	Object	Value that the promise is expected to be rejected with

Since:

3.3.0

Examples

await expectAsync(aPromise).toBeRejectedWith({prop: 'value'});

return expectAsync(aPromise).toBeRejectedWith({prop: 'value'});

(async) toBeRejectedWithError(expectedopt, messageopt)

Expect a promise to be rejected with a value matched to the expected

Parameters:

Name	Type	Attributes	Description
`expected`	Error	<optional>	`Error` constructor the object that was thrown needs to be an instance of. If not provided, `Error` will be used.
`message`	RegExp \| String	<optional>	The message that should be set on the thrown `Error`

Since:

3.5.0

Example

await expectAsync(aPromise).toBeRejectedWithError(MyCustomError, 'Error message');
await expectAsync(aPromise).toBeRejectedWithError(MyCustomError, /Error message/);
await expectAsync(aPromise).toBeRejectedWithError(MyCustomError);
await expectAsync(aPromise).toBeRejectedWithError('Error message');
return expectAsync(aPromise).toBeRejectedWithError(/Error message/);

(async) toBeResolved()

Expect a promise to be resolved.

Since:

3.1.0

Examples

await expectAsync(aPromise).toBeResolved();

return expectAsync(aPromise).toBeResolved();

(async) toBeResolvedTo(expected)

Expect a promise to be resolved to a value equal to the expected, using deep equality comparison.

Parameters:

Name	Type	Description
`expected`	Object	Value that the promise is expected to resolve to

Since:

3.1.0

Examples

await expectAsync(aPromise).toBeResolvedTo({prop: 'value'});

return expectAsync(aPromise).toBeResolvedTo({prop: 'value'});

withContext(message) → {async-matchers}

Add some context for an expectAsync

Parameters:

Name	Type	Description
`message`	String	Additional context to show when the async matcher fails

Since:

3.3.0

Returns:

Type: async-matchers