Running Playwright locally is useful, but a reliable CI pipeline turns end-to-end tests into a repeatable release safeguard. This checklist shows how to run Playwright in GitHub Actions, install browsers consistently, cache dependencies safely, parallelize large suites, preserve diagnostics, and revisit the workflow as your application changes.
Overview
A maintainable Playwright CI workflow should do more than execute a command and return a pass or fail status. It should create a predictable environment, install the browser version expected by the project, make failures diagnosable, and finish within a reasonable time without masking defects.
The basic sequence is:
- Check out the repository.
- Install the required Node.js version.
- Restore or create a dependency cache.
- Install project dependencies with a lockfile-aware command.
- Install the Playwright browsers and operating-system dependencies.
- Run the appropriate test command.
- Upload reports, screenshots, videos, and traces when useful.
Keep the first workflow deliberately small. Start with a smoke or critical-path suite on pull requests, then add broader regression coverage, browser projects, or sharded jobs once the basic pipeline is stable. This separates CI/CD testing design from the question of how many tests the suite contains.
For a fuller implementation, compare this checklist with our guide to building a reliable Playwright CI pipeline with GitHub Actions.
Checklist by scenario
For a first GitHub Actions workflow
Use a workflow that makes versions and commands explicit. The following example is a starting point rather than a universal configuration:
name: Playwright tests
on:
pull_request:
push:
branches: [main]
jobs:
test:
timeout-minutes: 15
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version-file: .nvmrc
cache: npm
- name: Install dependencies
run: npm ci
- name: Install Playwright browsers
run: npx playwright install --with-deps
- name: Run tests
run: npx playwright test
- name: Upload report
if: ${{ !cancelled() }}
uses: actions/upload-artifact@v4
with:
name: playwright-report
path: playwright-report/
retention-days: 7
Use the package manager and lockfile your project actually uses. For npm, npm ci is generally appropriate when a lockfile is committed. For pnpm or Yarn, use the corresponding immutable or frozen-lockfile option. The important practice is that CI should not silently rewrite dependency versions.
For pull requests and main-branch runs
Give each event a clear purpose. Pull requests usually benefit from a fast, high-value suite that provides feedback before merge. Runs on the main branch can include additional browsers, longer regression coverage, or tests against a deployed preview. Avoid making every pull request wait for every low-value scenario if that creates pressure to bypass the workflow.
Define environment variables and secrets at the workflow or job level, and keep test credentials limited to the permissions the tests need. If the application requires a server, start it with Playwright's webServer configuration or an explicit workflow step, then confirm that the base URL and readiness behavior are consistent in local and CI environments.
For dependency and browser caching
Dependency caching can reduce setup time, but it must be invalidated when the lockfile changes. The actions/setup-node cache option is a convenient choice for common package managers because the cache key can include the dependency lockfile. Do not treat a cache as the source of truth: the workflow should remain correct after a cache miss.
Playwright browser binaries are tied to the Playwright version. If you introduce a separate browser cache, include the lockfile or Playwright package version in its key. A stale browser cache can produce confusing mismatches, so simplicity is often preferable until installation time is a measured problem.
For parallel test execution
Playwright can distribute work across workers on one runner, and GitHub Actions can distribute work across multiple matrix jobs. For a larger suite, sharding is often easier to reason about than increasing the worker count indefinitely:
strategy:
fail-fast: false
matrix:
shard: [1/4, 2/4, 3/4, 4/4]
steps:
- name: Run Playwright shard
run: npx playwright test --shard=${{ matrix.shard }}
Set fail-fast: false when you want all shards to finish and produce diagnostics. Make sure each shard receives compatible test data and that cleanup does not remove resources another shard still needs. Parallel execution is not automatically faster when tests contend for a shared database, account, or environment.
For reports and failed-test diagnosis
Configure traces, screenshots, and videos selectively. A useful default is to capture a trace on the first retry and screenshots on failure, while avoiding large video files for every successful test. Upload the HTML report and diagnostic artifacts even when the test job fails, using an upload condition such as if: ${{ !cancelled() }}.
Use the report to answer three questions: which test failed, where it failed, and whether the failure is reproducible. For broader reporting practices, see how to measure test suite health and the flaky test troubleshooting guide.
What to double-check
- Node and Playwright versions: Pin or centrally define versions so local development and CI do not drift unexpectedly.
- Browser installation: Confirm that the workflow installs the browsers required by the configured projects, including operating-system dependencies on Linux runners.
- Application readiness: Verify that the test server is listening before tests start. A fixed sleep is usually less reliable than a readiness check.
- Base URL and secrets: Check that URLs, authentication state, API keys, and feature flags are supplied through the intended environment variables.
- Test isolation: Ensure tests do not depend on execution order, a developer's local data, or a shared account that parallel jobs can mutate.
- Retries: Keep retries limited and visible. A retry may help identify environmental instability, but it should not turn a repeatable product defect into a passing build.
- Artifacts: Confirm that reports and traces are uploaded on failure and that retention matches the team's debugging needs.
- Permissions: Give the workflow only the repository and deployment permissions it requires.
If test data is the source of intermittent failures, review test data management for automated QA before adding more retries.
Common mistakes
Installing dependencies with a floating command. Using an install command that changes the lockfile can make two CI runs resolve different packages. Use a lockfile-enforcing command and review dependency updates deliberately.
Caching without a useful key. A cache that ignores the lockfile or browser version can preserve incompatible files. Prefer a cache miss over silently reusing the wrong environment.
Running every test in one oversized job. A single job is easy to start with, but it can become slow and difficult to debug. Split by suite or shard only after measuring duration and checking for shared-state conflicts.
Using retries as a quality strategy. Retries can reduce noise from occasional infrastructure problems, but they can also hide synchronization bugs. Track tests that pass only after retry and fix their underlying causes. The guide on adding retries without hiding real failures provides a useful review point.
Uploading no diagnostics. A failed CI status without a trace, screenshot, console output, or report forces developers to reproduce the issue from scratch. Preserve enough evidence to investigate the failure without making every run expensive.
Testing only one browser forever. Start with a practical browser project, then add cross-browser coverage where user traffic, risk, or product requirements justify it. A targeted hosted versus self-hosted infrastructure review can help when local runners no longer provide the coverage or capacity you need.
When to revisit
Review this Playwright CI checklist before a seasonal planning cycle, a major release, or a change to the workflow, runner image, package manager, browser matrix, or deployment process. Also revisit it when the suite becomes noticeably slower, when developers stop trusting failures, or when a new application area introduces different test-data and authentication needs.
Use this short review sequence:
- Compare CI duration with the previous baseline and identify the slowest suites.
- Check the rate of first-run failures, retry-only passes, and infrastructure failures.
- Confirm that browser, Node.js, action, and dependency versions still match the team's support plan.
- Open a recent failed report and verify that the available artifacts are sufficient to diagnose it.
- Remove obsolete matrix entries, secrets, caches, and workarounds.
- Update the smoke suite when critical user journeys change.
For repositories with multiple applications, selective execution and change detection may be more valuable than adding more runners; see the guide to monorepo test strategies for CI. The goal is a CI pipeline that remains fast enough to use, strict enough to protect releases, and transparent enough that failures lead to fixes rather than repeated reruns.