From 9ad507d9c06e2423d5147b91d9b574d1a4bd2e73 Mon Sep 17 00:00:00 2001 From: Pavel Feldman Date: Fri, 4 Jun 2021 13:33:56 -0700 Subject: [PATCH] doc(test): pass through test docs (#6914) --- docs/src/test-annotations.md | 2 +- docs/src/test-intro.md | 124 +++++++++++++++++++++++++++-------- docs/src/test-parallel.md | 8 ++- 3 files changed, 104 insertions(+), 30 deletions(-) diff --git a/docs/src/test-annotations.md b/docs/src/test-annotations.md index 9e6d252f7b750..f036c4f7c4ab3 100644 --- a/docs/src/test-annotations.md +++ b/docs/src/test-annotations.md @@ -3,7 +3,7 @@ id: test-annotations title: "Annotations" --- -Sadly, tests do not always pass. Playwright Test supports test annotations to deal with failures, flakiness and tests that are not yet ready. +Sadly, tests do not always pass. Luckily, Playwright Test supports test annotations to deal with failures, flakiness and tests that are not yet ready. ```js js-flavor=js // example.spec.js diff --git a/docs/src/test-intro.md b/docs/src/test-intro.md index 83a70a7d95d7b..b67ea800b73a5 100644 --- a/docs/src/test-intro.md +++ b/docs/src/test-intro.md @@ -232,11 +232,11 @@ test('my test', async ({ page }) => { expect(await page.getAttribute('text=Get Started', 'href')).toBe('/docs/intro'); // Expect an element "to be visible". - expect(await page.isVisible('[aria-label="GitHub repository"]')).toBe(true); + expect(await page.isVisible('text=Learn more')).toBeTruthy(); await page.click('text=Get Started'); // Expect some text to be visible on the page. - expect(await page.waitForSelector('text=Getting Started')).toBeTruthy(); + expect(await page.waitForSelector('text=System requirements')).toBeTruthy(); // Compare screenshot with a stored reference. expect(await page.screenshot()).toMatchSnapshot('get-started.png'); @@ -257,17 +257,39 @@ test('my test', async ({ page }) => { expect(await page.getAttribute('text=Get Started', 'href')).toBe('/docs/intro'); // Expect an element "to be visible". - expect(await page.isVisible('[aria-label="GitHub repository"]')).toBe(true); + expect(await page.isVisible('[aria-label="GitHub repository"]')).toBeTruthy(); await page.click('text=Get Started'); // Expect some text to be visible on the page. - expect(await page.waitForSelector('text=Getting Started')).toBeTruthy(); + expect(await page.waitForSelector('text=System requirements')).toBeTruthy(); // Compare screenshot with a stored reference. expect(await page.screenshot()).toMatchSnapshot('get-started.png'); }); ``` +Notice how running this test is saying: + +``` +Error: example.spec.ts-snapshots/get-started-chromium-darwin.png is missing in snapshots, writing actual. +``` + +That's because there was no golden file for your `get-started.png` snapshot. It is now created and is ready to be added to the repository. The name of the folder with the golden expectations starts with the name of your test file: + +```bash +drwxr-xr-x 5 user group 160 Jun 4 11:46 . +drwxr-xr-x 6 user group 192 Jun 4 11:45 .. +-rw-r--r-- 1 user group 231 Jun 4 11:16 example.spec.ts +drwxr-xr-x 3 user group 96 Jun 4 11:46 example.spec.ts-snapshots +``` + +To update your golden files, you can use the `--update-snapshots` parameter. + +```bash +npx playwright test -c tests --update-snapshots +``` + + ## Learn the command line Here are the most common options available in the [command line](./test-cli.md). @@ -335,37 +357,87 @@ Here are the most common options available in the [command line](./test-cli.md). So far, we've looked at the zero-config operation of Playwright Test. For a real world application, it is likely that you would want to use a config. -Create `playwright.config.js` (or `playwright.config.ts`) to configure your tests. You can specify browser launch options, run tests in multiple browsers and much more with the config. Here is an example configuration that runs every test in Chromium, Firefox and WebKit. Look for more options in the [configuration section](./test-configuration.md). +Create `playwright.config.ts` (or `playwright.config.js`) to configure your tests. You can specify browser launch options, run tests in multiple browsers and much more with the config. Here is an example configuration that runs every test in Chromium, Firefox and WebKit, both Desktop and Mobile versions. Look for more options in the [configuration section](./test-configuration.md). ```js js-flavor=js -module.exports = { - // Each test is given 30 seconds. - timeout: 30000, +// playwright.config.js +const { devices } = require('@playwright/test'); - use: { - // Run browsers in the headless mode. - headless: true, - - // Specify the viewport size. - viewport: { width: 1280, height: 720 }, - }, +module.exports = { + projects: [ + { + name: 'Desktop Chromium', + use: { + browserName: 'chromium', + // Test against Chrome Beta channel. + channel: 'chrome-beta', + }, + }, + { + name: 'Desktop Safari', + use: { + browserName: 'webkit', + viewport: { width: 1200, height: 750 }, + } + }, + // Test against mobile viewports. + { + name: 'Mobile Chrome', + use: devices['Pixel 5'], + }, + { + name: 'Mobile Safari', + use: devices['iPhone 12'], + }, + { + name: 'Desktop Firefox', + use: { + browserName: 'firefox', + viewport: { width: 800, height: 600 }, + } + }, + ], }; ``` ```js js-flavor=ts -import { PlaywrightTestConfig } from '@playwright/test'; +// playwright.config.ts +import { PlaywrightTestConfig, devices } from '@playwright/test'; const config: PlaywrightTestConfig = { - // Each test is given 30 seconds. - timeout: 30000, - - use: { - // Run browsers in the headless mode. - headless: true, - - // Specify the viewport size. - viewport: { width: 1280, height: 720 }, - }, + projects: [ + { + name: 'Desktop Chromium', + use: { + browserName: 'chromium', + // Test against Chrome Beta channel. + channel: 'chrome-beta', + }, + }, + { + name: 'Desktop Safari', + use: { + browserName: 'webkit', + viewport: { width: 1200, height: 750 }, + } + }, + // Test against mobile viewports. + { + name: 'Mobile Chrome', + use: devices['Pixel 5'], + }, + { + name: 'Mobile Safari', + use: devices['iPhone 12'], + }, + { + name: 'Desktop Firefox', + use: { + browserName: 'firefox', + viewport: { width: 800, height: 600 }, + } + }, + ], }; export default config; ``` diff --git a/docs/src/test-parallel.md b/docs/src/test-parallel.md index 67453b69e6a9c..4ebebfe742e46 100644 --- a/docs/src/test-parallel.md +++ b/docs/src/test-parallel.md @@ -11,9 +11,9 @@ Playwright Test runs tests in parallel by default, using multiple worker process Each worker process creates a new environment to run tests. By default, Playwright Test reuses the worker as much as it can to make testing faster. -However, test runner will create a new worker when retrying tests, after any test failure, to initialize a new environment, or just to speed up test execution if the worker limit is not reached. +Should any test fail, Playwright will discard entire worker process along with the browsers used and will start a new one. That way failing tests can't affect healthy ones. -You can control the maximum number of worker processes via [command line](./test-cli.md) or in the [configuration file](./test-configuration.md). +You can control the maximum number of parallel worker processes via [command line](./test-cli.md) or in the [configuration file](./test-configuration.md). - Run in parallel by default ```bash @@ -50,7 +50,7 @@ You can control the maximum number of worker processes via [command line](./test export default config; ``` -Each worker process is assigned a unique sequential index that is accessible through the [`workerInfo`](./test-advanced.md#workerinfo) object. +Each worker process is assigned a unique sequential index that is accessible through the [`workerInfo`](./test-advanced.md#workerinfo) object. Since each worker is a process, there also is a process-wide environment variable `process.env.TEST_WORKER_INDEX` that has the same value. ## Shards @@ -61,3 +61,5 @@ npx playwright test --shard=1/3 npx playwright test --shard=2/3 npx playwright test --shard=3/3 ``` + +That way your test suite completes 3 times faster.