Namespace: async-matchers

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:
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:
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:
  • 3.6
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