Skip to main content

Assertions

Playwright Test uses expect library for test assertions. This library provides a lot of matchers like toEqual, toContain, toMatch, toMatchSnapshot and many more:

expect(success).toBeTruthy();

Playwright also extends it with convenience async matchers that will wait until the expected condition is met. Consider the following example:

await expect(page.locator('.status')).toHaveText('Submitted');

Playwright Test will be re-testing the node with the selector .status until fetched Node has the "Submitted" text. It will be re-fetching the node and checking it over and over, until the condition is met or until the timeout is reached. You can either pass this timeout or configure it once via the testConfig.expect value in test config.

By default, the timeout for assertions is set to 5 seconds. Learn more about various timeouts.

Negating Matchers​

In general, we can expect the opposite to be true by adding a .not to the front of the matchers:

expect(value).not.toEqual(0);
await expect(locator).not.toContainText("some text");

Soft Assertions​

By default, failed assertion will terminate test execution. Playwright also supports soft assertions: failed soft assertions do not terminate test execution, but mark the test as failed.

// Make a few checks that will not stop the test when failed...
await expect.soft(page.locator('#status')).toHaveText('Success');
await expect.soft(page.locator('#eta')).toHaveText('1 day');

// ... and continue the test to check more things.
await page.locator('#next-page').click();
await expect.soft(page.locator('#title')).toHaveText('Make another order');

At any point during test execution, you can check whether there were any soft assertion failures:

// Make a few checks that will not stop the test when failed...
await expect.soft(page.locator('#status')).toHaveText('Success');
await expect.soft(page.locator('#eta')).toHaveText('1 day');

// Avoid running further if there were soft assertion failures.
expect(test.info().errors).toHaveLength(0);

Custom Expect Message​

You can specify a custom error message as a second argument to the expect function, for example:

await expect(page.getByText('Name'), 'should be logged in').toBeVisible();

The error would look like this:

    Error: should be logged in

    Call log:
      - expect.toBeVisible with timeout 5000ms
      - waiting for selector "text=Name"


      2 |
      3 | test('example test', async({ page }) => {
    > 4 |   await expect(page.getByText('Name'), 'should be logged in').toBeVisible();
        |                                                                  ^
      5 | });
      6 |

The same works with soft assertions:

expect.soft(value, 'my soft assertion').toBe(56);

Polling​

You can convert any synchronous expect to an asynchronous polling one using expect.poll.

The following method will poll given function until it returns HTTP status 200:

await expect.poll(async () => {
  const response = await page.request.get('https://api.example.com');
  return response.status();
}, {
  // Custom error message, optional.
  message: 'make sure API eventually succeeds', // custom error message
  // Poll for 10 seconds; defaults to 5 seconds. Pass 0 to disable timeout.
  timeout: 10000,
}).toBe(200);

You can also specify custom polling intervals:

await expect.poll(async () => {
  const response = await page.request.get('https://api.example.com');
  return response.status();
}, {
  // Probe, wait 1s, probe, wait 2s, probe, wait 10s, probe, wait 10s, probe, .... Defaults to [100, 250, 500, 1000].
  intervals: [1_000, 2_000, 10_000],
  timeout: 60_000
}).toBe(200);

expect(locator).not​

Added in: v1.20

Makes the assertion check for the opposite condition. For example, this code tests that the Locator doesn't contain text "error":

await expect(locator).not.toContainText('error');

expect(locator).toBeChecked([options])​

Added in: v1.20
  • options? <Object>
    • checked? <boolean> Added in: v1.18#
    • timeout? <number> Time to retry the assertion for. Defaults to timeout in TestConfig.expect. Added in: v1.18#
  • returns: <Promise<void>>#

Ensures the Locator points to a checked input.

const locator = page.getByLabel('Subscribe to newsletter');
await expect(locator).toBeChecked();

expect(locator).toBeDisabled([options])​

