This reusable GitHub Actions testing pipeline runs Playwright end-to-end tests on pull requests and pushes to your main branch, checks multiple browsers, splits work across parallel jobs, and preserves reports and debugging artifacts when a run fails.
Overview
A useful CI pipeline for tests should do more than return a pass or fail status. It should provide fast feedback on pull requests, exercise the browser environments that matter to your product, and leave enough evidence to diagnose a failure without reproducing it locally.
The workflow below is designed as a starting point for GitHub Actions testing with Playwright. It assumes that your repository already contains a Playwright project and that package.json includes the required test dependencies. The example uses a browser matrix for Chromium, Firefox, and WebKit, plus two Playwright shards per browser. That creates six independent jobs, so adjust the matrix to match your suite size and CI budget.
This is not a replacement for unit, API, or integration tests. Browser tests are most valuable when they cover important user journeys, while faster checks provide earlier feedback. For a broader deployment process, compare this workflow with the checks in our CI/CD testing checklist.
Template structure
Create a file such as .github/workflows/playwright.yml. The action versions shown here are practical placeholders; review them as part of normal dependency maintenance rather than treating them as permanent values.
name: Playwright end-to-end tests
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
concurrency:
group: playwright-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
test:
timeout-minutes: 20
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
browser: [chromium, firefox, webkit]
shard: [1, 2]
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 Playwright tests
run: npx playwright test --project=${{ matrix.browser }} --shard=${{ matrix.shard }}/2
env:
CI: true
BASE_URL: ${{ vars.TEST_BASE_URL }}
TEST_USER_EMAIL: ${{ secrets.TEST_USER_EMAIL }}
TEST_USER_PASSWORD: ${{ secrets.TEST_USER_PASSWORD }}
- name: Upload Playwright report
if: always()
uses: actions/upload-artifact@v4
with:
name: playwright-report-${{ matrix.browser }}-${{ matrix.shard }}
path: playwright-report/
retention-days: 14
if-no-files-found: ignore
- name: Upload test results
if: always()
uses: actions/upload-artifact@v4
with:
name: playwright-results-${{ matrix.browser }}-${{ matrix.shard }}
path: test-results/
retention-days: 14
if-no-files-found: ignoreSeveral design choices are deliberate:
- Pull requests and main pushes: pull requests receive early feedback, while a push to
mainconfirms the branch after merging. - Least-privilege permissions: the workflow only requests read access to repository contents. Add permissions only when a later step genuinely needs them.
- Concurrency: a newer commit can cancel an older in-progress run for the same reference. This reduces redundant work during active pull requests.
- Fail-fast disabled: one browser failure does not stop the other matrix jobs, giving you a fuller picture of cross-browser impact.
- Artifacts uploaded with
always(): screenshots, traces, videos, and reports remain available after a failed test.
Configure Playwright to produce the artifacts you need. For example, use an HTML reporter and retain traces for failed tests in CI. Keep the report directory consistent with the workflow, or change the artifact path to match your configuration. Our guide to debugging failed browser tests in CI covers how to use these files effectively.
How to customize
Match the workflow to your package scripts
If your repository exposes a script such as test:e2e, replace the direct command with npm run test:e2e -- --project=.... Keep the CI command explicit enough that a reviewer can see which suite is running. In a monorepo, use the package's working directory or a selective test strategy instead of installing and running every project on every change. See our monorepo CI strategy guide for patterns involving change detection and caching.
Choose browsers and parallelism intentionally
Start with the browsers that reflect your supported user journeys. Adding every available project can multiply execution time without improving coverage. Likewise, increase the shard count only when the suite is large enough to benefit from it. More parallel jobs can expose shared test data problems, rate limits, or environment contention.
Each shard must use a unique artifact name. If you add a third shard, change the command to --shard=${{ matrix.shard }}/3 and update the matrix. For a small smoke suite, remove sharding altogether and keep the browser matrix if cross-browser validation is important.
Handle application startup and environment configuration
If Playwright starts a local application through webServer in playwright.config.ts, make sure the command can run in a clean CI environment and that its port matches baseURL. If the application is deployed to a test environment, set BASE_URL through a GitHub Actions variable or secret and avoid placing credentials in the repository.
Use dedicated test accounts and predictable data. Do not use personal credentials, production tokens, or secrets in screenshots and logs. For repeatable setup and cleanup, review test data management for automated QA.
Use retries as a diagnostic tool
A small CI-only retry allowance can help distinguish an intermittent failure from a consistently broken test, but it should not make an unreliable suite appear healthy. Record retry outcomes and investigate tests that pass only on a second attempt. Keep local runs stricter so developers see the underlying problem. Our guide on adding retries without hiding failures provides a useful policy framework.
Examples
Pull request checks versus release checks
A practical two-level approach is to run a focused smoke set on every pull request and the broader regression suite on pushes to main or before deployment. You can implement this with separate jobs, tags, or Playwright projects. Keep the pull request suite stable and fast; a large, noisy check teaches contributors to ignore CI.
Publishing a combined report
The workflow above stores one report per browser and shard. That is simple and reliable, but it requires opening several artifacts. If your team needs one report, add a dependent aggregation job that downloads all result directories, merges the Playwright blob reports, and uploads a single HTML report. Ensure each job writes to a distinct directory before merging; otherwise parallel jobs can overwrite files or make the result ambiguous.
Adding API checks
API checks can run in the same workflow before browser tests when they validate a prerequisite service or authentication path. A separate job is often easier to troubleshoot and can provide faster feedback. Use the browser job for user journeys and API tests for contracts, permissions, and data setup. See API testing in CI/CD for pipeline patterns.
Investigating a flaky test
When a job fails intermittently, first identify the browser, shard, commit, and retry status. Inspect the trace and screenshot, then ask whether the test depends on time, order, shared data, network availability, or an unstable selector. Prefer explicit waits for meaningful UI state, isolated fixtures, deterministic seeds, and accessible or role-based locators. Do not solve a product defect by adding a long fixed delay.
When to update
Revisit this workflow whenever the application, test suite, or publishing process changes. In particular, review it when:
- the supported browser list or minimum Node.js version changes;
- the Playwright configuration, report directory, or package manager changes;
- the suite becomes slow enough to require different shard counts;
- new secrets, test accounts, services, or network permissions are introduced;
- artifact retention no longer matches your debugging and compliance needs;
- failures cluster in one browser, shard, or test environment; or
- your deployment process needs smoke, regression, visual, or API checks at a different stage.
As a maintenance routine, inspect failed artifacts, retry rates, duration by project, and tests that are frequently skipped or quarantined. A pipeline is healthy when its failures are actionable, not merely when its final status is green. For a broader measurement approach, use our guide to test suite health.
Next step: copy the workflow, replace the browser projects and environment variables with values from your repository, run it against a small smoke suite, and confirm that a deliberately failing test uploads its report and debugging files. Then expand coverage gradually, documenting why each browser, shard, retry, and secret exists.
