Function expect

You can use expect.addEqualityTesters to add your own methods to test if two objects are equal. For example, let's say you have a class in your code that represents volume and can determine if two volumes using different units are equal. You may want toEqual (and other equality matchers) to use this custom equality method when comparing to Volume classes. You can add a custom equality tester to have toEqual detect and apply custom logic when comparing Volume classes:

expect.addSnapshotSerializer adds a module that formats application-specific data structures.

For an individual test file, an added module precedes any modules from snapshotSerializers configuration, which precede the default snapshot serializers for built-in JavaScript types. The last module added is the first module tested.

expect.any(constructor) matches anything that was created with the given constructor or if it's a primitive that is of the passed type. You can use it inside toEqual or toHaveBeenCalledWith instead of a literal value.

expect.anything() matches anything but null or undefined. You can use it inside toEqual or toHaveBeenCalledWith instead of a literal value.

expect.arrayContaining(array) matches a received array which contains all of the elements in the expected array. That is, the expected array is a subset of the received array. Therefore, it matches a received array which contains elements that are not in the expected array.

You can use it instead of a literal value:

• in toEqual or toHaveBeenCalledWith
• to match a property in objectContaining or toMatchObject

expect.assertions verifies that a certain number of assertions are called during a test.

Note: expect.assertions only can use in bdd function test suite, such as test or it.

expect.closeTo(number, numDigits?) is useful when comparing floating point numbers in object properties or array item. If you need to compare a number, please use .toBeCloseTo instead.

The optional numDigits argument limits the number of digits to check after the decimal point. For the default value 2, the test criterion is Math.abs(expected - received) < 0.005 (that is, 10 ** -2 / 2).

Extend expect() with custom provided matchers.

To do so, you will need to extend the interface Expected to define the new signature of the expect.

import type { Async, Expected } from "./expect.ts";
import { expect } from "./expect.ts";

// Extends the `Expected` interface with your new matchers signatures
interface ExtendedExpected<IsAsync = false> extends Expected<IsAsync> {
  // Matcher that asserts value is a dinosaur
  toBeDinosaur: (options?: { includeTrexs?: boolean }) => unknown;

  // NOTE: You also need to overrides the following typings to allow modifiers to correctly infer typing
  not: IsAsync extends true ? Async<ExtendedExpected<true>>
    : ExtendedExpected<false>;
  resolves: Async<ExtendedExpected<true>>;
  rejects: Async<ExtendedExpected<true>>;
}

// Call `expect.extend()` with your new matchers definitions
expect.extend({
  toBeDinosaur(context, options) {
    const dino = `${context.value}`;
    const allowed = ["🦕"];
    if (options?.includeTrexs) {
      allowed.push("🦖");
    }
    const pass = allowed.includes(dino);
    if (context.isNot) {
      // Note: when `context.isNot` is set, the test is considered successful when `pass` is false
      return {
        message: () => `Expected "${dino}" to NOT be a dinosaur`,
        pass,
      };
    }
    return { message: () => `Expected "${dino}" to be a dinosaur`, pass };
  },
});

// Alias expect to avoid having to pass the generic typing argument each time
// This is probably what you want to export and reuse across your tests
const myexpect = expect<ExtendedExpected>;

// Perform some tests
myexpect("🦕").toBeDinosaur();
myexpect("🦧").not.toBeDinosaur();
await myexpect(Promise.resolve("🦕")).resolves.toBeDinosaur();
await myexpect(Promise.resolve("🦧")).resolves.not.toBeDinosaur();

// Regular matchers will still be available
myexpect("foo").not.toBeNull()
myexpect.anything
Copy

expect.hasAssertions verifies that at least one assertion is called during a test.

Note: expect.hasAssertions only can use in bdd function test suite, such as test or it.

expect.not.arrayContaining matches a received array which does not contain all of the elements in the expected array. That is, the expected array is not a subset of the received array.

expect.not.objectContaining matches any received object that does not recursively match the expected properties. That is, the expected object is not a subset of the received object. Therefore, it matches a received object which contains properties that are not in the expected object.

expect.not.stringContaining matches the received value if it is not a string or if it is a string that does not contain the exact expected string.

expect.not.stringMatching matches the received value if it is not a string or if it is a string that does not match the expected string or regular expression.

expect.objectContaining(object) matches any received object that recursively matches the expected properties. That is, the expected object is not a subset of the received object. Therefore, it matches a received object which contains properties that are not in the expected object.

expect.stringContaining(string) matches the received value if it is a string that contains the exact expected string.

expect.stringMatching(string | regexp) matches the received value if it is a string that matches the expected string or regular expression.

You can use it instead of a literal value:

• in toEqual or toHaveBeenCalledWith
• to match an element in arrayContaining
• to match a property in objectContaining (not available yet) or toMatchObject