Added in: v1.20
  • options? <Object>
    • timeout? <number> Time to retry the assertion for. Defaults to timeout in TestConfig.expect. Added in: v1.18#
  • returns: <Promise<void>>#

Ensures the Locator points to a disabled element. Element is disabled if it has "disabled" attribute or is disabled via 'aria-disabled'. Note that only native control elements such as HTML button, input, select, textarea, option, optgroup can be disabled by setting "disabled" attribute. "disabled" attribute on other elements is ignored by the browser.

const locator = page.locator('button.submit');
await expect(locator).toBeDisabled();

expect(locator).toBeEditable([options])​

Added in: v1.20
  • options? <Object>
    • editable? <boolean> Added in: v1.26#
    • timeout? <number> Time to retry the assertion for. Defaults to timeout in TestConfig.expect. Added in: v1.18#
  • returns: <Promise<void>>#

Ensures the Locator points to an editable element.

const locator = page.getByRole('textbox');
await expect(locator).toBeEditable();

expect(locator).toBeEmpty([options])​

Added in: v1.20
  • options? <Object>
    • timeout? <number> Time to retry the assertion for. Defaults to timeout in TestConfig.expect. Added in: v1.18#
  • returns: <Promise<void>>#

Ensures the Locator points to an empty editable element or to a DOM node that has no text.

const locator = page.locator('div.warning');
await expect(locator).toBeEmpty();

expect(locator).toBeEnabled([options])​

Added in: v1.20
  • options? <Object>
    • enabled? <boolean> Added in: v1.26#
    • timeout? <number> Time to retry the assertion for. Defaults to timeout in TestConfig.expect. Added in: v1.18#
  • returns: <Promise<void>>#

Ensures the Locator points to an enabled element.

const locator = page.locator('button.submit');
await expect(locator).toBeEnabled();

expect(locator).toBeFocused([options])​

Added in: v1.20
  • options? <Object>
    • timeout? <number> Time to retry the assertion for. Defaults to timeout in TestConfig.expect. Added in: v1.18#
  • returns: <Promise<void>>#

Ensures the Locator points to a focused DOM node.

const locator = page.getByRole('textbox');
await expect(locator).toBeFocused();

expect(locator).toBeHidden([options])​

Added in: v1.20
  • options? <Object>
    • timeout? <number> Time to retry the assertion for. Defaults to timeout in TestConfig.expect. Added in: v1.18#
  • returns: <Promise<void>>#

Ensures that Locator either does not resolve to any DOM node, or resolves to a non-visible one.

const locator = page.locator('.my-element');
await expect(locator).toBeHidden();

expect(locator).toBeVisible([options])​

Added in: v1.20
  • options? <Object>
    • timeout? <number> Time to retry the assertion for. Defaults to timeout in TestConfig.expect. Added in: v1.18#
    • visible? <boolean> Added in: v1.26#
  • returns: <Promise<void>>#

Ensures that Locator points to an attached and visible DOM node.

const locator = page.locator('.my-element');
await expect(locator).toBeVisible();

expect(locator).toContainText(expected[, options])​

Added in: v1.20
  • expected <string|RegExp|Array<string|RegExp>> Expected substring or RegExp or a list of those. Added in: v1.18#
  • options? <Object>
    • ignoreCase? <boolean> Whether to perform case-insensitive match. ignoreCase option takes precedence over the corresponding regular expression flag if specified. Added in: v1.23#
    • timeout? <number> Time to retry the assertion for. Defaults to timeout in TestConfig.expect. Added in: v1.18#
    • useInnerText? <boolean> Whether to use element.innerText instead of element.textContent when retrieving DOM node text. Added in: v1.18#
  • returns: <Promise<void>>#

Ensures the Locator points to an element that contains the given text. You can use regular expressions for the value as well.

const locator = page.locator('.title');
await expect(locator).toContainText('substring');
await expect(locator).toContainText(/\d messages/);

