Skip to main content

SnapshotAssertions

Playwright provides methods for comparing page and element screenshots with expected values stored in files.

expect(screenshot).toMatchSnapshot('landing-page.png');

Methods​

toMatchSnapshot(name)​

Added in: v1.22 snapshotAssertions.toMatchSnapshot(name)
caution

To compare screenshots, use expect(page).toHaveScreenshot() instead.

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

Usage

// 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.

Note that matching snapshots only work with Playwright test runner.

Arguments

  • name string | Array<string>#

    Snapshot name.

  • options Object (optional)

    • maxDiffPixelRatio number (optional)#

      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 (optional)#

      An acceptable amount of pixels that could be different. Default is configurable with TestConfig.expect. Unset by default.

    • threshold number (optional)#

      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.

toMatchSnapshot()​

Added in: v1.22 snapshotAssertions.toMatchSnapshot()
caution

To compare screenshots, use expect(page).toHaveScreenshot() instead.

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

Usage

// 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.

Note that matching snapshots only work with Playwright test runner.

Arguments

  • options Object (optional)

    • maxDiffPixelRatio number (optional)#

      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 (optional)#

      An acceptable amount of pixels that could be different. Default is configurable with TestConfig.expect. Unset by default.

    • name string | Array<string> (optional)#

      Snapshot name. If not passed, the test name and ordinals are used when called multiple times.

    • threshold number (optional)#

      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.