Playwright Parallel Tests
Playwright Parallel Tests
Playwright runs tests in parallel: several tests at the same time, so the whole run is faster.
This chapter shows how to control how many tests run at once, and how to make some tests run in order.
Retrying failed tests is covered in the next chapter, Retries.
Workers
Playwright runs tests in workers.
A worker is a separate process (a running program) with its own browser.
Each worker runs one test at a time, so four workers run four tests at the same time.
The first line of the output tells you how many workers were used:
Output:
Running 4 tests using 4 workers
By default Playwright uses half of your CPU cores, but never more workers than there are tests.
Set the number in the config, or on the command line:
Example
playwright.config.js
export default defineConfig({
workers: process.env.CI ? 1 : undefined,
});
This config uses 1 worker on a CI server, and the default number on your computer.
Example
npx playwright test --workers=1
--workers=1 runs one test at a time.
It is slower, but useful when tests change the same data.
Tests in different workers never share a browser, so they cannot see each other's pages, cookies or local storage.
fullyParallel
Without fullyParallel, Playwright runs different files in parallel, but the tests inside one file run one after the other, in the same worker.
With fullyParallel: true, every test can run in its own worker:
Example
playwright.config.js
export default defineConfig({
fullyParallel: true,
});
The examples in this tutorial use fullyParallel: true, which is why two tests in one file finish in a different order each time.
You can also set the mode for one file with test.describe.configure().
Put it at the top of the file, or inside a test.describe() group to set it for that group only:
Example
test.describe.configure({ mode: 'parallel' });
Serial Mode
Sometimes tests must run in order, because each one continues where the last one stopped.
Use mode: 'serial' for that.
These three tests share one page and work on the same todo:
Example
tests/todo-steps.spec.js
// @ts-check
import { test, expect } from '@playwright/test';
test.describe.configure({ mode: 'serial' });
/** @type {import('@playwright/test').Page} */
let page;
test.beforeAll(async ({ browser }) => {
page = await browser.newPage();
await page.goto('todo.html');
});
test.afterAll(async () => {
await page.close();
});
test('add a todo', async () => {
await page.getByPlaceholder('What needs to be done?').fill('Learn Playwright');
await page.getByRole('button', { name: 'Add' }).click();
await expect(page.getByTestId('todo-count')).toHaveText('1 item left');
});
test('complete the todo', async () => {
await page.getByRole('checkbox', { name: 'Complete Learn Playwright' }).check();
await expect(page.getByTestId('todo-count')).toHaveText('0 items left');
});
test('delete the todo', async () => {
await page.getByRole('button', { name: 'Delete Learn Playwright' }).click();
await expect(page.getByRole('listitem')).toHaveCount(0);
});
Example Explained
test.describe.configure({ mode: 'serial' })makes the tests in this file run in order, one after the othertest.beforeAll()runs once, before the first test. It opens one page that all three tests share (see Hooks)browseris a fixture that gives you the browser, so you can open a new pagetest.afterAll()closes the page after the last test- The
@typecomment tells your editor thatpageis a Playwright Page
The output:
Output:
Running 3 tests using 1 worker
[1/3] [chromium] › tests/todo-steps.spec.js:18:1 › add a todo
[2/3] [chromium] › tests/todo-steps.spec.js:24:1 › complete the todo
[3/3] [chromium] › tests/todo-steps.spec.js:29:1 › delete the todo
3 passed (1.5s)
The three tests ran in one worker, in the order they are written, even though the config says fullyParallel: true.
If one serial test fails, the tests after it are not run.
Here, the second test expects the wrong text, "0 items done":
Output:
Running 3 tests using 1 worker
[1/3] [chromium] › tests/todo-steps.spec.js:18:1 › add a todo
[2/3] [chromium] › tests/todo-steps.spec.js:24:1 › complete the todo
1) [chromium] › tests/todo-steps.spec.js:24:1 › complete the todo ────────────────────────────────
Error: expect(locator).toHaveText(expected) failed
Locator: getByTestId('todo-count')
Expected: "0 items done"
Received: "0 items left"
Timeout: 5000ms
[3/3] [chromium] › tests/todo-steps.spec.js:29:1 › delete the todo
1 failed
[chromium] › tests/todo-steps.spec.js:24:1 › complete the todo ─────────────────────────────────
1 did not run
1 passed (7.7s)
The output still lists the third test, but the summary says 1 did not run.
Note: Use serial mode only when you must.
Independent tests are easier to read, to debug and to run in parallel.
Sharding
Sharding splits the tests into parts, so several machines can run them at the same time.
Each part is called a shard.
Each machine runs one shard with --shard=current/total.
These commands use the test file and config from the Browsers and Projects chapter: two tests, run in the chromium and webkit projects.
The first machine runs shard 1 of 2:
Example
npx playwright test --project=chromium --project=webkit --shard=1/2
Output:
Running 2 tests using 2 workers, shard 1 of 2
[1/2] [chromium] › tests/todo.spec.js:9:1 › can add a todo
[2/2] [chromium] › tests/todo.spec.js:4:1 › has title
2 passed (2.5s)
The second machine runs shard 2 of 2:
Example
npx playwright test --project=chromium --project=webkit --shard=2/2
Output:
Running 2 tests using 2 workers, shard 2 of 2
[1/2] [webkit] › tests/todo.spec.js:9:1 › can add a todo
[2/2] [webkit] › tests/todo.spec.js:4:1 › has title
2 passed (1.6s)
That makes four tests, so each shard ran two.
Sharding is used on CI servers with many machines.
To get one report for all shards, use the blob reporter on each machine and merge the results, see File Reporters.