Function Assertions

These assertions test functions, their behavior, and properties.

to be a function

Success:

expect(function () {}, 'to be a function');
expect(() => {}, 'to be a function');
expect(Math.max, 'to be a function');
Copy

Failure:

expect('hello', 'to be a function');
// AssertionError: Expected 'hello' to be a function
Copy

Negation:

expect('hello', 'not to be a function');
Copy

to be an async function

Success:

expect(async function () {}, 'to be an async function');
expect(async () => {}, 'to be an async function');
Copy

Failure:

expect(function () {}, 'to be an async function');
// AssertionError: Expected function to be an async function
Copy

Negation:

expect(function () {}, 'not to be an async function');
Copy

to be a class

Aliases: to be a class, to be a constructor

⚠️ Warning!

It is currently (as of September 2025) not possible to reliably distinguish between classes and regular functions in JavaScript. We can only tell if a function is constructable (i.e., can be called with new); we cannot determine if it is specifically a class constructor.

Use with caution.

Success:

class MyClass {}
expect(MyClass, 'to be a class');
expect(Date, 'to be a constructor');
Copy

Failure:

const fn = function () {};
expect(fn, 'to be a class');
// AssertionError: Expected function to be a class
Copy

Negation:

expect(fn, 'not to be a class');
Copy

to have arity <nonnegative-integer>

Success:

function add(a, b) {
  return a + b;
}
expect(add, 'to have arity', 2);

const multiply = (x, y, z) => x * y * z;
expect(multiply, 'to have arity', 3);
Copy

Failure:

function greet(name) {
  return `Hello, ${name}!`;
}
expect(greet, 'to have arity', 2);
// AssertionError: Expected function to have arity 2
Copy

Negation:

expect(greet, 'not to have arity', 2);
Copy

to throw <string | RegExp | object>

This assertion optionally accepts a parameter which must be a string, RegExp or object:

• If omitted, the assertion checks that the function throws anything.
• If a string, matches the message prop of the thrown Error exactly; if a non-error was thrown, the value is coerced to a string and matched directly.
• If a RegExp, tests the message prop of the thrown Error; if a non-error was thrown, the value is coerced to a string and tested directly.
• If an object, "to satisfy" semantics are used.

Success:

expect(() => {
  throw new Error('Something went wrong');
}, 'to throw');

expect(() => {
  JSON.parse('invalid json');
}, 'to throw');

// String matching
expect(
  () => {
    throw new Error('Specific error message');
  },
  'to throw',
  'Specific error message',
);

// RegExp matching
expect(
  () => {
    throw new Error('Error: Something failed');
  },
  'to throw',
  /Something failed/,
);

// Object matching
expect(
  () => {
    throw new Error('Custom error');
  },
  'to throw',
  { message: 'Custom error' },
);
Copy

Failure:

expect(() => {
  return 'all good';
}, 'to throw');
// AssertionError: Expected function to throw

expect(
  () => {
    throw new Error('Different message');
  },
  'to throw',
  'Specific error message',
);
// AssertionError: Expected function to throw 'Specific error message'
Copy

Negation:

expect(() => {
  return 'all good';
}, 'not to throw');

expect(
  () => {
    throw new Error('Different message');
  },
  'not to throw',
  'Specific error message',
);
Copy

to throw a <constructor>

Aliases: to throw a <constructor>, to throw an <constructor>

Success:

expect(
  () => {
    throw new TypeError('Type error');
  },
  'to throw a',
  TypeError,
);

expect(
  () => {
    throw new RangeError('Range error');
  },
  'to throw an',
  Error,
); // RangeError extends Error
Copy

Failure:

expect(
  () => {
    throw new TypeError('Type error');
  },
  'to throw a',
  RangeError,
);
// AssertionError: Expected function to throw a RangeError
Copy

Negation:

expect(
  () => {
    throw new TypeError('Type error');
  },
  'not to throw a',
  RangeError,
);
Copy

to throw an <error> satisfying <object>

Aliases: to throw a <error> satisfying <object>, to throw an <error> satisfying <object>

This assertion is a combination of "to throw a" and "to throw" (with an object parameter).

Success:

expect(
  () => {
    const err = new Error('Custom error');
    err.code = 'CUSTOM_CODE';
    throw err;
  },
  'to throw a',
  Error,
  'satisfying',
  { code: 'CUSTOM_CODE' },
);
Copy

Failure:

expect(
  () => {
    throw new Error('Simple error');
  },
  'to throw a',
  Error,
  'satisfying',
  { code: 'MISSING_CODE' },
);
// AssertionError: Expected thrown error to satisfy { code: 'MISSING_CODE' }
Copy

Negation:

expect(
  () => {
    throw new Error('Simple error');
  },
  'not to throw a',
  Error,
  'satisfying',
  { code: 'MISSING_CODE' },
);
Copy