Skip to main content

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.9genericAssertions.toBe

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);

Arguments

toBeCloseTo​

Added in: v1.9genericAssertions.toBeCloseTo

Compares 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 number#

    Expected value.

  • numDigits number (optional)#

    The number of decimal digits after the decimal point that must be equal.

toBeDefined​

Added in: v1.9genericAssertions.toBeDefined

Ensures that value is not undefined.

Usage

const value = null;
expect(value).toBeDefined();

toBeFalsy​

Added in: v1.9genericAssertions.toBeFalsy

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();

toBeGreaterThan​

Added in: v1.9genericAssertions.toBeGreaterThan

Ensures that value > expected for number or big integer values.

Usage

const value = 42;
expect(value).toBeGreaterThan(1);

Arguments

  • expected number|[bigint]#

    The value to compare to.

toBeGreaterThanOrEqual​

Added in: v1.9genericAssertions.toBeGreaterThanOrEqual

Ensures that value >= expected for number or big integer values.

Usage

const value = 42;
expect(value).toBeGreaterThanOrEqual(42);

Arguments

  • expected number|[bigint]#

    The value to compare to.

toBeInstanceOf​

Added in: v1.9genericAssertions.toBeInstanceOf

Ensures that value is an instance of a class. Uses instanceof operator.

Usage

expect(page).toBeInstanceOf(Page);

class Example {}
expect(new Example()).toBeInstanceOf(Example);

Arguments

  • expected Function#

    The class or constructor function.

toBeLessThan​

Added in: v1.9genericAssertions.toBeLessThan

Ensures that value < expected for number or big integer values.

Usage

const value = 42;
expect(value).toBeLessThan(100);

Arguments

  • expected number|[bigint]#

    The value to compare to.

toBeLessThanOrEqual​

Added in: v1.9genericAssertions.toBeLessThanOrEqual

Ensures that value <= expected for number or big integer values.

Usage

const value = 42;
expect(value).toBeLessThanOrEqual(42);

Arguments

  • expected number|[bigint]#

    The value to compare to.

toBeNaN​

Added in: v1.9genericAssertions.toBeNaN

Ensures that value is NaN.

Usage

const value = NaN;
expect(value).toBeNaN();

toBeNull​

Added in: v1.9genericAssertions.toBeNull

Ensures that value is null.

Usage

const value = null;
expect(value).toBeNull();

toBeTruthy​

Added in: v1.9genericAssertions.toBeTruthy

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();

toBeUndefined​

Added in: v1.9genericAssertions.toBeUndefined

Ensures that value is undefined.

Usage

const value = undefined;
expect(value).toBeUndefined();

toContain(expected)​

Added in: v1.9genericAssertions.toContain(expected)

Ensures that string value contains an expected substring. Comparison is case-sensitive.

Usage

const value = 'Hello, World';
expect(value).toContain('World');
expect(value).toContain(',');

Arguments

  • expected string#

    Expected substring.

toContain(expected)​

Added in: v1.9genericAssertions.toContain(expected)

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);

Arguments

  • expected Object#

    Expected value in the collection.

toContainEqual​

Added in: v1.9genericAssertions.toContainEqual

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(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

  • expected Object#

    Expected value in the collection.

toEqual​

Added in: v1.9genericAssertions.toEqual

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(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.9genericAssertions.toHaveLength

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);

Arguments

toHaveProperty​

Added in: v1.9genericAssertions.toHaveProperty

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(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

  • keyPath string#

    Path to the property. Use dot notation a.b to check nested properties and indexed a[2] notation to check nested array items.

  • expected Object (optional)#

    Optional expected value to compare the property to.

toMatch​

Added in: v1.9genericAssertions.toMatch

Ensures that string value matches a regular expression.

Usage

const value = 'Is 42 enough?';
expect(value).toMatch(/Is \d+ enough/);

Arguments

toMatchObject​

Added in: v1.9genericAssertions.toMatchObject

Compares 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

  • expected Object|Array#

    The expected object value to match against.

toStrictEqual​

Added in: v1.9genericAssertions.toStrictEqual

Compares 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 and b will not equal a literal object with fields a and b.

Usage

const value = { prop: 1 };
expect(value).toStrictEqual({ prop: 1 });

Arguments

toThrow​

Added in: v1.9genericAssertions.toThrow

Calls 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

  • expected Object (optional)#

    Expected error message or error object.

toThrowError​

Added in: v1.9genericAssertions.toThrowError

An alias for expect(generic).toThrow().

Usage

expect(() => {
  throw new Error('Something bad');
}).toThrowError();

Arguments

  • expected Object (optional)#

    Expected error message or error object.

Properties​

not​

Added in: v1.9genericAssertions.not

Makes 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