when called with

• <function> [when] called with <array-like> <assertion?>

Apply the subject function to an array of parameters, then delegate the return value to another assertion.

function add(a, b) {
  return a + b;
}
 
expect(add, 'when called with', [1, 2], 'to equal', 3);

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

expect(add, 'when called with', [1, 2], 'to equal', 9);

expected function add(a, b) { return a + b; } when called with 1, 2 to equal 9
  
expected 3 to equal 9

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

return expect(add, 'called with', [1, 2]).then(function (result) {
  expect(result, 'to equal', 3);
});

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

function Greeter(prefix) {
  this.prefix = prefix;
}
 
Greeter.prototype.greet = function (name) {
  return this.prefix + name;
};
 
const helloGreeter = new Greeter('Hello, ');
 
expect(helloGreeter, 'to satisfy', {
  greet: expect.it(
    'when called with',
    ['John Doe'],
    'to equal',
    'Hello, John Doe'
  ),
});