If you pass an array as an expected value, the expectations are:

  1. Locator resolves to a list of elements.
  2. Elements from a subset of this list contain text from the expected array, respectively.
  3. The matching subset of elements has the same order as the expected array.
  4. Each text value from the expected array is matched by some element from the list.

For example, consider the following list:

<ul>
  <li>Item Text 1</li>
  <li>Item Text 2</li>
  <li>Item Text 3</li>
</ul>

Let's see how we can use the assertion:

// ✓ Contains the right items in the right order
await expect(page.locator('ul > li')).toContainText(['Text 1', 'Text 3']);

// ✖ Wrong order
await expect(page.locator('ul > li')).toContainText(['Text 3', 'Text 2']);

// ✖ No item contains this text
await expect(page.locator('ul > li')).toContainText(['Some 33']);

// ✖ Locator points to the outer list element, not to the list items
await expect(page.locator('ul')).toContainText(['Text 3']);

expect(locator).toHaveAttribute(name, value[, options])​

Added in: v1.20
  • name <string> Attribute name. Added in: v1.18#
  • value <string|RegExp> Expected attribute value. Added in: v1.18#
  • options? <Object>
    • timeout? <number> Time to retry the assertion for. Defaults to timeout in TestConfig.expect. Added in: v1.18#
  • returns: <Promise<void>>#

Ensures the Locator points to an element with given attribute.

const locator = page.locator('input');
await expect(locator).toHaveAttribute('type', 'text');

expect(locator).toHaveClass(expected[, options])​

Added in: v1.20

Ensures the Locator points to an element with given CSS classes. This needs to be a full match or using a relaxed regular expression.

<div class='selected row' id='component'></div>
const locator = page.locator('#component');
await expect(locator).toHaveClass(/selected/);
await expect(locator).toHaveClass('selected row');

Note that if array is passed as an expected value, entire lists of elements can be asserted:

const locator = page.locator('list > .component');
await expect(locator).toHaveClass(['component', 'component selected', 'component']);

expect(locator).toHaveCount(count[, options])​

Added in: v1.20
  • count <number> Expected count. Added in: v1.18#
  • options? <Object>
    • timeout? <number> Time to retry the assertion for. Defaults to timeout in TestConfig.expect. Added in: v1.18#
  • returns: <Promise<void>>#

Ensures the Locator resolves to an exact number of DOM nodes.

const list = page.locator('list > .component');
await expect(list).toHaveCount(3);

expect(locator).toHaveCSS(name, value[, options])​

Added in: v1.20
  • name <string> CSS property name. Added in: v1.18#
  • value <string|RegExp> CSS property value. Added in: v1.18#
  • options? <Object>
    • timeout? <number> Time to retry the assertion for. Defaults to timeout in TestConfig.expect. Added in: v1.18#
  • returns: <Promise<void>>#

Ensures the Locator resolves to an element with the given computed CSS style.

const locator = page.getByRole('button');
await expect(locator).toHaveCSS('display', 'flex');

expect(locator).toHaveId(id[, options])​

Added in: v1.20
  • id <string|RegExp> Element id. Added in: v1.18#
  • options? <Object>
    • timeout? <number> Time to retry the assertion for. Defaults to timeout in TestConfig.expect. Added in: v1.18#
  • returns: <Promise<void>>#

Ensures the Locator points to an element with the given DOM Node ID.

const locator = page.getByRole('textbox');
await expect(locator).toHaveId('lastname');

expect(locator).toHaveJSProperty(name, value[, options])​

Added in: v1.20
  • name <string> Property name. Added in: v1.18#
  • value <Object> Property value. Added in: v1.18#
  • options? <Object>
    • timeout? <number> Time to retry the assertion for. Defaults to timeout in TestConfig.expect. Added in: v1.18#
  • returns: <Promise<void>>#

Ensures the Locator points to an element with given JavaScript property. Note that this property can be of a primitive type as well as a plain serializable JavaScript object.

const locator = page.locator('.component');
await expect(locator).toHaveJSProperty('loaded', true);

expect(locator).toHaveScreenshot(name[, options])​

