The Playwright + GitHub Actions setup that actually runs fast

Jakob Norlin — Tue, 15 Sep 2026 14:53:37 +0000

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.

The complete workflow

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

      # Cache the browser binaries. The lockfile is a proxy for the
      # Playwright version, so it usually turns over when you update Playwright.
      - name: Cache Playwright browsers
        id: playwright-cache
        uses: actions/cache@v6
        with:
          path: ~/.cache/ms-playwright
          key: ${{ runner.os }}-playwright-${{ hashFiles('package-lock.json') }}

      # Cache miss: download browsers and system libraries together
      - name: Install browsers and system dependencies
        if: steps.playwright-cache.outputs.cache-hit != 'true'
        run: npx playwright install --with-deps

      # Cache hit: binaries are restored, but system libraries still need installing
      - name: Install OS dependencies for browsers
        if: steps.playwright-cache.outputs.cache-hit == 'true'
        run: npx playwright install-deps

      # Chromium only on PRs for fast feedback; the full browser set on merges to main
      - name: Run Playwright tests
        run: |
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            npx playwright test --project=chromium
          else
            npx playwright test
          fi

      # Upload the report whether tests pass or fail, so failures are never lost
      - 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.

Where the time actually goes

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.

Fix 1: cache the browser binaries

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.

Fix 2: run tests in parallel with workers

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.

Fix 3: run only the browsers you need

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:
      # checkout, setup-node, cache, and install from the earlier sections
      - 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:
      # same setup 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.

Get the failure report off the runner

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.

Passing config and secrets

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

When to add sharding (and when not to)

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.

Common setup mistakes

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.

Wrapping up

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.

DEV Community: Jakob Norlin