This article was originally published on the Endform blog*.*
By the end of this you'll have a Playwright pipeline that gives useful feedback on every PR and stays under five minutes on a single runner, no sharding required. You need a Playwright suite, a GitHub repo, and the default Actions workflow that npm init playwright@latest generated. Two changes carry most of the weight: caching the browser binaries and fixing parallelism. Both are config edits you can land in an afternoon.
Here's the complete setup first, then the reasoning behind each piece.
Two files. Worker count, fullyParallel, and the reporters go in playwright.config.ts. Caching, the Chromium-on-PR split, and the artifact upload go in the workflow YAML.
playwright.config.ts:
typescript
import { defineConfig, devices } from "@playwright/test";
export default defineConfig({
testDir: "./tests",
fullyParallel: true, // parallelize tests within a file, not just across files
forbidOnly: !!process.env.CI, // fail the build if a stray test.only is committed
retries: process.env.CI ? 2 : 0, // retry flaky tests in CI only
workers: process.env.CI ? "50%" : undefined, // scale workers to the runner; measure and raise from here
reporter: [
["html"], // full report, uploaded as an artifact
["github"], // inline annotations on the run summary
],
use: {
trace: "on-first-retry", // capture a trace when a test retries
},
projects: [
{ name: "chromium", use: { ...devices["Desktop Chrome"] } },
{ name: "firefox", use: { ...devices["Desktop Firefox"] } },
{ name: "webkit", use: { ...devices["Desktop Safari"] } },
],
});
.github/workflows/playwright.yml:
yaml
name: Playwright Tests
on:
pull_request:
branches: [main]
push:
branches: [main]
jobs:
test:
timeout-minutes: 60
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: lts/*
cache: "npm" # caches ~/.npm, the safe npm cache, not node_modules
- name: Install dependencies
run: npm ci
- name: Cache Playwright browsers
id: playwright-cache
uses: actions/cache@v6
with:
path: ~/.cache/ms-playwright
key: ${{ runner.os }}-playwright-${{ hashFiles('package-lock.json') }}
- name: Install browsers and system dependencies
if: steps.playwright-cache.outputs.cache-hit != 'true'
run: npx playwright install --with-deps
- name: Install OS dependencies for browsers
if: steps.playwright-cache.outputs.cache-hit == 'true'
run: npx playwright install-deps
- name: Run Playwright tests
run: |
if [ "${{ github.event_name }}" = "pull_request" ]; then
npx playwright test --project=chromium
else
npx playwright test
fi
- name: Upload Playwright report
uses: actions/upload-artifact@v7
if: ${{ !cancelled() }}
with:
name: playwright-report
path: playwright-report/
retention-days: 14
Drop both in, push, and the first run populates the cache while every run after it skips the download. The rest of this post explains why each block earns its place.
The default workflow from npm init playwright@latest works, it just spends most of its time on setup and a serial test run. On a public repo with about 40 lightweight tests, the baseline came in at 3m 18s. Treat that as a fixed number for comparing fixes, not a prediction of your own run times.
Only two steps mattered. Install Playwright Browsers took 42 seconds because it downloads Chromium, Firefox, and WebKit plus their system libraries on every single run, whether or not those browsers changed. Run Playwright tests took 2m 25s, and that number is about parallelism. The generated config pins CI to one worker:
typescript
workers: process.env.CI ? 1 : undefined,
So the suite runs close to one test at a time even with idle cores. Checkout, Node setup, and npm ci came in at a second or two each and aren't worth touching.
Two independent bottlenecks: repeated download overhead, and serial execution. Here's each fix.
Playwright installs its browsers to ~/.cache/ms-playwright, which on the Linux runner resolves to /home/runner/.cache/ms-playwright. That directory is what you cache. The binaries only change when your Playwright version changes, so keying the cache to a hash of package-lock.json is a convenient proxy. Updating Playwright turns the cache over, though any unrelated dependency edit does too, which forces the occasional slow run you didn't strictly need.
One thing most guides skip: the cache stores the browser binaries but not the OS libraries they need, because those get installed system-wide with apt and never land in ~/.cache/ms-playwright. On a cache hit the binaries are present but the libraries are missing, and tests fail with Host system is missing dependencies to run browsers. So you install the libraries on a cache hit too, just without the download:
yaml
steps:
- name: Cache Playwright browsers
id: playwright-cache
uses: actions/cache@v6
with:
path: ~/.cache/ms-playwright
key: ${{ runner.os }}-playwright-${{ hashFiles('package-lock.json') }}
- name: Install Playwright browsers and system dependencies
if: steps.playwright-cache.outputs.cache-hit != 'true'
run: npx playwright install --with-deps
- name: Install OS dependencies for browsers
if: steps.playwright-cache.outputs.cache-hit == 'true'
run: npx playwright install-deps
The id on the cache step is what lets the two install steps read cache-hit and pick a branch. On a cache miss, playwright install --with-deps downloads browsers and libraries together. On a cache hit, playwright install-deps runs instead, every time, installing only the libraries. It's fast because there's no download, just a dependency check apt has already satisfied. Each job starts from a clean machine, so this isn't a one-off step you skip later.
One alternative skips caching: run the job inside the official mcr.microsoft.com/playwright image, which ships with browsers and OS packages preinstalled. You're trading the browser download for an image pull rather than removing it. It's a common choice for visual regression work where consistent rendering matters, but for most suites the cache is lighter.
The 2m 25s test run is Playwright doing exactly what the config told it to. Two changes fix it.
fullyParallel: true lets tests within a single file run across workers. By default Playwright parallelizes separate files but runs tests inside one file in order, so a suite concentrated in a few large files leaves most workers idle. The second change replaces the hard one-worker cap with a percentage:
typescript
export default defineConfig({
fullyParallel: true, // top-level, applies to every project
workers: process.env.CI ? "50%" : undefined, // top-level, not inside a project
use: {/* ... */},
projects: [/* chromium, firefox, webkit */],
});
Both keys sit at the top level of defineConfig, alongside use and projects, not nested inside any one project.
On the worker count, one assumption gets repeated: that GitHub's free runners are 2-core. That's true for private repos, but public repos now get 4-core Linux runners for free. On a 2-core runner undefined resolves to one worker, so the default is effectively serial. On a 4-core runner the same undefined gives you two workers out of the box.
| Runner | Cores | 50% gives you | Worth trying |
|---|---|---|---|
| Private repo, ubuntu-latest | 2 | 1 worker | Set to 2 explicitly |
| Public repo, ubuntu-latest | 4 | 2 workers | 75% or 100%, then measure |
| Larger runner | 8 | 4 workers | 75% and up, more headroom |
Start at 50%, look at wall-clock time on your suite, and raise it in steps until the run stops getting faster or the tests start going flaky. There's no single correct number, since it depends on core count, how heavy your tests are, and how much memory each browser instance eats. The thing not to do is push workers well above your core count. Once workers contend for the same cores and RAM, you trade a faster run for memory pressure and intermittent failures that didn't exist serially.
With fullyParallel on and the cap lifted, the test run on a 4-core runner drops to roughly half, and the install step is already cached. Those two fixes together pull the whole job under five minutes.
The baseline was hiding something. The default config runs your tests against Chromium, Firefox, and WebKit, so those 40 tests were actually 120 test runs on every push. A good share of that 2m 25s was the same assertions executing twice more against browsers that rarely surface a bug the first one missed.
If your product doesn't need every browser verified on every change, tier it by event. Run Chromium on every PR, where the feedback loop needs to be fast and most rendering and logic bugs show up. Save the full three-browser sweep for merges to main or a nightly schedule. It's a single flag switched on the triggering event:
yaml
on:
pull_request:
push:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- name: Run Playwright tests
run: |
if [ "${{ github.event_name }}" = "pull_request" ]; then
npx playwright test --project=chromium
else
npx playwright test
fi
On a PR this runs Chromium alone. On a push to main it falls through to the full set. This keeps everything in one job. Local runs are unaffected, since the conditionals key off the CI event.
If you'd rather run the three browsers as separate parallel jobs on main, a conditional matrix does that:
yaml
jobs:
test:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
project: ${{ github.event_name == 'push'
&& fromJSON('["chromium", "firefox", "webkit"]')
|| fromJSON('["chromium"]') }}
steps:
- run: npx playwright test --project=${{ matrix.project }}
A push to main fans out into three jobs, one per browser; a PR collapses to a single Chromium job. It stays bounded at three jobs, so it doesn't drift into open-ended job-splitting.
One caveat on WebKit: the build Playwright runs on Linux tracks WebKit's main development branch, often ahead of what Apple ships in Safari, and it lacks Apple's platform integrations. A green Linux WebKit run is a good signal for layout and JavaScript bugs, but it's not proof the page looks right in Safari. When that distinction matters you need macOS runners, which is a separate decision from this workflow.
Playwright writes an HTML report on every run, but a CI runner is torn down when the job ends, so by default that report vanishes and you never see it. Teams usually discover this on their first failing run, when they go looking for the detail behind a red X and find nothing left to open.
Upload it as an artifact before the job exits:
yaml
steps:
- name: Upload Playwright report
uses: actions/upload-artifact@v7
if: ${{ !cancelled() }}
with:
name: playwright-report
path: playwright-report/
retention-days: 14
The if: ${{ !cancelled() }} is doing real work. Without it, the step only runs when everything before it passed, which is backwards, since the run you most want the report for is the one that failed. This uploads whether tests passed or failed and skips only on a manual cancel. Use retention-days: 14 for active development and 30 on release branches.
The artifact gives you the full report but costs a few clicks. You can't open the HTML file directly, since it loads its data over HTTP, so you download the zip, unzip it, and run npx playwright show-report path/to/playwright-report. Fine when you need a trace, more friction than most failures deserve.
That's where a second reporter comes in. The github reporter writes failures as inline annotations in the Actions UI, so a failed assertion shows up on the run summary and against the offending line in the diff, no download in the loop. Add it alongside the HTML reporter rather than replacing it:
typescript
export default defineConfig({
reporter: [["html"], ["github"]],
// ... rest of your config
});
Now a failed run annotates the summary with what broke and where, and the full HTML report is still attached for the times you need the trace, screenshots, and step timeline.
If your tests need a base URL or an API token, pass it through the test step with an env block. Non-sensitive values can go straight in the workflow; anything secret goes in a repository secret and gets referenced:
yaml
steps:
- name: Run Playwright tests
env:
BASE_URL: https://staging.example.com
API_TOKEN: ${{ secrets.API_TOKEN }}
run: # ... as above
Sharding splits your suite across several CI jobs running in parallel, each handling a slice, with a final step merging the reports. It's the standard answer to a slow Playwright suite, and it works, but it solves a problem you don't have until a single runner genuinely can't keep up.
The decision rule: start with workers and fullyParallel, tune the worker count, and measure your best single-runner time. If you've maxed that and still need more speed, try a bigger runner before sharding. An 8 or 16-core GitHub-hosted runner gives you more workers without the merge-reports step or shard-count maintenance. Only reach for sharding when one runner, even a larger one, can't finish inside your PR review window.
| Suite size | Single-runner time | What to do |
|---|---|---|
| Under 50 tests | Well under 5 min | Workers and fullyParallel are plenty |
| 50–200 tests | Around 3 to 5 min | Move to a bigger runner before you shard |
| Over 200 tests, or 10+ min | Past your PR window | Shard, or move the run off your own CI |
Run time is what matters here, not test count. A suite of heavy end-to-end flows hits the ceiling sooner than the same number of light page checks. Sharding buys wall-clock time; it costs more CI minutes, a merge-reports step, and a shard count you revisit as the suite grows. That's maintenance you take on deliberately, not a default the moment a run feels slow.
Installing browsers without --with-deps. npx playwright install alone fetches binaries but not the system libraries, and runners don't ship those. Tests fail with a "Host system is missing dependencies" error that says nothing about the cause. Use --with-deps on a cache miss and install-deps on a cache hit.
Caching node_modules instead of the npm cache. A restored node_modules can carry platform-specific or partially built dependencies that don't match the runner, surfacing as subtle failures. Cache ~/.npm by setting cache: 'npm' on the setup-node step and let npm ci rebuild cleanly each run.
Setting workers too high for the runner. More workers stop helping once they outnumber the cores, and past that point the browser instances contend for CPU and memory, trading speed for flakiness. Scale to the runner and raise only as far as your measurements stay stable.
Forgetting the github reporter. Without it, a failed run tells you something broke but not what. Adding ['github'] alongside ['html'] puts the failure inline on the summary.
A fast Playwright pipeline on GitHub Actions doesn't require sharding. Caching the browser binaries and tuning parallelism for your runner are both afternoon-sized config changes, and they pay off on every PR rather than once. The single-runner setup holds for a good while as a suite grows, and outgrowing it is a scaling decision to make on purpose when your numbers cross the line, not evidence something was done wrong.
If your suite has crossed that line and you don't want to own shard counts, matrix jobs, and report merging, Endform gives you the same parallelism without the CI plumbing.