Added in: v1.23

  • name <string|Array<string>> Snapshot name.#

  • options? <Object>

    • animations? <"disabled"|"allow"> When set to "disabled", stops CSS animations, CSS transitions and Web Animations. Animations get different treatment depending on their duration:#

      • finite animations are fast-forwarded to completion, so they'll fire transitionend event.
      • infinite animations are canceled to initial state, and then played over after the screenshot.

      Defaults to "disabled" that disables animations.

    • caret? <"hide"|"initial"> When set to "hide", screenshot will hide text caret. When set to "initial", text caret behavior will not be changed. Defaults to "hide".#

    • mask? <Array<Locator>> Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink box #FF00FF that completely covers its bounding box.#

    • maxDiffPixelRatio? <number> An acceptable ratio of pixels that are different to the total amount of pixels, between 0 and 1. Default is configurable with TestConfig.expect. Unset by default.#

    • maxDiffPixels? <number> An acceptable amount of pixels that could be different. Default is configurable with TestConfig.expect. Unset by default.#

    • omitBackground? <boolean> Hides default white background and allows capturing screenshots with transparency. Not applicable to jpeg images. Defaults to false.#

    • scale? <"css"|"device"> When set to "css", screenshot will have a single pixel per each css pixel on the page. For high-dpi devices, this will keep screenshots small. Using "device" option will produce a single pixel per each device pixel, so screenhots of high-dpi devices will be twice as large or even larger.#

      Defaults to "css".

    • threshold? <number> An acceptable perceived color difference in the YIQ color space between the same pixel in compared images, between zero (strict) and one (lax), default is configurable with TestConfig.expect. Defaults to 0.2.#

    • timeout? <number> Time to retry the assertion for. Defaults to timeout in TestConfig.expect.#

  • returns: <Promise<void>>#

This function will wait until two consecutive locator screenshots yield the same result, and then compare the last screenshot with the expectation.

const locator = page.getByRole('button');
await expect(locator).toHaveScreenshot('image.png');

expect(locator).toHaveScreenshot([options])​

Added in: v1.23

  • options? <Object>

    • animations? <"disabled"|"allow"> When set to "disabled", stops CSS animations, CSS transitions and Web Animations. Animations get different treatment depending on their duration:#

      • finite animations are fast-forwarded to completion, so they'll fire transitionend event.
      • infinite animations are canceled to initial state, and then played over after the screenshot.

      Defaults to "disabled" that disables animations.

    • caret? <"hide"|"initial"> When set to "hide", screenshot will hide text caret. When set to "initial", text caret behavior will not be changed. Defaults to "hide".#

    • mask? <Array<Locator>> Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink box #FF00FF that completely covers its bounding box.#

    • maxDiffPixelRatio? <number> An acceptable ratio of pixels that are different to the total amount of pixels, between 0 and 1. Default is configurable with TestConfig.expect. Unset by default.#

    • maxDiffPixels? <number> An acceptable amount of pixels that could be different. Default is configurable with TestConfig.expect. Unset by default.#

    • omitBackground? <boolean> Hides default white background and allows capturing screenshots with transparency. Not applicable to jpeg images. Defaults to false.#

    • scale? <"css"|"device"> When set to "css", screenshot will have a single pixel per each css pixel on the page. For high-dpi devices, this will keep screenshots small. Using "device" option will produce a single pixel per each device pixel, so screenhots of high-dpi devices will be twice as large or even larger.#

      Defaults to "css".

    • threshold? <number> An acceptable perceived color difference in the YIQ color space between the same pixel in compared images, between zero (strict) and one (lax), default is configurable with TestConfig.expect. Defaults to 0.2.#

    • timeout? <number> Time to retry the assertion for. Defaults to timeout in TestConfig.expect.#

  • returns: <Promise<void>>#

This function will wait until two consecutive locator screenshots yield the same result, and then compare the last screenshot with the expectation.

