docs(intro): rework js intro (#10157)
- Educate on the config file right away. - Switch from `--browser` to `--project`. - Update configuration sections.
This commit is contained in:
Dmitry Gozman
GitHub
parent
626c0f8f51
commit
5c9dcffd67
|
|
@ -34,7 +34,7 @@ You can optionally install only selected browsers, see [installing browsers](./b
|
|||
|
||||
## First test
|
||||
|
||||
Create `tests/foo.spec.js` (or `tests/foo.spec.ts` for TypeScript) to define your test.
|
||||
Create `tests/example.spec.js` (or `tests/example.spec.ts` for TypeScript) to define your test.
|
||||
|
||||
```js js-flavor=js
|
||||
const { test, expect } = require('@playwright/test');
|
||||
|
|
@ -68,20 +68,91 @@ Playwright Test just ran a test using Chromium browser, in a headless manner. Le
|
|||
npx playwright test --headed
|
||||
```
|
||||
|
||||
What about other browsers? Let's run the same test using Firefox:
|
||||
## Configuration file
|
||||
|
||||
```bash
|
||||
npx playwright test --browser=firefox
|
||||
To enjoy all the features that Playwright Test has to offer, you would want to create a configuration file `playwright.config.ts` (or `playwright.config.js`). It allows you to run tests in multiple browsers configured as you'd like.
|
||||
|
||||
Here is an example configuration that runs every test in Chromium, Firefox and WebKit, by creating a "project" for each browser configuration. It also specifies [two retries](./test-retries.md) and [tracing](./trace-viewer.md) options.
|
||||
|
||||
```js js-flavor=js
|
||||
// playwright.config.js
|
||||
// @ts-check
|
||||
|
||||
/** @type {import('@playwright/test').PlaywrightTestConfig} */
|
||||
const config = {
|
||||
retries: 2,
|
||||
use: {
|
||||
trace: 'on-first-retry',
|
||||
},
|
||||
projects: [
|
||||
{
|
||||
name: 'chromium',
|
||||
use: { browserName: 'chromium' },
|
||||
},
|
||||
{
|
||||
name: 'firefox',
|
||||
use: { browserName: 'firefox' },
|
||||
},
|
||||
{
|
||||
name: 'webkit',
|
||||
use: { browserName: 'webkit' },
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
module.exports = config;
|
||||
```
|
||||
|
||||
And finally, on all three browsers:
|
||||
```js js-flavor=ts
|
||||
// playwright.config.ts
|
||||
import { PlaywrightTestConfig } from '@playwright/test';
|
||||
|
||||
```bash
|
||||
npx playwright test --browser=all
|
||||
const config: PlaywrightTestConfig = {
|
||||
retries: 2,
|
||||
use: {
|
||||
trace: 'on-first-retry',
|
||||
},
|
||||
projects: [
|
||||
{
|
||||
name: 'chromium',
|
||||
use: { browserName: 'chromium' },
|
||||
},
|
||||
{
|
||||
name: 'firefox',
|
||||
use: { browserName: 'firefox' },
|
||||
},
|
||||
{
|
||||
name: 'webkit',
|
||||
use: { browserName: 'webkit' },
|
||||
},
|
||||
],
|
||||
};
|
||||
export default config;
|
||||
```
|
||||
|
||||
Refer to [configuration](./test-configuration.md) section for configuring test runs in different modes with different browsers.
|
||||
Look for more options in the [configuration section](./test-configuration.md).
|
||||
|
||||
Now you can run tests in multiple browsers by default.
|
||||
|
||||
```bash
|
||||
npx playwright test
|
||||
|
||||
Running 5 tests using 5 workers
|
||||
|
||||
✓ [chromium] › example.spec.ts:3:1 › basic test (2s)
|
||||
✓ [firefox] › example.spec.ts:3:1 › basic test (2s)
|
||||
✓ [webkit] › example.spec.ts:3:1 › basic test (2s)
|
||||
```
|
||||
|
||||
Use `--project` command line option to run a single project.
|
||||
|
||||
```bash
|
||||
npx playwright test --project=firefox
|
||||
|
||||
Running 1 test using 1 worker
|
||||
|
||||
✓ [firefox] › example.spec.ts:3:1 › basic test (2s)
|
||||
```
|
||||
|
||||
## Writing assertions
|
||||
|
||||
|
|
@ -110,10 +181,7 @@ test('my test', async ({ page }) => {
|
|||
|
||||
await page.click('text=Get Started');
|
||||
// Expect some text to be visible on the page.
|
||||
await expect(page.locator('text=System requirements').first()).toBeVisible();
|
||||
|
||||
// Compare screenshot with a stored reference.
|
||||
expect(await page.screenshot()).toMatchSnapshot('get-started.png');
|
||||
await expect(page.locator('text=Introduction').first()).toBeVisible();
|
||||
});
|
||||
```
|
||||
|
||||
|
|
@ -135,35 +203,10 @@ test('my test', async ({ page }) => {
|
|||
|
||||
await page.click('text=Get Started');
|
||||
// Expect some text to be visible on the page.
|
||||
await expect(page.locator('text=System requirements').first()).toBeVisible();
|
||||
|
||||
// Compare screenshot with a stored reference.
|
||||
expect(await page.screenshot()).toMatchSnapshot('get-started.png');
|
||||
await expect(page.locator('text=Introduction').first()).toBeVisible();
|
||||
});
|
||||
```
|
||||
|
||||
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 --update-snapshots
|
||||
```
|
||||
|
||||
|
||||
## Using test fixtures
|
||||
|
||||
You noticed an argument `{ page }` that the test above has access to:
|
||||
|
|
@ -201,12 +244,12 @@ const { test, expect } = require('@playwright/test');
|
|||
test.describe('feature foo', () => {
|
||||
test.beforeEach(async ({ page }) => {
|
||||
// Go to the starting url before each test.
|
||||
await page.goto('https://my.start.url/');
|
||||
await page.goto('https://playwright.dev/');
|
||||
});
|
||||
|
||||
test('my test', async ({ page }) => {
|
||||
// Assertions use the expect API.
|
||||
await expect(page).toHaveURL('https://my.start.url/');
|
||||
await expect(page).toHaveURL('https://playwright.dev/');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
|
@ -218,12 +261,12 @@ import { test, expect } from '@playwright/test';
|
|||
test.describe('feature foo', () => {
|
||||
test.beforeEach(async ({ page }) => {
|
||||
// Go to the starting url before each test.
|
||||
await page.goto('https://my.start.url/');
|
||||
await page.goto('https://playwright.dev/');
|
||||
});
|
||||
|
||||
test('my test', async ({ page }) => {
|
||||
// Assertions use the expect API.
|
||||
await expect(page).toHaveURL('https://my.start.url/');
|
||||
await expect(page).toHaveURL('https://playwright.dev/');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
|
@ -263,14 +306,9 @@ Following are the usual command line patterns. Learn more about the [command lin
|
|||
npx playwright test --headed
|
||||
```
|
||||
|
||||
- Run tests in a particular browser (config-less mode)
|
||||
- Run tests in a particular configuration (project)
|
||||
```bash
|
||||
npx playwright test --browser=webkit
|
||||
```
|
||||
|
||||
- Run tests in all browsers (config-less mode)
|
||||
```bash
|
||||
npx playwright test --browser=all
|
||||
npx playwright test --project=firefox
|
||||
```
|
||||
|
||||
- Disable [parallelization](./test-parallel.md)
|
||||
|
|
@ -293,100 +331,9 @@ Following are the usual command line patterns. Learn more about the [command lin
|
|||
npx playwright test --help
|
||||
```
|
||||
|
||||
## Creating a configuration file
|
||||
## Configure NPM scripts
|
||||
|
||||
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.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
|
||||
// playwright.config.js
|
||||
// @ts-check
|
||||
const { devices } = require('@playwright/test');
|
||||
|
||||
/** @type {import('@playwright/test').PlaywrightTestConfig} */
|
||||
const config = {
|
||||
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 },
|
||||
}
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
module.exports = config;
|
||||
```
|
||||
|
||||
```js js-flavor=ts
|
||||
// playwright.config.ts
|
||||
import { PlaywrightTestConfig, devices } from '@playwright/test';
|
||||
|
||||
const config: PlaywrightTestConfig = {
|
||||
projects: [
|
||||
{
|
||||
name: 'Chrome Stable',
|
||||
use: {
|
||||
browserName: 'chromium',
|
||||
// Test against Chrome Stable channel.
|
||||
channel: 'chrome',
|
||||
},
|
||||
},
|
||||
{
|
||||
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;
|
||||
```
|
||||
|
||||
Configure NPM script to run tests. Playwright Test will automatically pick up `playwright.config.js` or `playwright.config.ts`.
|
||||
Playwright Test will automatically pick up `playwright.config.js` or `playwright.config.ts`.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -405,3 +352,7 @@ If you put your configuration file in a different place, pass it with `--config`
|
|||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
To pass options through npm script, use double dashes: ```npm run test -- --headed```.
|
||||
:::
|
||||
|
|
|
|||
|
|
@ -489,7 +489,7 @@ const config: PlaywrightTestConfig<TestOptions> = {
|
|||
export default config;
|
||||
```
|
||||
|
||||
Each project can be configured separately, and run different set of tests with different parameters. See [test suite options](#test-suite-options) for the list of options available to each project.
|
||||
Each project can be configured separately, and run different set of tests with different parameters. See [project options][TestProject] for the list of options available to each project.
|
||||
|
||||
You can run all projects or just a single one:
|
||||
```bash
|
||||
|
|
@ -500,6 +500,12 @@ npx playwright test
|
|||
npx playwright test --project=v2
|
||||
```
|
||||
|
||||
There are many more things you can do with projects:
|
||||
- Run a subset of test by specifying different `testDir` for each project.
|
||||
- Run tests in multiple configurations, for example with desktop Chromium and emulating Chrome for Android.
|
||||
- Run "core" tests without retries to ensure stability of the core functionality, and use `retries` for other tests.
|
||||
- And much more! See [project options][TestProject] for the list of options available to each project.
|
||||
|
||||
## Add custom matchers using expect.extend
|
||||
|
||||
Playwright Test uses [`expect` library](https://jestjs.io/docs/expect) under the hood which has the functionality to extend it with [custom matchers](https://jestjs.io/docs/expect#expectextendmatchers).
|
||||
|
|
|
|||
|
|
@ -156,6 +156,82 @@ const config: PlaywrightTestConfig = {
|
|||
export default config;
|
||||
```
|
||||
|
||||
## Multiple browsers
|
||||
|
||||
Playwright Test supports multiple "projects" that can run your tests in multiple browsers and configurations. Here is an example that runs every test in Chromium, Firefox and WebKit, by creating a project for each.
|
||||
|
||||
```js js-flavor=js
|
||||
// playwright.config.js
|
||||
// @ts-check
|
||||
|
||||
/** @type {import('@playwright/test').PlaywrightTestConfig} */
|
||||
const config = {
|
||||
projects: [
|
||||
{
|
||||
name: 'chromium',
|
||||
use: { browserName: 'chromium' },
|
||||
},
|
||||
{
|
||||
name: 'firefox',
|
||||
use: { browserName: 'firefox' }
|
||||
},
|
||||
{
|
||||
name: 'webkit',
|
||||
use: { browserName: 'webkit' }
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
module.exports = config;
|
||||
```
|
||||
|
||||
```js js-flavor=ts
|
||||
// playwright.config.ts
|
||||
import { PlaywrightTestConfig } from '@playwright/test';
|
||||
|
||||
const config: PlaywrightTestConfig = {
|
||||
projects: [
|
||||
{
|
||||
name: 'chromium',
|
||||
use: { browserName: 'chromium' },
|
||||
},
|
||||
{
|
||||
name: 'firefox',
|
||||
use: { browserName: 'firefox' },
|
||||
},
|
||||
{
|
||||
name: 'webkit',
|
||||
use: { browserName: 'webkit' },
|
||||
},
|
||||
],
|
||||
};
|
||||
export default config;
|
||||
```
|
||||
|
||||
You can specify [different options][TestProject] for each project, for example set specific command-line arguments for Chromium.
|
||||
|
||||
Playwright Test will run all projects by default.
|
||||
|
||||
```bash
|
||||
npx playwright test
|
||||
|
||||
Running 5 tests using 5 workers
|
||||
|
||||
✓ [chromium] › example.spec.ts:3:1 › basic test (2s)
|
||||
✓ [firefox] › example.spec.ts:3:1 › basic test (2s)
|
||||
✓ [webkit] › example.spec.ts:3:1 › basic test (2s)
|
||||
```
|
||||
|
||||
Use `--project` command line option to run a single project.
|
||||
|
||||
```bash
|
||||
npx playwright test --project=firefox
|
||||
|
||||
Running 1 test using 1 worker
|
||||
|
||||
✓ [firefox] › example.spec.ts:3:1 › basic test (2s)
|
||||
```
|
||||
|
||||
## Emulation
|
||||
|
||||
Playwright can [emulate different environments](./emulation.md) like mobile device, locale or timezone.
|
||||
|
|
@ -540,113 +616,3 @@ const config: PlaywrightTestConfig = {
|
|||
};
|
||||
export default config;
|
||||
```
|
||||
|
||||
## Different options for each browser
|
||||
|
||||
To specify different options per browser, for example command line arguments for Chromium, create multiple projects in your configuration file. Below is an example that runs all tests in three browsers, with different options.
|
||||
|
||||
```js js-flavor=js
|
||||
// playwright.config.js
|
||||
// @ts-check
|
||||
|
||||
/** @type {import('@playwright/test').PlaywrightTestConfig} */
|
||||
const config = {
|
||||
// Put any shared options on the top level.
|
||||
use: {
|
||||
headless: true,
|
||||
},
|
||||
|
||||
projects: [
|
||||
{
|
||||
name: 'Chromium',
|
||||
use: {
|
||||
// Configure the browser to use.
|
||||
browserName: 'chromium',
|
||||
|
||||
// Any Chromium-specific options.
|
||||
viewport: { width: 600, height: 800 },
|
||||
},
|
||||
},
|
||||
|
||||
{
|
||||
name: 'Firefox',
|
||||
use: { browserName: 'firefox' },
|
||||
},
|
||||
|
||||
{
|
||||
name: 'WebKit',
|
||||
use: { browserName: 'webkit' },
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
module.exports = config;
|
||||
```
|
||||
|
||||
```js js-flavor=ts
|
||||
// playwright.config.ts
|
||||
import { PlaywrightTestConfig } from '@playwright/test';
|
||||
|
||||
const config: PlaywrightTestConfig = {
|
||||
// Put any shared options on the top level.
|
||||
use: {
|
||||
headless: true,
|
||||
},
|
||||
|
||||
projects: [
|
||||
{
|
||||
name: 'Chromium',
|
||||
use: {
|
||||
// Configure the browser to use.
|
||||
browserName: 'chromium',
|
||||
|
||||
// Any Chromium-specific options.
|
||||
viewport: { width: 600, height: 800 },
|
||||
},
|
||||
},
|
||||
|
||||
{
|
||||
name: 'Firefox',
|
||||
use: { browserName: 'firefox' },
|
||||
},
|
||||
|
||||
{
|
||||
name: 'WebKit',
|
||||
use: { browserName: 'webkit' },
|
||||
},
|
||||
],
|
||||
};
|
||||
export default config;
|
||||
```
|
||||
|
||||
Playwright Test will run all projects by default.
|
||||
|
||||
```bash
|
||||
$ npx playwright test
|
||||
|
||||
Running 3 tests using 3 workers
|
||||
|
||||
✓ example.spec.ts:3:1 › [Chromium] should work (2s)
|
||||
✓ example.spec.ts:3:1 › [Firefox] should work (2s)
|
||||
✓ example.spec.ts:3:1 › [WebKit] should work (2s)
|
||||
```
|
||||
|
||||
Use `--project` command line option to run a single project.
|
||||
|
||||
```bash
|
||||
$ npx playwright test --project=webkit
|
||||
|
||||
Running 1 test using 1 worker
|
||||
|
||||
✓ example.spec.ts:3:1 › [WebKit] should work (2s)
|
||||
```
|
||||
|
||||
There are many more things you can do with projects:
|
||||
- Run a subset of test by specifying different `testDir` for each project.
|
||||
- Run tests in multiple configurations, for example with desktop Chromium and emulating Chrome for Android.
|
||||
- Run "core" tests without retries to ensure stability of the core functionality, and use `retries` for other tests.
|
||||
- And much more! See [advanced configuration](./test-advanced.md) for more details.
|
||||
|
||||
:::note
|
||||
`--browser` command line option is not compatible with projects. Specify `browserName` in each project instead.
|
||||
:::
|
||||
|
|
|
|||
Loading…
Reference in a new issue