feat: deprecate toMatchSnapshot for buffers (#26718)
These are usually used for screenshots instead of toHaveScreenshot. String-based snapshots are left as is. <img width="836" alt="deprecated" src="https://github.com/microsoft/playwright/assets/9881434/d02818da-7eea-47fc-8ea8-4104b0dd49b5"> --- Also deemphasized toMatchSnapshot throughout all docs. Fixes #26612.
This commit is contained in:
Dmitry Gozman
GitHub
Родитель
bc1f6272d8
Коммит
8348f66107
|
|
@ -2,20 +2,75 @@
|
|||
* since: v1.20
|
||||
* langs: js
|
||||
|
||||
Playwright provides methods for comparing page and element screenshots with
|
||||
expected values stored in files.
|
||||
:::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.
|
||||
|
||||
```js
|
||||
expect(screenshot).toMatchSnapshot('landing-page.png');
|
||||
expect(text).toMatchSnapshot('snapshot.txt');
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
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');
|
||||
|
|
@ -37,25 +92,26 @@ Learn more about [visual comparisons](../test-snapshots.md).
|
|||
|
||||
Note that matching snapshots only work with Playwright test runner.
|
||||
|
||||
### param: SnapshotAssertions.toMatchSnapshot#1.name
|
||||
### param: SnapshotAssertions.toMatchSnapshot#3.name
|
||||
* since: v1.22
|
||||
- `name` <[string]|[Array]<[string]>>
|
||||
|
||||
Snapshot name.
|
||||
|
||||
### option: SnapshotAssertions.toMatchSnapshot#1.maxDiffPixels = %%-assertions-max-diff-pixels-%%
|
||||
### option: SnapshotAssertions.toMatchSnapshot#3.maxDiffPixels = %%-assertions-max-diff-pixels-%%
|
||||
* since: v1.22
|
||||
|
||||
### option: SnapshotAssertions.toMatchSnapshot#1.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%
|
||||
### option: SnapshotAssertions.toMatchSnapshot#3.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%
|
||||
* since: v1.22
|
||||
|
||||
### option: SnapshotAssertions.toMatchSnapshot#1.threshold = %%-assertions-threshold-%%
|
||||
### option: SnapshotAssertions.toMatchSnapshot#3.threshold = %%-assertions-threshold-%%
|
||||
* since: v1.22
|
||||
|
||||
## method: SnapshotAssertions.toMatchSnapshot#2
|
||||
## method: SnapshotAssertions.toMatchSnapshot#4
|
||||
* deprecated: To avoid flakiness, use [`method: PageAssertions.toHaveScreenshot#1`] instead.
|
||||
* since: v1.22
|
||||
|
||||
Ensures that passed value, either a [string] or a [Buffer], matches the expected snapshot stored in the test snapshots directory.
|
||||
Ensures that the passed [Buffer] matches the expected snapshot stored in the test snapshots directory.
|
||||
|
||||
**Usage**
|
||||
|
||||
|
|
@ -79,17 +135,18 @@ Learn more about [visual comparisons](../test-snapshots.md).
|
|||
|
||||
Note that matching snapshots only work with Playwright test runner.
|
||||
|
||||
### option: SnapshotAssertions.toMatchSnapshot#2.maxDiffPixels = %%-assertions-max-diff-pixels-%%
|
||||
### option: SnapshotAssertions.toMatchSnapshot#4.maxDiffPixels = %%-assertions-max-diff-pixels-%%
|
||||
* since: v1.22
|
||||
|
||||
### option: SnapshotAssertions.toMatchSnapshot#2.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%
|
||||
### option: SnapshotAssertions.toMatchSnapshot#4.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%
|
||||
* since: v1.22
|
||||
|
||||
### option: SnapshotAssertions.toMatchSnapshot#2.name
|
||||
### option: SnapshotAssertions.toMatchSnapshot#4.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#2.threshold = %%-assertions-threshold-%%
|
||||
### option: SnapshotAssertions.toMatchSnapshot#4.threshold = %%-assertions-threshold-%%
|
||||
* since: v1.22
|
||||
|
||||
|
|
|
|||
|
|
@ -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]> 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]> **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.
|
||||
|
||||
Configuration for the `expect` assertion library. Learn more about [various timeouts](../test-timeouts.md).
|
||||
Configuration for the `expect` assertion library. Learn more about [test configuration](../test-configuration.md#expect-options).
|
||||
|
||||
**Usage**
|
||||
|
||||
|
|
@ -62,7 +62,7 @@ import { defineConfig } from '@playwright/test';
|
|||
export default defineConfig({
|
||||
expect: {
|
||||
timeout: 10000,
|
||||
toMatchSnapshot: {
|
||||
toHaveScreenshot: {
|
||||
maxDiffPixels: 10,
|
||||
},
|
||||
},
|
||||
|
|
@ -196,7 +196,7 @@ export default defineConfig({
|
|||
* since: v1.26
|
||||
- type: ?<[boolean]>
|
||||
|
||||
Whether to skip snapshot expectations, such as `expect(value).toMatchSnapshot()` and `await expect(page).toHaveScreenshot()`.
|
||||
Whether to skip snapshot expectations, such as [`method: PageAssertions.toHaveScreenshot#1`] and [`method: SnapshotAssertions.toMatchSnapshot#1`].
|
||||
|
||||
**Usage**
|
||||
|
||||
|
|
@ -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 snapshot files created with `toMatchSnapshot`. Defaults to [`property: TestConfig.testDir`].
|
||||
The base directory, relative to the config file, for screenshot files created with [`method: PageAssertions.toHaveScreenshot#1`]. Defaults to [`property: TestConfig.testDir`].
|
||||
|
||||
**Usage**
|
||||
|
||||
|
|
|
|||
|
|
@ -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 `expect(value).toMatchSnapshot(snapshotName)` 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 [`method: PageAssertions.toHaveScreenshot#1`] will use different snapshots depending on the platform. Learn more about [snapshots](../test-snapshots.md).
|
||||
|
||||
## property: TestInfo.status
|
||||
* since: v1.10
|
||||
|
|
|
|||
|
|
@ -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]> 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]> **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.
|
||||
|
||||
Configuration for the `expect` assertion library.
|
||||
|
||||
|
|
|
|||
|
|
@ -82,6 +82,7 @@ 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 |
|
||||
|
|
|
|||
|
|
@ -131,12 +131,6 @@ 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,
|
||||
},
|
||||
},
|
||||
|
||||
});
|
||||
|
|
@ -144,9 +138,8 @@ export default defineConfig({
|
|||
|
||||
| Option | Description |
|
||||
| :- | :- |
|
||||
| [`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.|
|
||||
| `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. |
|
||||
|
||||
|
||||
### Add custom matchers using expect.extend
|
||||
|
|
|
|||
|
|
@ -20,10 +20,10 @@ When you run above for the first time, test runner will say:
|
|||
Error: A snapshot doesn't exist at example.spec.ts-snapshots/example-test-1-chromium-darwin.png, writing actual.
|
||||
```
|
||||
|
||||
That's because there was no golden file yet. This method took a bunch of screenshots until two consecutive
|
||||
screenshots matched, and saved the last screenshot to file system. It is now ready to be added to the repository.
|
||||
That's because there was no reference screenshot yet. This method took a bunch of screenshots until two consecutive
|
||||
screenshots matched, and saved the last screenshot to file system. It is now ready to be added to the repository. You should review any changes to the reference screenshots to make sure they are expected.
|
||||
|
||||
The name of the folder with the golden expectations starts with the name of your test file:
|
||||
The name of the folder with the reference screenshots starts with the name of your test file:
|
||||
|
||||
```bash
|
||||
drwxr-xr-x 5 user group 160 Jun 4 11:46 .
|
||||
|
|
@ -32,7 +32,7 @@ drwxr-xr-x 6 user group 192 Jun 4 11:45 ..
|
|||
drwxr-xr-x 3 user group 96 Jun 4 11:46 example.spec.ts-snapshots
|
||||
```
|
||||
|
||||
The snapshot name `example-test-1-chromium-darwin.png` consists of a few parts:
|
||||
The name of the reference screenshot `example-test-1-chromium-darwin.png` consists of a few parts:
|
||||
- `example-test-1.png` - an auto-generated name of the snapshot. Alternatively you can specify snapshot name as the first argument of the `toHaveScreenshot()` method:
|
||||
```js
|
||||
await expect(page).toHaveScreenshot('landing.png');
|
||||
|
|
@ -40,13 +40,7 @@ The snapshot name `example-test-1-chromium-darwin.png` consists of a few parts:
|
|||
|
||||
- `chromium-darwin` - the browser name and the platform. Screenshots differ between browsers and platforms due to different rendering, fonts and more, so you will need different snapshots for them. If you use multiple projects in your [configuration file](./test-configuration.md), project name will be used instead of `chromium`.
|
||||
|
||||
If you are not on the same operating system as your CI system, you can use Docker to generate/update the screenshots:
|
||||
|
||||
```bash
|
||||
docker run --rm --network host -v $(pwd):/work/ -w /work/ -it mcr.microsoft.com/playwright:v%%VERSION%%-jammy /bin/bash
|
||||
npm install
|
||||
npx playwright test --update-snapshots
|
||||
```
|
||||
You can customize the name and the path of the reference screnshot by modifying [`property: TestProject.snapshotPathTemplate`] property in the config file.
|
||||
|
||||
Sometimes you need to update the reference screenshot, for example when the page has changed. Do this with the `--update-snapshots` flag.
|
||||
|
||||
|
|
@ -54,9 +48,6 @@ Sometimes you need to update the reference screenshot, for example when the page
|
|||
npx playwright test --update-snapshots
|
||||
```
|
||||
|
||||
> Note that `snapshotName` also accepts an array of path segments to the snapshot file such as `expect().toHaveScreenshot(['relative', 'path', 'to', 'snapshot.png'])`.
|
||||
> However, this path must stay within the snapshots directory for each test file (i.e. `a.spec.js-snapshots`), otherwise it will throw.
|
||||
|
||||
Playwright Test uses the [pixelmatch](https://github.com/mapbox/pixelmatch) library. You can [pass various options](./api/class-pageassertions.md#page-assertions-to-have-screenshot-1) to modify its behavior:
|
||||
|
||||
```js title="example.spec.ts"
|
||||
|
|
@ -79,17 +70,10 @@ export default defineConfig({
|
|||
});
|
||||
```
|
||||
|
||||
Apart from screenshots, you can use `expect(value).toMatchSnapshot(snapshotName)` to compare text or arbitrary binary data. Playwright Test auto-detects the content type and uses the appropriate comparison algorithm.
|
||||
If you are not on the same operating system as your CI system, you can use Docker to generate/update the screenshots:
|
||||
|
||||
Here we compare text content against the reference.
|
||||
|
||||
```js title="example.spec.ts"
|
||||
import { test, expect } from '@playwright/test';
|
||||
|
||||
test('example test', async ({ page }) => {
|
||||
await page.goto('https://playwright.dev');
|
||||
expect(await page.textContent('.hero__title')).toMatchSnapshot('hero.txt');
|
||||
});
|
||||
```bash
|
||||
docker run --rm --network host -v $(pwd):/work/ -w /work/ -it mcr.microsoft.com/playwright:v%%VERSION%%-jammy /bin/bash
|
||||
npm install
|
||||
npx playwright test --update-snapshots
|
||||
```
|
||||
|
||||
Snapshots are stored next to the test file, in a separate directory. For example, `my.spec.ts` file will produce and store snapshots in the `my.spec.ts-snapshots` directory. You should commit this directory to your version control (e.g. `git`), and review any changes to it.
|
||||
|
|
|
|||
|
|
@ -595,7 +595,8 @@ interface TestConfig {
|
|||
};
|
||||
|
||||
/**
|
||||
* Configuration for the `expect` assertion library. Learn more about [various timeouts](https://playwright.dev/docs/test-timeouts).
|
||||
* Configuration for the `expect` assertion library. Learn more about
|
||||
* [test configuration](https://playwright.dev/docs/test-configuration#expect-options).
|
||||
*
|
||||
* **Usage**
|
||||
*
|
||||
|
|
@ -606,7 +607,7 @@ interface TestConfig {
|
|||
* export default defineConfig({
|
||||
* expect: {
|
||||
* timeout: 10000,
|
||||
* toMatchSnapshot: {
|
||||
* toHaveScreenshot: {
|
||||
* maxDiffPixels: 10,
|
||||
* },
|
||||
* },
|
||||
|
|
@ -627,19 +628,19 @@ interface TestConfig {
|
|||
*/
|
||||
toHaveScreenshot?: {
|
||||
/**
|
||||
* an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and
|
||||
* 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`.
|
||||
*/
|
||||
threshold?: number;
|
||||
|
||||
/**
|
||||
* an acceptable amount of pixels that could be different, unset by default.
|
||||
* An acceptable amount of pixels that could be different, unset by default.
|
||||
*/
|
||||
maxDiffPixels?: number;
|
||||
|
||||
/**
|
||||
* an acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by
|
||||
* An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by
|
||||
* default.
|
||||
*/
|
||||
maxDiffPixelRatio?: number;
|
||||
|
|
@ -665,25 +666,25 @@ interface TestConfig {
|
|||
|
||||
/**
|
||||
* Configuration for the
|
||||
* [snapshotAssertions.toMatchSnapshot(name[, options])](https://playwright.dev/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1)
|
||||
* [snapshotAssertions.toMatchSnapshot(name)](https://playwright.dev/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1)
|
||||
* method.
|
||||
*/
|
||||
toMatchSnapshot?: {
|
||||
/**
|
||||
* 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
|
||||
* **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`.
|
||||
*/
|
||||
threshold?: number;
|
||||
|
||||
/**
|
||||
* an acceptable amount of pixels that could be different, unset by default.
|
||||
* **Deprecated.** An acceptable amount of pixels that could be different, unset by default.
|
||||
*/
|
||||
maxDiffPixels?: number;
|
||||
|
||||
/**
|
||||
* an acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by
|
||||
* default.
|
||||
* **Deprecated.** An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1`
|
||||
* , unset by default.
|
||||
*/
|
||||
maxDiffPixelRatio?: number;
|
||||
};
|
||||
|
|
@ -833,8 +834,10 @@ interface TestConfig {
|
|||
grepInvert?: RegExp|Array<RegExp>;
|
||||
|
||||
/**
|
||||
* Whether to skip snapshot expectations, such as `expect(value).toMatchSnapshot()` and `await
|
||||
* expect(page).toHaveScreenshot()`.
|
||||
* Whether to skip snapshot expectations, such as
|
||||
* [pageAssertions.toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1)
|
||||
* and
|
||||
* [snapshotAssertions.toMatchSnapshot(name)](https://playwright.dev/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1).
|
||||
*
|
||||
* **Usage**
|
||||
*
|
||||
|
|
@ -1103,8 +1106,9 @@ interface TestConfig {
|
|||
* [testConfig.snapshotPathTemplate](https://playwright.dev/docs/api/class-testconfig#test-config-snapshot-path-template)
|
||||
* to configure snapshot paths.
|
||||
*
|
||||
* The base directory, relative to the config file, for snapshot files created with `toMatchSnapshot`. Defaults to
|
||||
* [testConfig.testDir](https://playwright.dev/docs/api/class-testconfig#test-config-test-dir).
|
||||
* The base directory, relative to the config file, for screenshot files created with
|
||||
* [pageAssertions.toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1).
|
||||
* Defaults to [testConfig.testDir](https://playwright.dev/docs/api/class-testconfig#test-config-test-dir).
|
||||
*
|
||||
* **Usage**
|
||||
*
|
||||
|
|
@ -1133,7 +1137,7 @@ interface TestConfig {
|
|||
* This option configures a template controlling location of snapshots generated by
|
||||
* [pageAssertions.toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1)
|
||||
* and
|
||||
* [snapshotAssertions.toMatchSnapshot(name[, options])](https://playwright.dev/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1).
|
||||
* [snapshotAssertions.toMatchSnapshot(name)](https://playwright.dev/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1).
|
||||
*
|
||||
* **Usage**
|
||||
*
|
||||
|
|
@ -2267,8 +2271,8 @@ export interface TestInfo {
|
|||
*
|
||||
* 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](https://playwright.dev/docs/test-snapshots).
|
||||
* [pageAssertions.toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1)
|
||||
* will use different snapshots depending on the platform. Learn more about [snapshots](https://playwright.dev/docs/test-snapshots).
|
||||
*/
|
||||
snapshotSuffix: string;
|
||||
|
||||
|
|
@ -5071,6 +5075,27 @@ type FunctionAssertions = {
|
|||
toPass(options?: { timeout?: number, intervals?: number[] }): Promise<void>;
|
||||
};
|
||||
|
||||
type BufferAssertions = {
|
||||
/**
|
||||
* Ensures that the passed [Buffer] matches the expected snapshot stored in the test snapshots directory.
|
||||
* @deprecated To avoid flakiness, use
|
||||
* [pageAssertions.toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1)
|
||||
* instead.
|
||||
* @param name Snapshot name.
|
||||
* @param options
|
||||
*/
|
||||
toMatchSnapshot(name: string | Array<string>, options?: { maxDiffPixelRatio?: number, maxDiffPixels?: number, threshold?: number }): void;
|
||||
|
||||
/**
|
||||
* Ensures that the passed [Buffer] matches the expected snapshot stored in the test snapshots directory.
|
||||
* @deprecated To avoid flakiness, use
|
||||
* [pageAssertions.toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1)
|
||||
* instead.
|
||||
* @param options
|
||||
*/
|
||||
toMatchSnapshot(options?: { maxDiffPixelRatio?: number, maxDiffPixels?: number, name?: string|Array<string>, threshold?: number }): void;
|
||||
};
|
||||
|
||||
type BaseMatchers<R, T> = GenericAssertions<R> & PlaywrightTest.Matchers<R, T> & SnapshotAssertions;
|
||||
type AllowedGenericMatchers<R> = Pick<GenericAssertions<R>, 'toBe' | 'toBeDefined' | 'toBeFalsy' | 'toBeNull' | 'toBeTruthy' | 'toBeUndefined'>;
|
||||
|
||||
|
|
@ -5078,6 +5103,7 @@ type SpecificMatchers<R, T> =
|
|||
T extends Page ? PageAssertions & AllowedGenericMatchers<R> :
|
||||
T extends Locator ? LocatorAssertions & AllowedGenericMatchers<R> :
|
||||
T extends APIResponse ? APIResponseAssertions & AllowedGenericMatchers<R> :
|
||||
T extends Buffer ? BufferAssertions & GenericAssertions<R> & PlaywrightTest.Matchers<R, T> :
|
||||
BaseMatchers<R, T> & (T extends Function ? FunctionAssertions : {});
|
||||
type AllMatchers<R, T> = PageAssertions & LocatorAssertions & APIResponseAssertions & FunctionAssertions & BaseMatchers<R, T>;
|
||||
|
||||
|
|
@ -6221,14 +6247,39 @@ interface PageAssertions {
|
|||
}
|
||||
|
||||
/**
|
||||
* Playwright provides methods for comparing page and element screenshots with expected values stored in files.
|
||||
* **NOTE** For visual regression testing, use
|
||||
* [pageAssertions.toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1)
|
||||
* and
|
||||
* [locatorAssertions.toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-1)
|
||||
* instead.
|
||||
*
|
||||
* Playwright provides methods for comparing text values with expected values stored in snapshot files.
|
||||
*
|
||||
* ```js
|
||||
* expect(screenshot).toMatchSnapshot('landing-page.png');
|
||||
* expect(text).toMatchSnapshot('snapshot.txt');
|
||||
* ```
|
||||
*
|
||||
*/
|
||||
interface SnapshotAssertions {
|
||||
/**
|
||||
* 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 name Snapshot name.
|
||||
*/
|
||||
toMatchSnapshot(name: string|Array<string>): void;
|
||||
|
||||
/**
|
||||
* Ensures that passed value, either a [string] or a [Buffer], matches the expected snapshot stored in the test
|
||||
* snapshots directory.
|
||||
|
|
@ -6237,99 +6288,22 @@ interface SnapshotAssertions {
|
|||
*
|
||||
* ```js
|
||||
* // Basic usage.
|
||||
* expect(await page.screenshot()).toMatchSnapshot('landing-page.png');
|
||||
* expect(await page.title()).toMatchSnapshot();
|
||||
*
|
||||
* // 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](https://playwright.dev/docs/test-snapshots).
|
||||
*
|
||||
* Note that matching snapshots only work with Playwright test runner.
|
||||
* @param name Snapshot name.
|
||||
* @param options
|
||||
*/
|
||||
toMatchSnapshot(name: string|Array<string>, options?: {
|
||||
/**
|
||||
* 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.
|
||||
*/
|
||||
maxDiffPixelRatio?: number;
|
||||
|
||||
/**
|
||||
* An acceptable amount of pixels that could be different. Default is configurable with `TestConfig.expect`. Unset by
|
||||
* default.
|
||||
*/
|
||||
maxDiffPixels?: number;
|
||||
|
||||
/**
|
||||
* An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the
|
||||
* same pixel in compared images, between zero (strict) and one (lax), default is configurable with
|
||||
* `TestConfig.expect`. Defaults to `0.2`.
|
||||
*/
|
||||
threshold?: number;
|
||||
}): void;
|
||||
|
||||
/**
|
||||
* Ensures that passed value, either a [string] or a [Buffer], matches the expected snapshot stored in the test
|
||||
* snapshots directory.
|
||||
*
|
||||
* **Usage**
|
||||
*
|
||||
* ```js
|
||||
* // 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,
|
||||
* // Configure the snapshot name.
|
||||
* expect(await page.title()).toMatchSnapshot({
|
||||
* name: 'page-title.txt',
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* Learn more about [visual comparisons](https://playwright.dev/docs/test-snapshots).
|
||||
*
|
||||
* Note that matching snapshots only work with Playwright test runner.
|
||||
* @param options
|
||||
*/
|
||||
toMatchSnapshot(options?: {
|
||||
/**
|
||||
* 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.
|
||||
*/
|
||||
maxDiffPixelRatio?: number;
|
||||
|
||||
/**
|
||||
* An acceptable amount of pixels that could be different. Default is configurable with `TestConfig.expect`. Unset by
|
||||
* default.
|
||||
*/
|
||||
maxDiffPixels?: number;
|
||||
|
||||
/**
|
||||
* Snapshot name. If not passed, the test name and ordinals are used when called multiple times.
|
||||
*/
|
||||
name?: string|Array<string>;
|
||||
|
||||
/**
|
||||
* An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the
|
||||
* same pixel in compared images, between zero (strict) and one (lax), default is configurable with
|
||||
* `TestConfig.expect`. Defaults to `0.2`.
|
||||
*/
|
||||
threshold?: number;
|
||||
}): void;
|
||||
}
|
||||
|
||||
|
|
@ -6465,19 +6439,19 @@ interface TestProject {
|
|||
*/
|
||||
toHaveScreenshot?: {
|
||||
/**
|
||||
* an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and
|
||||
* 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`.
|
||||
*/
|
||||
threshold?: number;
|
||||
|
||||
/**
|
||||
* an acceptable amount of pixels that could be different, unset by default.
|
||||
* An acceptable amount of pixels that could be different, unset by default.
|
||||
*/
|
||||
maxDiffPixels?: number;
|
||||
|
||||
/**
|
||||
* an acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by
|
||||
* An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by
|
||||
* default.
|
||||
*/
|
||||
maxDiffPixelRatio?: number;
|
||||
|
|
@ -6503,25 +6477,25 @@ interface TestProject {
|
|||
|
||||
/**
|
||||
* Configuration for the
|
||||
* [snapshotAssertions.toMatchSnapshot(name[, options])](https://playwright.dev/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1)
|
||||
* [snapshotAssertions.toMatchSnapshot(name)](https://playwright.dev/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1)
|
||||
* method.
|
||||
*/
|
||||
toMatchSnapshot?: {
|
||||
/**
|
||||
* 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
|
||||
* **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`.
|
||||
*/
|
||||
threshold?: number;
|
||||
|
||||
/**
|
||||
* an acceptable amount of pixels that could be different, unset by default.
|
||||
* **Deprecated.** An acceptable amount of pixels that could be different, unset by default.
|
||||
*/
|
||||
maxDiffPixels?: number;
|
||||
|
||||
/**
|
||||
* an acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by
|
||||
* default.
|
||||
* **Deprecated.** An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1`
|
||||
* , unset by default.
|
||||
*/
|
||||
maxDiffPixelRatio?: number;
|
||||
};
|
||||
|
|
@ -6631,7 +6605,7 @@ interface TestProject {
|
|||
* This option configures a template controlling location of snapshots generated by
|
||||
* [pageAssertions.toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1)
|
||||
* and
|
||||
* [snapshotAssertions.toMatchSnapshot(name[, options])](https://playwright.dev/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1).
|
||||
* [snapshotAssertions.toMatchSnapshot(name)](https://playwright.dev/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1).
|
||||
*
|
||||
* **Usage**
|
||||
*
|
||||
|
|
|
|||
|
|
@ -96,8 +96,20 @@ test('should compile with different option combinations', async ({ runTSC }) =>
|
|||
import { test, expect } from '@playwright/test';
|
||||
test('is a test', async ({ page }) => {
|
||||
expect('foo').toMatchSnapshot();
|
||||
expect('foo').toMatchSnapshot('foo.txt');
|
||||
expect('foo').toMatchSnapshot(['dir', 'foo.txt']);
|
||||
expect('foo').toMatchSnapshot({ name: 'foo.txt' });
|
||||
|
||||
const buf: Buffer = 1 as any;
|
||||
expect(buf).toMatchSnapshot({ threshold: 0.2 });
|
||||
expect(buf).toMatchSnapshot({ maxDiffPixelRatio: 0.2 });
|
||||
expect(buf).toMatchSnapshot({ maxDiffPixels: 0.2 });
|
||||
|
||||
// @ts-expect-error
|
||||
expect('foo').toMatchSnapshot({ threshold: 0.2 });
|
||||
// @ts-expect-error
|
||||
expect('foo').toMatchSnapshot({ maxDiffPixelRatio: 0.2 });
|
||||
// @ts-expect-error
|
||||
expect('foo').toMatchSnapshot({ maxDiffPixels: 0.2 });
|
||||
});
|
||||
`
|
||||
|
|
|
|||
|
|
@ -578,6 +578,8 @@ class TypesGenerator {
|
|||
'GenericAssertions.objectContaining',
|
||||
'GenericAssertions.stringContaining',
|
||||
'GenericAssertions.stringMatching',
|
||||
'SnapshotAssertions.toMatchSnapshot#3',
|
||||
'SnapshotAssertions.toMatchSnapshot#4',
|
||||
]),
|
||||
overridesToDocsClassMapping: new Map([
|
||||
['TestType', 'Test'],
|
||||
|
|
|
|||
|
|
@ -329,6 +329,27 @@ type FunctionAssertions = {
|
|||
toPass(options?: { timeout?: number, intervals?: number[] }): Promise<void>;
|
||||
};
|
||||
|
||||
type BufferAssertions = {
|
||||
/**
|
||||
* Ensures that the passed [Buffer] matches the expected snapshot stored in the test snapshots directory.
|
||||
* @deprecated To avoid flakiness, use
|
||||
* [pageAssertions.toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1)
|
||||
* instead.
|
||||
* @param name Snapshot name.
|
||||
* @param options
|
||||
*/
|
||||
toMatchSnapshot(name: string | Array<string>, options?: { maxDiffPixelRatio?: number, maxDiffPixels?: number, threshold?: number }): void;
|
||||
|
||||
/**
|
||||
* Ensures that the passed [Buffer] matches the expected snapshot stored in the test snapshots directory.
|
||||
* @deprecated To avoid flakiness, use
|
||||
* [pageAssertions.toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1)
|
||||
* instead.
|
||||
* @param options
|
||||
*/
|
||||
toMatchSnapshot(options?: { maxDiffPixelRatio?: number, maxDiffPixels?: number, name?: string|Array<string>, threshold?: number }): void;
|
||||
};
|
||||
|
||||
type BaseMatchers<R, T> = GenericAssertions<R> & PlaywrightTest.Matchers<R, T> & SnapshotAssertions;
|
||||
type AllowedGenericMatchers<R> = Pick<GenericAssertions<R>, 'toBe' | 'toBeDefined' | 'toBeFalsy' | 'toBeNull' | 'toBeTruthy' | 'toBeUndefined'>;
|
||||
|
||||
|
|
@ -336,6 +357,7 @@ type SpecificMatchers<R, T> =
|
|||
T extends Page ? PageAssertions & AllowedGenericMatchers<R> :
|
||||
T extends Locator ? LocatorAssertions & AllowedGenericMatchers<R> :
|
||||
T extends APIResponse ? APIResponseAssertions & AllowedGenericMatchers<R> :
|
||||
T extends Buffer ? BufferAssertions & GenericAssertions<R> & PlaywrightTest.Matchers<R, T> :
|
||||
BaseMatchers<R, T> & (T extends Function ? FunctionAssertions : {});
|
||||
type AllMatchers<R, T> = PageAssertions & LocatorAssertions & APIResponseAssertions & FunctionAssertions & BaseMatchers<R, T>;
|
||||
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче