GenericAssertions
The GenericAssertions class provides assertion methods that can be used to make assertions about any values in the tests. A new instance of GenericAssertions is created by calling expect():
import { test, expect } from '@playwright/test';
test('assert a value', async ({ page }) => {
const value = 1;
await expect(value).toBe(2);
});
Methods
toBe
Added in: v1.9Compares 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);
Arguments
toBeCloseTo
Added in: v1.9Compares floating point numbers for approximate equality. Use this method instead of expect(generic).toBe() when comparing floating point numbers.
Usage
expect(0.1 + 0.2).not.toBe(0.3);
expect(0.1 + 0.2).toBeCloseTo(0.3, 5);
Arguments
Expected value.
The number of decimal digits after the decimal point that must be equal.
toBeDefined
Added in: v1.9Ensures that value is not undefined
.
Usage
const value = null;
expect(value).toBeDefined();
toBeFalsy
Added in: v1.9Ensures 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();
toBeGreaterThan
Added in: v1.9Ensures that value > expected
for number or big integer values.
Usage
const value = 42;
expect(value).toBeGreaterThan(1);
Arguments
toBeGreaterThanOrEqual
Added in: v1.9Ensures that value >= expected
for number or big integer values.
Usage
const value = 42;
expect(value).toBeGreaterThanOrEqual(42);
Arguments
toBeInstanceOf
Added in: v1.9Ensures that value is an instance of a class. Uses instanceof
operator.
Usage
expect(page).toBeInstanceOf(Page);
class Example {}
expect(new Example()).toBeInstanceOf(Example);
Arguments
toBeLessThan
Added in: v1.9Ensures that value < expected
for number or big integer values.
Usage
const value = 42;
expect(value).toBeLessThan(100);
Arguments
toBeLessThanOrEqual
Added in: v1.9Ensures that value <= expected
for number or big integer values.
Usage
const value = 42;
expect(value).toBeLessThanOrEqual(42);
Arguments
toBeNaN
Added in: v1.9Ensures that value is NaN
.
Usage
const value = NaN;
expect(value).toBeNaN();
toBeNull
Added in: v1.9Ensures that value is null
.
Usage
const value = null;
expect(value).toBeNull();
toBeTruthy
Added in: v1.9Ensures 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();
toBeUndefined
Added in: v1.9Ensures that value is undefined
.
Usage
const value = undefined;
expect(value).toBeUndefined();
toContain(expected)
Added in: v1.9Ensures that string value contains an expected substring. Comparison is case-sensitive.
Usage
const value = 'Hello, World';
expect(value).toContain('World');
expect(value).toContain(',');
Arguments
toContain(expected)
Added in: v1.9Ensures 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);
Arguments
toContainEqual
Added in: v1.9Ensures 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(generic).toContain().
For primitive values, this method is equivalent to expect(generic).toContain().
Usage
const value = [
{ example: 1 },
{ another: 2 },
{ more: 3 },
];
expect(value).toContainEqual({ another: 2 });
expect(new Set(value)).toContainEqual({ another: 2 });
Arguments
toEqual
Added in: v1.9Compares 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(generic).toBe().
For primitive values, this method is equivalent to expect(generic).toBe().
Usage
const value = { prop: 1 };
expect(value).toEqual({ prop: 1 });
Arguments
toHaveLength
Added in: v1.9Ensures 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);
Arguments
toHaveProperty
Added in: v1.9Ensures 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(generic).toEqual().
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);
Arguments
Path to the property. Use dot notation
a.b
to check nested properties and indexeda[2]
notation to check nested array items.Optional expected value to compare the property to.
toMatch
Added in: v1.9Ensures that string value matches a regular expression.
Usage
const value = 'Is 42 enough?';
expect(value).toMatch(/Is \d+ enough/);
Arguments
toMatchObject
Added in: v1.9Compares contents of the value with contents of expected
, performing "deep equality" check. Allows extra properties to be present in the value, unlike expect(generic).toEqual(), 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 }]);
Arguments
toStrictEqual
Added in: v1.9Compares contents of the value with contents of expected
and their types.
Differences from expect(generic).toEqual():
- Keys with undefined properties are checked. For example,
{ a: undefined, b: 2 }
does not match{ b: 2 }
. - Array sparseness is checked. For example,
[, 1]
does not match[undefined, 1]
. - Object types are checked to be equal. For example, a class instance with fields
a
andb
will not equal a literal object with fieldsa
andb
.
Usage
const value = { prop: 1 };
expect(value).toStrictEqual({ prop: 1 });
Arguments
toThrow
Added in: v1.9Calls the function and ensures it throws an error.
Optionally compares the error with expected
. Allowed expected values:
- Regular expression - error message should match the pattern.
- String - error message should include the substring.
- Error object - error message should be equal to the message property of the object.
- Error class - error object should be an instance of the class.
Usage
expect(() => {
throw new Error('Something bad');
}).toThrow();
expect(() => {
throw new Error('Something bad');
}).toThrow(/something/);
expect(() => {
throw new Error('Something bad');
}).toThrow(Error);
Arguments
toThrowError
Added in: v1.9An alias for expect(generic).toThrow().
Usage
expect(() => {
throw new Error('Something bad');
}).toThrowError();
Arguments
Properties
not
Added in: v1.9Makes the assertion check for the opposite condition. For example, the following code passes:
const value = 1;
await expect(value).not.toBe(2);
Usage
expect(generic).not
Type