Prompt
How do I run my Playwright tests in parallel in CI?
Latest observation
To run Playwright tests in parallel in CI, you usually want two layers of parallelism:
- Within a single CI job: Playwright runs tests in parallel across workers.
- Across multiple CI jobs/machines: split the test suite into shards.
1) Enable parallel workers
Playwright runs tests in parallel by default, but you can control it in playwright.config.ts:
import { defineConfig } from '@playwright/test';
export default defineConfig({
workers: process.env.CI ? 4 : undefined,
});
Common pattern:
- Use a fixed number of workers in CI, like
2,4, or50% - Avoid too many workers if your CI machine is small
2) Use sharding in CI
For bigger suites, shard tests across multiple CI runners:
npx playwright test --shard=1/4
npx playwright test --shard=2/4
npx playwright test --shard=3/4
npx playwright test --shard=4/4
Each job gets a portion of the suite, which is often the best way to speed up CI.
Example: GitHub Actions
Here’s a common setup using a matrix to shard tests:
name: Playwright Tests
on:
push:
pull_request:
jobs:
test:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
shard: [1, 2, 3, 4]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- run: npx playwright install --with-deps
- run: npx playwright test --shard=${{ matrix.shard }}/4
3) Make sure tests are isolated
Parallel execution only works reliably if tests don’t share mutable state.
Best practices:
- Don’t reuse the same user/session across tests unless intentionally isolated
- Avoid writing to the same file or DB record from multiple tests
- Use
beforeEachto create fresh state - Use unique test data per test
If tests conflict, you’ll get flaky failures that look like “parallel issues” but are really state-sharing issues.
4) Control test parallelism inside files
If needed, you can mark a file or suite to run serially:
import { test } from '@playwright/test';
test.describe.configure({ mode: 'serial' });
Or disable parallelism for a specific suite if it’s not safe.
5) Recommended CI approach
A good default is:
- Small suite: set
workersto 2–4 in CI - Medium/large suite: use sharding plus a moderate worker count
- Flaky/shared-state tests: isolate or run serially
If you want, I can show you the exact setup for GitHub Actions, GitLab CI, CircleCI, or Azure DevOps.