const locator = page.getByRole('button');
await expect(locator).toHaveScreenshot();

expect(locator).toHaveText(expected[, options])​

Added in: v1.20
  • expected <string|RegExp|Array<string|RegExp>> Expected substring or RegExp or a list of those. Added in: v1.18#
  • options? <Object>
    • ignoreCase? <boolean> Whether to perform case-insensitive match. ignoreCase option takes precedence over the corresponding regular expression flag if specified. Added in: v1.23#
    • timeout? <number> Time to retry the assertion for. Defaults to timeout in TestConfig.expect. Added in: v1.18#
    • useInnerText? <boolean> Whether to use element.innerText instead of element.textContent when retrieving DOM node text. Added in: v1.18#
  • returns: <Promise<void>>#

Ensures the Locator points to an element with the given text. You can use regular expressions for the value as well.

const locator = page.locator('.title');
await expect(locator).toHaveText(/Welcome, Test User/);
await expect(locator).toHaveText(/Welcome, .*/);

If you pass an array as an expected value, the expectations are:

  1. Locator resolves to a list of elements.
  2. The number of elements equals the number of expected values in the array.
  3. Elements from the list have text matching expected array values, one by one, in order.

For example, consider the following list:

<ul>
  <li>Text 1</li>
  <li>Text 2</li>
  <li>Text 3</li>
</ul>

Let's see how we can use the assertion:

// ✓ Has the right items in the right order
await expect(page.locator('ul > li')).toHaveText(['Text 1', 'Text 2', 'Text 3']);

// ✖ Wrong order
await expect(page.locator('ul > li')).toHaveText(['Text 3', 'Text 2', 'Text 1']);

// ✖ Last item does not match
await expect(page.locator('ul > li')).toHaveText(['Text 1', 'Text 2', 'Text']);

// ✖ Locator points to the outer list element, not to the list items
await expect(page.locator('ul')).toHaveText(['Text 1', 'Text 2', 'Text 3']);

expect(locator).toHaveValue(value[, options])​

Added in: v1.20
  • value <string|RegExp> Expected value. Added in: v1.18#
  • options? <Object>
    • timeout? <number> Time to retry the assertion for. Defaults to timeout in TestConfig.expect. Added in: v1.18#
  • returns: <Promise<void>>#

Ensures the Locator points to an element with the given input value. You can use regular expressions for the value as well.

const locator = page.locator('input[type=number]');
await expect(locator).toHaveValue(/[0-9]/);

expect(locator).toHaveValues(values[, options])​

Added in: v1.23

Ensures the Locator points to multi-select/combobox (i.e. a select with the multiple attribute) and the specified values are selected.

For example, given the following element:

<select id="favorite-colors" multiple>
  <option value="R">Red</option>
  <option value="G">Green</option>
  <option value="B">Blue</option>
</select>
const locator = page.locator("id=favorite-colors");
await locator.selectOption(["R", "G"]);
await expect(locator).toHaveValues([/R/, /G/]);

expect(page).not​

Added in: v1.20

Makes the assertion check for the opposite condition. For example, this code tests that the page URL doesn't contain "error":

await expect(page).not.toHaveURL('error');

expect(page).toHaveScreenshot(name[, options])​

