Playwright Config File
The Playwright Config File
The file playwright.config.js tells Playwright how to run your tests.
It sets where your tests are, how long they may take, which browsers to use and much more.
Playwright reads it every time you run npx playwright test.
The file is in the root of your project, next to package.json.
A Complete Config
This config uses the options you will need most:
Example
playwright.config.js
// @ts-check
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: './tests',
timeout: 30000,
expect: {
timeout: 5000,
},
fullyParallel: true,
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 1 : undefined,
reporter: 'html',
outputDir: 'test-results',
use: {
baseURL: 'https://www.w3schools.com/playwright/practice/',
headless: true,
viewport: { width: 1280, height: 720 },
locale: 'en-GB',
timezoneId: 'Europe/London',
trace: 'on-first-retry',
screenshot: 'only-on-failure',
video: 'retain-on-failure',
},
projects: [
{ name: 'chromium', use: { ...devices['Desktop Chrome'] } },
],
});
defineConfig() does not change anything.
It lets your editor check the option names and show help for them.
A CI (Continuous Integration) server is a machine that runs your tests automatically, for example every time you push code.
Most CI servers set the environment variable process.env.CI, so the config can use other values there.
For example, retries: process.env.CI ? 2 : 0 retries a failed test 2 times on CI, and 0 times on your computer.
Test Run Options
The top level options control the test run:
| Option | Description |
|---|---|
testDir | The folder with your test files |
timeout | The maximum time for one test, in milliseconds. Default: 30000 (30 seconds) |
expect.timeout | How long an assertion like toHaveText() keeps retrying. Default: 5000 |
fullyParallel | Runs the tests inside each file at the same time (in parallel), not only different files |
forbidOnly | Fails the run if a test.only was left in the code (see Skip and Only) |
retries | How many times to retry a failed test. Default: 0 |
workers | How many worker processes run tests at the same time. Each worker runs one test at a time. Default: half of your CPU cores |
reporter | How results are shown: 'list', 'html' and more |
outputDir | The folder for screenshots, videos and traces. Default: test-results |
You will learn more in the Parallel Tests, Retries and Reporters chapters.
The use Options
The options inside use set up the browser and the page for every test:
| Option | Description |
|---|---|
baseURL | The start of every relative URL, see below |
headless | true runs the browser without a window. Default: true |
viewport | The size of the page in pixels |
locale | The browser language, like 'en-GB' or 'de-DE' |
timezoneId | The time zone of the browser, like 'Europe/London' |
trace | When to record a trace, see Trace Viewer |
screenshot | When to take a screenshot, see Screenshots and Videos |
video | When to record a video |
This test prints some of the settings from inside the browser.
It is in tests/practice.spec.js, after the two tests shown in the baseURL section below.
It opens 'todo.html', a short URL that works because of baseURL:
Example
tests/practice.spec.js
test('browser settings from the config', async ({ page }) => {
await page.goto('todo.html');
console.log('URL:', page.url());
console.log('Viewport:', page.viewportSize());
console.log('Language:', await page.evaluate(() => navigator.language));
console.log('Time zone:', await page.evaluate(() => Intl.DateTimeFormat().resolvedOptions().timeZone));
});
Output:
[chromium] › tests/practice.spec.js:14:1 › browser settings from the config
URL: https://www.w3schools.com/playwright/practice/todo.html
Viewport: { width: 1280, height: 720 }
Language: en-GB
Time zone: Europe/London
Each value comes from the use options in the config above.
Note: A project can have its own use options.
When a project and the top level use set the same option, the project value is used.
For example, devices['Desktop Chrome'] sets its own viewport of 1280 x 720, and that viewport is used.
baseURL
Until now, every test in this tutorial used a full URL:
Before
await page.goto('https://www.w3schools.com/playwright/practice/todo.html');
With baseURL in the config, you write only the last part:
After
playwright.config.js
use: {
baseURL: 'https://www.w3schools.com/playwright/practice/',
},
After
tests/practice.spec.js
// @ts-check
import { test, expect } from '@playwright/test';
test('todo page opens', async ({ page }) => {
await page.goto('todo.html');
await expect(page).toHaveTitle(/Todo List/);
});
test('login page opens', async ({ page }) => {
await page.goto('login.html');
await expect(page.getByRole('heading', { name: 'Log in' })).toBeVisible();
});
The file also has the "browser settings from the config" test from the section above, so 3 tests run:
Output:
Running 3 tests using 3 workers
[1/3] [chromium] › tests/practice.spec.js:9:1 › login page opens
[2/3] [chromium] › tests/practice.spec.js:14:1 › browser settings from the config
[3/3] [chromium] › tests/practice.spec.js:4:1 › todo page opens
3 passed (3.2s)
Playwright joins baseURL and 'todo.html' into the full URL.
Now you can run the same tests against another server, like a test server, by changing one line.
From now on, the examples in this tutorial use baseURL.
Note: End baseURL with a slash, and do not start the path with one.
page.goto('/todo.html') would go to https://www.w3schools.com/todo.html, because a path that starts with / starts at the root of the site.
webServer
If you test your own web app, Playwright can start it before the tests run with the webServer option:
Example
playwright.config.js
export default defineConfig({
webServer: {
command: 'npm run start',
url: 'http://localhost:3000',
reuseExistingServer: !process.env.CI,
},
use: {
baseURL: 'http://localhost:3000/',
},
});
command: the command that starts your appurl: Playwright waits until this URL answers before it starts the testsreuseExistingServer: uses your app if it is already running, instead of starting a new one
Playwright stops the server when the tests are done.
The examples in this tutorial test the W3Schools practice pages, so they do not need webServer.
Options on the Command Line
Many config options can also be set for one run on the command line.
When an option is set in both places, the command line value is used:
Example
npx playwright test --workers=1 --retries=2 --timeout=60000 --headed
Use a different config file with --config:
Example
npx playwright test --config=playwright.ci.config.js