Skip to content

Commit beebf45

Browse files
omacrangerLogan Graham
omacranger
and
Logan Graham
authored
Add Sauce Visual Playwright docs (#2931)
* Add Sauce Visual Playwright docs --------- Co-authored-by: Logan Graham <[email protected]>
1 parent 8a51f84 commit beebf45

File tree

2 files changed

+177
-0
lines changed

2 files changed

+177
-0
lines changed

‎docs/visual-testing/integrations/playwright.md

+176
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
---
2+
sidebar_label: Playwright
3+
---
4+
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
7+
8+
# Playwright Integration
9+
10+
An extension for [Playwright](https://playwright.dev/) to integrate effortless visual testing with Sauce Visual.
11+
12+
## Usage
13+
14+
### Step 1 - Install the Visual Package
15+
16+
Install and add the Sauce Visual Playwright package to your project.
17+
18+
```sh
19+
npm i @saucelabs/visual-playwright
20+
```
21+
22+
### Step 2 - Create Your Setup and Teardown
23+
24+
The setup / teardown block will allow Sauce Visual to automatically create and finish builds and associate all snapshots with the current build during a run.
25+
26+
Create the following two files with their respective contents or append the visual config to your current global setup / teardowns:
27+
28+
<details>
29+
<summary>`global-setup.ts` File contents</summary>
30+
31+
```ts
32+
import { FullConfig } from '@playwright/test';
33+
import { sauceVisualSetup } from "@saucelabs/visual-playwright";
34+
35+
export default async function globalSetup(config: FullConfig) {
36+
// If you already have a setup, append this line somewhere in your setup block.
37+
await sauceVisualSetup();
38+
}
39+
```
40+
</details>
41+
42+
<details>
43+
<summary>`global-teardown.ts` File contents</summary>
44+
45+
```ts
46+
import { FullConfig } from '@playwright/test';
47+
import { sauceVisualTeardown } from "@saucelabs/visual-playwright";
48+
49+
export default async function globalTeardown(config: FullConfig) {
50+
// If you already have a teardown, append this line somewhere in your teardown block.
51+
await sauceVisualTeardown();
52+
}
53+
```
54+
</details>
55+
56+
57+
Edit your `playwright.config.ts` and append the following config options with the filenames that you created / referenced above if not already present:
58+
59+
```js
60+
import { defineConfig } from '@playwright/test';
61+
62+
export default defineConfig({
63+
// ... your other config options
64+
globalSetup: require.resolve('./global-setup'),
65+
globalTeardown: require.resolve('./global-teardown'),
66+
});
67+
```
68+
69+
### Step 3 - (Optional) Add a Sauce Visual Fixture
70+
71+
Though this step is optional it is _highly recommended_ for ease of use / developer experience. By creating a custom Playwright fixture you can enable quick and convenient access to the Sauce Visual service, as well as setting and configuring global defaults which can be overridden on a per-test basis. See the [Playwright Fixtures Docs Page](https://playwright.dev/docs/test-fixtures#creating-a-fixture) for more information and other examples of the benefits.
72+
73+
If you already have a custom fixture file, append the body of the example `base.extend` below to it; otherwise, create a `custom-test.ts` file with the included contents.
74+
75+
<details>
76+
<summary>`custom-test.ts` File contents</summary>
77+
78+
```js
79+
import { test as base } from "@playwright/test";
80+
import { sauceVisualFixtures, SauceVisualFixtures } from "@saucelabs/visual-playwright";
81+
82+
export const test = base.extend<SauceVisualFixtures>({
83+
// Set up the Sauce Visual fixture, and optionally customize the global options which are sent
84+
// with each sauce visual check to reduce duplication.
85+
...sauceVisualFixtures({
86+
// You can append some of the options available in the 'Check Options' section below. Ex:
87+
// captureDom: true,
88+
// delay: 200,
89+
}),
90+
});
91+
92+
export { expect } from "@playwright/test";
93+
```
94+
95+
[//]: # (</SauceVisualFixtures> fake closing block here as a comment for MDX format)
96+
</details>
97+
98+
After setup, you would replace usages of
99+
100+
```js
101+
import { test, expect } from '@playwright/test'
102+
```
103+
104+
with
105+
106+
```js
107+
import { test, expect } from './custom-test'
108+
```
109+
110+
### Step 4 - Use Sauce Visual in Your Tests
111+
112+
If you've set up a fixture during Step 3, use the 'Fixture' example, otherwise, you can still access Sauce Visual using our exported function with the 'Standard' example.
113+
114+
<Tabs>
115+
<TabItem value="fixture" label="Fixture" default>
116+
```ts
117+
import { test, expect } from '../custom-test';
118+
119+
// Add the `sauceVisual` fixture into each test you want to capture a snapshot in
120+
// -------------------------------- here ▼ --------------------------------------
121+
test('has title', async ({ page, sauceVisual }) => {
122+
await page.goto('https://playwright.dev/');
123+
await expect(page).toHaveTitle(/Playwright/);
124+
125+
// Call `visualCheck` using the fixture and optionally apply any additional
126+
// options as the second argument.
127+
await sauceVisual.visualCheck("Fixture Snapshot");
128+
});
129+
```
130+
</TabItem>
131+
<TabItem value="no-fixture" label="Standard" default>
132+
```ts
133+
import { expect, test } from '@playwright/test';
134+
// Import `sauceVisualCheck` from our visual plugin
135+
import { sauceVisualCheck } from '@saucelabs/visual-playwright';
136+
137+
// Expose the `testInfo` argument here ▼ -------
138+
test('has title', async ({ page }, testInfo) => {
139+
await page.goto('https://docs.saucelabs.com/visual-testing/integrations/playwright/');
140+
await expect(page).toHaveTitle(/Playwright/);
141+
142+
// Pass the current page object and test info into the `sauceVisualCheck` call, and optionally
143+
// customize the options via the fourth argument.
144+
await sauceVisualCheck(page, testInfo, 'Export Snapshot');
145+
});
146+
```
147+
</TabItem>
148+
</Tabs>
149+
150+
### Step 5 - Configure Your Sauce Labs Credentials
151+
152+
Sauce Visual relies on environment variables for authentication.<br />
153+
Both `SAUCE_USERNAME` and `SAUCE_ACCESS_KEY` need to be set prior starting your Playwright tests.
154+
155+
Username and Access Key can be retrieved from https://app.saucelabs.com/user-settings.
156+
157+
```sh
158+
export SAUCE_USERNAME=__YOUR_SAUCE_USER_NAME__
159+
export SAUCE_ACCESS_KEY=__YOUR_SAUCE_ACCESS_KEY__
160+
```
161+
162+
### Step 6 - Run Your Tests
163+
164+
Upon executing your tests for the first time under this step, a visual baseline is automatically created in our system. This baseline serves as the standard for all subsequent tests. As new tests are run, they are compared to this original baseline, with any deviations highlighted to signal visual changes. These comparisons are integral for detecting any unintended visual modifications early in your development cycle. All test builds, including the initial baseline and subsequent runs, can be monitored and managed through the Sauce Labs platform at [Sauce Visual Builds](https://app.saucelabs.com/visual/builds).
165+
166+
## Check Options
167+
168+
These options can be defined globally during fixture initialization (see [Step 3](#step-3---optional-add-a-sauce-visual-fixture)) or as an option when calling `sauceVisual.visualCheck` / `sauceVisualCheck`.
169+
170+
| Key | Type | Default | Description |
171+
|:----------------|:-------------------------|:-------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
172+
| `captureDom` | `boolean` | `true` | Toggles DOM snapshot capture. |
173+
| `clipSelector` | `string` | `undefined` | A CSS selector that we should clip the final screenshot to. |
174+
| `delay` | `number` | `0` (no delay) | A number, in ms, that we should delay before taking the snapshot. |
175+
| `ignoreRegions` | `(RegionIn \| string)[]` | `[]` (empty) | An array of manually created ignore regions, or CSS selectors in string form to ignore. |
176+
| `diffingMethod` | `DiffingMethod` | `DiffingMethod.Balanced` | The diffing method from the backend that we should use when performing visual differences. This can be customized by using the `DiffingMethod` enum exported from our `@saucelabs/visual` package. |

‎sidebars.js

+1
Original file line numberDiff line numberDiff line change
@@ -1721,6 +1721,7 @@ module.exports = {
17211721
'visual-testing/integrations/webdriverio',
17221722
'visual-testing/integrations/python',
17231723
'visual-testing/integrations/python-robot-framework',
1724+
'visual-testing/integrations/playwright',
17241725
],
17251726
},
17261727
'visual-testing/cli',

0 commit comments

Comments
 (0)