Added in: v1.23

  • name <string|Array<string>> Snapshot name.#

  • options? <Object>

    • animations? <"disabled"|"allow"> When set to "disabled", stops CSS animations, CSS transitions and Web Animations. Animations get different treatment depending on their duration:#

      • finite animations are fast-forwarded to completion, so they'll fire transitionend event.
      • infinite animations are canceled to initial state, and then played over after the screenshot.

      Defaults to "disabled" that disables animations.

    • caret? <"hide"|"initial"> When set to "hide", screenshot will hide text caret. When set to "initial", text caret behavior will not be changed. Defaults to "hide".#

    • clip? <Object> An object which specifies clipping of the resulting image. Should have the following fields:#

      • x <number> x-coordinate of top-left corner of clip area
      • y <number> y-coordinate of top-left corner of clip area
      • width <number> width of clipping area
      • height <number> height of clipping area

    • fullPage? <boolean> When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Defaults to false.#

    • mask? <Array<Locator>> Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink box #FF00FF that completely covers its bounding box.#

    • maxDiffPixelRatio? <number> An acceptable ratio of pixels that are different to the total amount of pixels, between 0 and 1. Default is configurable with TestConfig.expect. Unset by default.#

    • maxDiffPixels? <number> An acceptable amount of pixels that could be different. Default is configurable with TestConfig.expect. Unset by default.#

    • omitBackground? <boolean> Hides default white background and allows capturing screenshots with transparency. Not applicable to jpeg images. Defaults to false.#

    • scale? <"css"|"device"> When set to "css", screenshot will have a single pixel per each css pixel on the page. For high-dpi devices, this will keep screenshots small. Using "device" option will produce a single pixel per each device pixel, so screenhots of high-dpi devices will be twice as large or even larger.#

      Defaults to "css".

    • threshold? <number> An acceptable perceived color difference in the YIQ color space between the same pixel in compared images, between zero (strict) and one (lax), default is configurable with TestConfig.expect. Defaults to 0.2.#

    • timeout? <number> Time to retry the assertion for. Defaults to timeout in TestConfig.expect.#

  • returns: <Promise<void>>#

This function will wait until two consecutive page screenshots yield the same result, and then compare the last screenshot with the expectation.

await expect(page).toHaveScreenshot('image.png');

expect(page).toHaveScreenshot([options])​

Added in: v1.23

  • options? <Object>

    • animations? <"disabled"|"allow"> When set to "disabled", stops CSS animations, CSS transitions and Web Animations. Animations get different treatment depending on their duration:#

      • finite animations are fast-forwarded to completion, so they'll fire transitionend event.
      • infinite animations are canceled to initial state, and then played over after the screenshot.

      Defaults to "disabled" that disables animations.

    • caret? <"hide"|"initial"> When set to "hide", screenshot will hide text caret. When set to "initial", text caret behavior will not be changed. Defaults to "hide".#

    • clip? <Object> An object which specifies clipping of the resulting image. Should have the following fields:#

      • x <number> x-coordinate of top-left corner of clip area
      • y <number> y-coordinate of top-left corner of clip area
      • width <number> width of clipping area
      • height <number> height of clipping area

    • fullPage? <boolean> When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Defaults to false.#

    • mask? <Array<Locator>> Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink box #FF00FF that completely covers its bounding box.#

    • maxDiffPixelRatio? <number> An acceptable ratio of pixels that are different to the total amount of pixels, between 0 and 1. Default is configurable with TestConfig.expect. Unset by default.#

    • maxDiffPixels? <number> An acceptable amount of pixels that could be different. Default is configurable with TestConfig.expect. Unset by default.#

    • omitBackground? <boolean> Hides default white background and allows capturing screenshots with transparency. Not applicable to jpeg images. Defaults to false.#

    • scale? <"css"|"device"> When set to "css", screenshot will have a single pixel per each css pixel on the page. For high-dpi devices, this will keep screenshots small. Using "device" option will produce a single pixel per each device pixel, so screenhots of high-dpi devices will be twice as large or even larger.#

      Defaults to "css".

    • threshold? <number> An acceptable perceived color difference in the YIQ color space between the same pixel in compared images, between zero (strict) and one (lax), default is configurable with TestConfig.expect. Defaults to 0.2.#

    • timeout? <number> Time to retry the assertion for. Defaults to timeout in TestConfig.expect.#

  • returns: <Promise<void>>#

This function will wait until two consecutive page screenshots yield the same result, and then compare the last screenshot with the expectation.

await expect(page).toHaveScreenshot();

expect(page).toHaveTitle(titleOrRegExp[, options])​

Added in: v1.20
  • titleOrRegExp <string|RegExp> Expected title or RegExp. Added in: v1.18#
  • options? <Object>
    • timeout? <number> Time to retry the assertion for. Defaults to timeout in TestConfig.expect. Added in: v1.18#
  • returns: <Promise<void>>#

Ensures the page has the given title.

await expect(page).toHaveTitle(/.*checkout/);

expect(page).toHaveURL(urlOrRegExp[, options])​

Added in: v1.20
  • urlOrRegExp <string|RegExp> Expected URL string or RegExp. Added in: v1.18#
  • options? <Object>
    • timeout? <number> Time to retry the assertion for. Defaults to timeout in TestConfig.expect. Added in: v1.18#
  • returns: <Promise<void>>#

Ensures the page is navigated to the given URL.

await expect(page).toHaveURL(/.*checkout/);

expect(apiResponse).not​

Added in: v1.20

Makes the assertion check for the opposite condition. For example, this code tests that the response status is not successful:

await expect(response).not.toBeOK();

expect(apiResponse).toBeOK()​

Added in: v1.18

Ensures the response status code is within 200..299 range.

await expect(response).toBeOK();

expect(screenshot).toMatchSnapshot(name[, options])​

Added in: v1.22
  • name <string|Array<string>> Snapshot name.#
  • options? <Object>
    • maxDiffPixelRatio? <number> An acceptable ratio of pixels that are different to the total amount of pixels, between 0 and 1. Default is configurable with TestConfig.expect. Unset by default.#
    • maxDiffPixels? <number> An acceptable amount of pixels that could be different. Default is configurable with TestConfig.expect. Unset by default.#
    • threshold? <number> An acceptable perceived color difference in the YIQ color space between the same pixel in compared images, between zero (strict) and one (lax), default is configurable with TestConfig.expect. Defaults to 0.2.#
  • returns: <void>#

Ensures that passed value, either a string or a Buffer, matches the expected snapshot stored in the test snapshots directory.

// Basic usage.
expect(await page.screenshot()).toMatchSnapshot('landing-page.png');

// Pass options to customize the snapshot comparison and have a generated name.
expect(await page.screenshot()).toMatchSnapshot('landing-page.png', {
  maxDiffPixels: 27, // allow no more than 27 different pixels.
});

// Configure image matching threshold.
expect(await page.screenshot()).toMatchSnapshot('landing-page.png', { threshold: 0.3 });

// Bring some structure to your snapshot files by passing file path segments.
expect(await page.screenshot()).toMatchSnapshot(['landing', 'step2.png']);
expect(await page.screenshot()).toMatchSnapshot(['landing', 'step3.png']);

Learn more about visual comparisons.

expect(screenshot).toMatchSnapshot([options])​

Added in: v1.22
  • options? <Object>
    • maxDiffPixelRatio? <number> An acceptable ratio of pixels that are different to the total amount of pixels, between 0 and 1. Default is configurable with TestConfig.expect. Unset by default.#
    • maxDiffPixels? <number> An acceptable amount of pixels that could be different. Default is configurable with TestConfig.expect. Unset by default.#
    • name? <string|Array<string>> Snapshot name. If not passed, the test name and ordinals are used when called multiple times.#
    • threshold? <number> An acceptable perceived color difference in the YIQ color space between the same pixel in compared images, between zero (strict) and one (lax), default is configurable with TestConfig.expect. Defaults to 0.2.#
  • returns: <void>#

Ensures that passed value, either a string or a Buffer, matches the expected snapshot stored in the test snapshots directory.

// Basic usage and the file name is derived from the test name.
expect(await page.screenshot()).toMatchSnapshot();

// Pass options to customize the snapshot comparison and have a generated name.
expect(await page.screenshot()).toMatchSnapshot({
  maxDiffPixels: 27, // allow no more than 27 different pixels.
});

// Configure image matching threshold and snapshot name.
expect(await page.screenshot()).toMatchSnapshot({
  name: 'landing-page.png',
  threshold: 0.3,
});

Learn more about visual comparisons.