Compares value with
expected by
calling Object.is. This method compares objects by reference instead of their contents, similarly to the strict
equality operator ===.
Usage
const value = { prop: 1 };
expect(value).toBe(value);
expect(value).not.toBe({});
expect(value.prop).toBe(1);
Expected value.
Compares floating point numbers for approximate equality. Use this method instead of expect(value).toBe(expected) when comparing floating point numbers.
Usage
expect(0.1 + 0.2).not.toBe(0.3);
expect(0.1 + 0.2).toBeCloseTo(0.3, 5);
Expected value.
OptionalnumDigits: numberThe number of decimal digits after the decimal point that must be equal.
Ensures that value is not undefined.
Usage
const value = null;
expect(value).toBeDefined();
Ensures that value is false in a boolean context, one of false, 0, '', null, undefined or NaN. Use this
method when you don't care about the specific value.
Usage
const value = null;
expect(value).toBeFalsy();
Ensures that value > expected for number or big integer values.
Usage
const value = 42;
expect(value).toBeGreaterThan(1);
The value to compare to.
Ensures that value >= expected for number or big integer values.
Usage
const value = 42;
expect(value).toBeGreaterThanOrEqual(42);
The value to compare to.
Ensures that value is an instance of a class. Uses instanceof operator.
Usage
expect(page).toBeInstanceOf(Page);
class Example {}
expect(new Example()).toBeInstanceOf(Example);
The class or constructor function.
Ensures that value < expected for number or big integer values.
Usage
const value = 42;
expect(value).toBeLessThan(100);
The value to compare to.
Ensures that value <= expected for number or big integer values.
Usage
const value = 42;
expect(value).toBeLessThanOrEqual(42);
The value to compare to.
Ensures that value is NaN.
Usage
const value = NaN;
expect(value).toBeNaN();
Ensures that value is null.
Usage
const value = null;
expect(value).toBeNull();
Ensures that value is true in a boolean context, anything but false, 0, '', null, undefined or NaN.
Use this method when you don't care about the specific value.
Usage
const value = { example: 'value' };
expect(value).toBeTruthy();
Ensures that value is undefined.
Usage
const value = undefined;
expect(value).toBeUndefined();
Ensures that value is an Array or Set and contains an item equal to the expected.
For objects, this method recursively checks equality of all fields, rather than comparing objects by reference as performed by expect(value).toContain(expected).
For primitive values, this method is equivalent to expect(value).toContain(expected).
Usage
const value = [
{ example: 1 },
{ another: 2 },
{ more: 3 },
];
expect(value).toContainEqual({ another: 2 });
expect(new Set(value)).toContainEqual({ another: 2 });
Expected value in the collection.
Compares contents of the value with contents of
expected,
performing "deep equality" check.
For objects, this method recursively checks equality of all fields, rather than comparing objects by reference as performed by expect(value).toBe(expected).
For primitive values, this method is equivalent to expect(value).toBe(expected).
Usage
const value = { prop: 1 };
expect(value).toEqual({ prop: 1 });
Non-strict equality
expect(value).toEqual(expected) performs deep equality check that compares contents of the received and expected values. To ensure two objects reference the same instance, use expect(value).toBe(expected) instead.
expect(value).toEqual(expected)
ignores undefined properties and array items, and does not insist on object types being equal. For stricter
matching, use
expect(value).toStrictEqual(expected).
Pattern matching
expect(value).toEqual(expected) can be also used to perform pattern matching on objects, arrays and primitive types, with the help of the following matchers:
Here is an example that asserts some of the values inside a complex object:
expect({
list: [1, 2, 3],
obj: { prop: 'Hello world!', another: 'some other value' },
extra: 'extra',
}).toEqual(expect.objectContaining({
list: expect.arrayContaining([2, 3]),
obj: expect.objectContaining({ prop: expect.stringContaining('Hello') }),
}));
Expected value.
Ensures that value has a .length property equal to
expected.
Useful for arrays and strings.
Usage
expect('Hello, World').toHaveLength(12);
expect([1, 2, 3]).toHaveLength(3);
Expected length.
Ensures that property at provided keyPath exists on the object and optionally checks that property is equal to
the
expected.
Equality is checked recursively, similarly to
expect(value).toEqual(expected).
Usage
const value = {
a: {
b: [42],
},
c: true,
};
expect(value).toHaveProperty('a.b');
expect(value).toHaveProperty('a.b', [42]);
expect(value).toHaveProperty('a.b[0]', 42);
expect(value).toHaveProperty('c');
expect(value).toHaveProperty('c', true);
Path to the property. Use dot notation a.b to check nested properties and indexed a[2] notation to check nested array items.
OptionalexpectedValue: unknownOptional expected value to compare the property to.
Ensures that string value matches a regular expression.
Usage
const value = 'Is 42 enough?';
expect(value).toMatch(/Is \d+ enough/);
Regular expression to match against.
Compares contents of the value with contents of
expected,
performing "deep equality" check. Allows extra properties to be present in the value, unlike
expect(value).toEqual(expected),
so you can check just a subset of object properties.
When comparing arrays, the number of items must match, and each item is checked recursively.
Usage
const value = {
a: 1,
b: 2,
c: true,
};
expect(value).toMatchObject({ a: 1, c: true });
expect(value).toMatchObject({ b: 2, c: true });
expect([{ a: 1, b: 2 }]).toMatchObject([{ a: 1 }]);
The expected object value to match against.
Compares contents of the value with contents of
expected
and their types.
Differences from expect(value).toEqual(expected):
{ a: undefined, b: 2 } does not match { b: 2 }.[, 1] does not match [undefined, 1].a and b will not equal a
literal object with fields a and b.Usage
const value = { prop: 1 };
expect(value).toStrictEqual({ prop: 1 });
Expected value.
Calls the function and ensures it throws an error.
Optionally compares the error with
expected.
Allowed expected values:
Usage
expect(() => {
throw new Error('Something bad');
}).toThrow();
expect(() => {
throw new Error('Something bad');
}).toThrow(/something/);
expect(() => {
throw new Error('Something bad');
}).toThrow(Error);
Optionalexpected: unknownExpected error message or error object.
An alias for expect(value).toThrow([expected]).
Usage
expect(() => {
throw new Error('Something bad');
}).toThrowError();
Optionalexpected: unknownExpected error message or error object.
Ensures that value is an Array or Set and contains an expected item.
Usage
const value = [1, 2, 3];
expect(value).toContain(2);
expect(new Set(value)).toContain(2);
Expected value in the collection.
Ensures that string value contains an expected substring. Comparison is case-sensitive.
Usage
const value = 'Hello, World';
expect(value).toContain('World');
expect(value).toContain(',');
Expected substring.
Matchers available in expect.