Function Assertions

These assertions test functions, their behavior, and properties.

{unknown} 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

{unknown} to be a constructor

✏️ Aliases:

{unknown} to be a constructor
{unknown} to be constructible
{unknown} to be a class

⚠️ 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

{function} 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

{function} to throw [{any}]

✏️ Aliases:

{function} to throw [{any}]
{function} to throw an error satisfying {any}

ℹ️ The to throw form of this assertion optionally accepts a parameter using the "to satisfy" semantics. The to throw an error satisfying form requires this parameter.

👉 See to satisfy <any>

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

{function} to throw a {constructor}

✏️ Aliases:

{function} to throw a {constructor}
{function} 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

{function} to throw a {constructor} satisfying {any}

✏️ Aliases:

{function} to throw a {constructor} satisfying {any}
{function} to throw an {constructor} satisfying {any}

👉 See {object} to satisfy {any}

This assertion is a combination of "to throw a" and "to throw".

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