Skip to content

Commit

Permalink
cherry-pick(microsoft#27089): fix: revert toMatchSnapshot deprecation
Browse files Browse the repository at this point in the history 
- This reverts commit
microsoft@8348f66
landed in microsoft#26718.
- Update docs to point towards `toHaveScreenshot`.
  • Loading branch information
@dgozman
dgozman committed Sep 14, 2023
1 parent da997ee commit aa22c17
Show file tree
Hide file tree
Showing 12 changed files with 178 additions and 209 deletions.
89 changes: 20 additions & 69 deletions docs/src/api/class-snapshotassertions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,75 +2,24 @@
* since: v1.20
* langs: js

:::tip
For visual regression testing, use [`method: PageAssertions.toHaveScreenshot#1`] and [`method: LocatorAssertions.toHaveScreenshot#1`] instead.
:::

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

```js
expect(text).toMatchSnapshot('snapshot.txt');
expect(screenshot).toMatchSnapshot('landing-page.png');
```

## method: SnapshotAssertions.toMatchSnapshot#1
* since: v1.22

Ensures that the passed [string] matches the expected snapshot stored in the test snapshots directory.

**Usage**

```js
// Basic usage.
expect(await page.title()).toMatchSnapshot('page-title.txt');

// Bring some structure to your snapshot files by passing file path segments.
expect(await page.title()).toMatchSnapshot(['page-title', 'step1.txt']);
expect(await page.title()).toMatchSnapshot(['page-title', 'step2.txt']);
```

Note that matching snapshots only work with Playwright test runner.

### param: SnapshotAssertions.toMatchSnapshot#1.name
* since: v1.22
- `name` <[string]|[Array]<[string]>>

Snapshot name.

## method: SnapshotAssertions.toMatchSnapshot#2
* since: v1.22
:::caution
To compare screenshots, use [`method: PageAssertions.toHaveScreenshot#1`] instead.
:::

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

**Usage**

```js
// Basic usage.
expect(await page.title()).toMatchSnapshot();

// Configure the snapshot name.
expect(await page.title()).toMatchSnapshot({
name: 'page-title.txt',
});
```

Note that matching snapshots only work with Playwright test runner.

### option: SnapshotAssertions.toMatchSnapshot#2.name
* since: v1.22
- `name` <[string]|[Array]<[string]>>

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



## method: SnapshotAssertions.toMatchSnapshot#3
* deprecated: To avoid flakiness, use [`method: PageAssertions.toHaveScreenshot#1`] instead.
* since: v1.22

Ensures that the passed [Buffer] matches the expected snapshot stored in the test snapshots directory.

**Usage**

```js
// Basic usage.
expect(await page.screenshot()).toMatchSnapshot('landing-page.png');
Expand All @@ -92,26 +41,29 @@ Learn more about [visual comparisons](../test-snapshots.md).

Note that matching snapshots only work with Playwright test runner.

### param: SnapshotAssertions.toMatchSnapshot#3.name
### param: SnapshotAssertions.toMatchSnapshot#1.name
* since: v1.22
- `name` <[string]|[Array]<[string]>>

Snapshot name.

### option: SnapshotAssertions.toMatchSnapshot#3.maxDiffPixels = %%-assertions-max-diff-pixels-%%
### option: SnapshotAssertions.toMatchSnapshot#1.maxDiffPixels = %%-assertions-max-diff-pixels-%%
* since: v1.22

### option: SnapshotAssertions.toMatchSnapshot#3.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%
### option: SnapshotAssertions.toMatchSnapshot#1.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%
* since: v1.22

### option: SnapshotAssertions.toMatchSnapshot#3.threshold = %%-assertions-threshold-%%
### option: SnapshotAssertions.toMatchSnapshot#1.threshold = %%-assertions-threshold-%%
* since: v1.22

## method: SnapshotAssertions.toMatchSnapshot#4
* deprecated: To avoid flakiness, use [`method: PageAssertions.toHaveScreenshot#1`] instead.
## method: SnapshotAssertions.toMatchSnapshot#2
* since: v1.22

Ensures that the passed [Buffer] matches the expected snapshot stored in the test snapshots directory.
:::caution
To compare screenshots, use [`method: PageAssertions.toHaveScreenshot#2`] instead.
:::

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

**Usage**

Expand All @@ -135,18 +87,17 @@ Learn more about [visual comparisons](../test-snapshots.md).

Note that matching snapshots only work with Playwright test runner.

### option: SnapshotAssertions.toMatchSnapshot#4.maxDiffPixels = %%-assertions-max-diff-pixels-%%
### option: SnapshotAssertions.toMatchSnapshot#2.maxDiffPixels = %%-assertions-max-diff-pixels-%%
* since: v1.22

### option: SnapshotAssertions.toMatchSnapshot#4.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%
### option: SnapshotAssertions.toMatchSnapshot#2.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%
* since: v1.22

### option: SnapshotAssertions.toMatchSnapshot#4.name
### option: SnapshotAssertions.toMatchSnapshot#2.name
* since: v1.22
- `name` <[string]|[Array]<[string]>>

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

### option: SnapshotAssertions.toMatchSnapshot#4.threshold = %%-assertions-threshold-%%
### option: SnapshotAssertions.toMatchSnapshot#2.threshold = %%-assertions-threshold-%%
* since: v1.22

2 changes: 0 additions & 2 deletions docs/src/release-notes-js.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,6 @@ import LiteYouTube from '@site/src/components/LiteYouTube';
Please use [`method: Locator.fill`] instead which is much faster. Use
[`method: Locator.pressSequentially`] only if there is a special keyboard
handling on the page, and you need to press keys one-by-one.
* The method [`method: SnapshotAssertions.toMatchSnapshot#1`] is deprecated in
favor of [`method: PageAssertions.toHaveScreenshot#1`] and [`method: LocatorAssertions.toHaveScreenshot#1`].

### Breaking Changes: Playwright no longer downloads browsers automatically

Expand Down
20 changes: 10 additions & 10 deletions docs/src/test-api/class-testconfig.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,18 +41,18 @@ export default defineConfig({
- type: ?<[Object]>
- `timeout` ?<[int]> Default timeout for async expect matchers in milliseconds, defaults to 5000ms.
- `toHaveScreenshot` ?<[Object]> Configuration for the [`method: PageAssertions.toHaveScreenshot#1`] method.
- `threshold` ?<[float]> An acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and `1` (lax). `"pixelmatch"` comparator computes color difference in [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`.
- `maxDiffPixels` ?<[int]> An acceptable amount of pixels that could be different, unset by default.
- `maxDiffPixelRatio` ?<[float]> An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by default.
- `threshold` ?<[float]> an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and `1` (lax). `"pixelmatch"` comparator computes color difference in [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`.
- `maxDiffPixels` ?<[int]> an acceptable amount of pixels that could be different, unset by default.
- `maxDiffPixelRatio` ?<[float]> an acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by default.
- `animations` ?<[ScreenshotAnimations]<"allow"|"disabled">> See [`option: animations`] in [`method: Page.screenshot`]. Defaults to `"disabled"`.
- `caret` ?<[ScreenshotCaret]<"hide"|"initial">> See [`option: caret`] in [`method: Page.screenshot`]. Defaults to `"hide"`.
- `scale` ?<[ScreenshotScale]<"css"|"device">> See [`option: scale`] in [`method: Page.screenshot`]. Defaults to `"css"`.
- `toMatchSnapshot` ?<[Object]> Configuration for the [`method: SnapshotAssertions.toMatchSnapshot#1`] method.
- `threshold` ?<[float]> **Deprecated.** An acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and `1` (lax). `"pixelmatch"` comparator computes color difference in [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`.
- `maxDiffPixels` ?<[int]> **Deprecated.** An acceptable amount of pixels that could be different, unset by default.
- `maxDiffPixelRatio` ?<[float]> **Deprecated.** An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by default.
- `threshold` ?<[float]> an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and `1` (lax). `"pixelmatch"` comparator computes color difference in [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`.
- `maxDiffPixels` ?<[int]> an acceptable amount of pixels that could be different, unset by default.
- `maxDiffPixelRatio` ?<[float]> an acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by default.

Configuration for the `expect` assertion library. Learn more about [test configuration](../test-configuration.md#expect-options).
Configuration for the `expect` assertion library. Learn more about [various timeouts](../test-timeouts.md).

**Usage**

Expand All @@ -62,7 +62,7 @@ import { defineConfig } from '@playwright/test';
export default defineConfig({
expect: {
timeout: 10000,
toHaveScreenshot: {
toMatchSnapshot: {
maxDiffPixels: 10,
},
},
Expand Down Expand Up @@ -196,7 +196,7 @@ export default defineConfig({
* since: v1.26
- type: ?<[boolean]>

Whether to skip snapshot expectations, such as [`method: PageAssertions.toHaveScreenshot#1`] and [`method: SnapshotAssertions.toMatchSnapshot#1`].
Whether to skip snapshot expectations, such as `expect(value).toMatchSnapshot()` and `await expect(page).toHaveScreenshot()`.

**Usage**

Expand Down Expand Up @@ -296,7 +296,7 @@ test('example test', async ({}, testInfo) => {
* discouraged: Use [`property: TestConfig.snapshotPathTemplate`] to configure snapshot paths.
- type: ?<[string]>

The base directory, relative to the config file, for screenshot files created with [`method: PageAssertions.toHaveScreenshot#1`]. Defaults to [`property: TestConfig.testDir`].
The base directory, relative to the config file, for snapshot files created with `toMatchSnapshot`. Defaults to [`property: TestConfig.testDir`].

**Usage**

Expand Down
2 changes: 1 addition & 1 deletion docs/src/test-api/class-testinfo.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -397,7 +397,7 @@ Use of [`property: TestInfo.snapshotSuffix`] is discouraged. Please use [`proper
snapshot paths.
:::

Suffix used to differentiate snapshots between multiple test configurations. For example, if snapshots depend on the platform, you can set `testInfo.snapshotSuffix` equal to `process.platform`. In this case [`method: PageAssertions.toHaveScreenshot#1`] will use different snapshots depending on the platform. Learn more about [snapshots](../test-snapshots.md).
Suffix used to differentiate snapshots between multiple test configurations. For example, if snapshots depend on the platform, you can set `testInfo.snapshotSuffix` equal to `process.platform`. In this case `expect(value).toMatchSnapshot(snapshotName)` will use different snapshots depending on the platform. Learn more about [snapshots](../test-snapshots.md).

## property: TestInfo.status
* since: v1.10
Expand Down
12 changes: 6 additions & 6 deletions docs/src/test-api/class-testproject.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -91,16 +91,16 @@ export default defineConfig({
- type: ?<[Object]>
- `timeout` ?<[int]> Default timeout for async expect matchers in milliseconds, defaults to 5000ms.
- `toHaveScreenshot` ?<[Object]> Configuration for the [`method: PageAssertions.toHaveScreenshot#1`] method.
- `threshold` ?<[float]> An acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and `1` (lax). `"pixelmatch"` comparator computes color difference in [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`.
- `maxDiffPixels` ?<[int]> An acceptable amount of pixels that could be different, unset by default.
- `maxDiffPixelRatio` ?<[float]> An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by default.
- `threshold` ?<[float]> an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and `1` (lax). `"pixelmatch"` comparator computes color difference in [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`.
- `maxDiffPixels` ?<[int]> an acceptable amount of pixels that could be different, unset by default.
- `maxDiffPixelRatio` ?<[float]> an acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by default.
- `animations` ?<[ScreenshotAnimations]<"allow"|"disabled">> See [`option: animations`] in [`method: Page.screenshot`]. Defaults to `"disabled"`.
- `caret` ?<[ScreenshotCaret]<"hide"|"initial">> See [`option: caret`] in [`method: Page.screenshot`]. Defaults to `"hide"`.
- `scale` ?<[ScreenshotScale]<"css"|"device">> See [`option: scale`] in [`method: Page.screenshot`]. Defaults to `"css"`.
- `toMatchSnapshot` ?<[Object]> Configuration for the [`method: SnapshotAssertions.toMatchSnapshot#1`] method.
- `threshold` ?<[float]> **Deprecated.** An acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and `1` (lax). `"pixelmatch"` comparator computes color difference in [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`.
- `maxDiffPixels` ?<[int]> **Deprecated.** An acceptable amount of pixels that could be different, unset by default.
- `maxDiffPixelRatio` ?<[float]> **Deprecated.** An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by default.
- `threshold` ?<[float]> an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and `1` (lax). `"pixelmatch"` comparator computes color difference in [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`.
- `maxDiffPixels` ?<[int]> an acceptable amount of pixels that could be different, unset by default.
- `maxDiffPixelRatio` ?<[float]> an acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by default.

Configuration for the `expect` assertion library.

Expand Down
1 change: 0 additions & 1 deletion docs/src/test-assertions-js.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,6 @@ Prefer [auto-retrying](#auto-retrying-assertions) assertions whenever possible.
| [`method: GenericAssertions.toHaveProperty`] | Object has a property |
| [`method: GenericAssertions.toMatch`] | String matches a regular expression |
| [`method: GenericAssertions.toMatchObject`] | Object contains specified properties |
| [`method: SnapshotAssertions.toMatchSnapshot#1`] | String equals a reference value, stored in a snapshot file |
| [`method: GenericAssertions.toStrictEqual`] | Value is similar, including property types |
| [`method: GenericAssertions.toThrow`] | Function throws an error |
| [`method: GenericAssertions.any`] | Matches any instance of a class/primitive |
Expand Down
11 changes: 9 additions & 2 deletions docs/src/test-configuration-js.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -131,15 +131,22 @@ export default defineConfig({
// An acceptable amount of pixels that could be different, unset by default.
maxDiffPixels: 10,
},

toMatchSnapshot: {
// An acceptable ratio of pixels that are different to the
// total amount of pixels, between 0 and 1.
maxDiffPixelRatio: 0.1,
},
},

});
```

| Option | Description |
| :- | :- |
| `expect.timeout` | [Web first assertions](./test-assertions.md) like `expect(locator).toHaveText()` have a separate timeout of 5 seconds by default. This is the maximum time the `expect()` should wait for the condition to be met. Learn more about [test and expect timeouts](./test-timeouts.md) and how to set them for a single test. |
| `expect.toHaveScreenshot` | Configuration for [`method: PageAssertions.toHaveScreenshot#1`] and [`method: LocatorAssertions.toHaveScreenshot#1`] methods. |
| [`property: TestConfig.expect`] | [Web first assertions](./test-assertions.md) like `expect(locator).toHaveText()` have a separate timeout of 5 seconds by default. This is the maximum time the `expect()` should wait for the condition to be met. Learn more about [test and expect timeouts](./test-timeouts.md) and how to set them for a single test. |
| [`method: PageAssertions.toHaveScreenshot#1`] | Configuration for the `expect(locator).toHaveScreeshot()` method. |
| [`method: SnapshotAssertions.toMatchSnapshot#1`]| Configuration for the `expect(locator).toMatchSnapshot()` method.|


### Add custom matchers using expect.extend
Expand Down
Loading

0 comments on commit aa22c17

Please sign in to comment.