when called

• <function> [when] called <assertion?>

Call the subject function without arguments, then delegate the return value to another assertion.

function giveMeFive() {
  return 5;
}
 
expect(giveMeFive, 'when called', 'to equal', 5);

In case of a failing expectation you get the following output:

expect(giveMeFive, 'when called', 'to equal', 7);

expected function giveMeFive() { return 5; } when called to equal 7
  
expected 5 to equal 7

If you don't provide an assertion to delegate to, the return value will be provided as the fulfillment value of the promise:

return expect(giveMeFive, 'called').then(function (result) {
  expect(result, 'to equal', 5);
});

When this assertion in used together with to satisfy we make sure that this is bound correctly:

function Person(name) {
  this.name = name;
}
 
Person.prototype.toString = function () {
  return this.name;
};
 
expect(new Person('John Doe'), 'to satisfy', {
  toString: expect.it('when called to equal', 'John Doe'),
});