Docs

CI/CD

How to Run Playwright Tests in GitHub Actions

Set up a GitHub Actions workflow for Playwright with current checkout and Node actions, browser installation, reports, traces, caching, secrets, and CI troubleshooting.

Software Testing Automation Editorial TeamEditorial publishing identity
Published
Reading time
3 min read
Difficulty
Intermediate
Audience
For Automation tester, Developer, QA engineer
On this page
  1. Verify the prerequisites
  2. Create the workflow file
  3. What each workflow section does
  4. Reports, traces, and failure artifacts
  5. Environment variables and GitHub secrets
  6. Parallel execution and sharding
  7. Common CI-only failures
  8. Key takeaways
A workflow file beside a play button, representing tests running automatically
IllustrationA workflow file beside a play button, representing tests running automatically.

Article overview

What you will learn

  • Where a GitHub Actions workflow belongs
  • How triggers, checkout, Node setup, installation, and execution fit together
  • How to upload Playwright reports and traces
  • How caching differs from artifacts
  • How to troubleshoot CI-only failures and scale with sharding

Before you begin

Prerequisites

  • A GitHub repository
  • A Playwright Test project committed to the repository
  • A committed package-lock.json file
  • Permission to create files in .github/workflows

Verify the prerequisites

Run the project locally before debugging CI. From the project directory, check Node.js and run the same installation and test commands the workflow will use.

Terminal Bash
node --versionnpm cinpx playwright install --with-depsnpx playwright test

Create the workflow file

GitHub reads workflow files from .github/workflows. This example runs for pushes and pull requests to main, uses current major versions verified from the official action repositories, installs Playwright dependencies, and retains the HTML report even when tests fail.

.github/workflows/playwright.yml YAML
name: Playwright tests on: push: branches: [main] pull_request: branches: [main] jobs: test: timeout-minutes: 30 runs-on: ubuntu-latest steps: - name: Check out repository uses: actions/checkout@v7 - name: Set up Node.js uses: actions/setup-node@v7 with: node-version: 24 cache: npm - name: Install project dependencies run: npm ci - name: Install Playwright browsers run: npx playwright install --with-deps - name: Run Playwright tests run: npx playwright test - name: Upload HTML report if: ${{ !cancelled() }} uses: actions/upload-artifact@v4 with: name: playwright-report path: playwright-report/ retention-days: 14 if-no-files-found: ignore

What each workflow section does

  • on defines the push and pull-request events that start the workflow.
  • jobs.test creates one job on GitHub’s current Ubuntu runner image.
  • actions/checkout places repository content in the runner workspace.
  • actions/setup-node installs Node.js and enables npm dependency caching based on the lockfile.
  • npm ci performs a clean, reproducible dependency installation.
  • playwright install --with-deps installs browsers and required Linux packages.
  • playwright test executes the configured suite and reporters.
  • upload-artifact preserves the report after the runner is removed. !cancelled() still uploads after test failures but not after cancellation.

Reports, traces, and failure artifacts

Configure traces in playwright.config.ts, commonly with trace: 'on-first-retry', so an intermittent CI failure can include detailed evidence without tracing every successful test. Screenshots and videos can also be retained according to project policy. Artifacts preserve outputs; caches speed repeated setup and should not be used as permanent evidence storage.

Environment variables and GitHub secrets

Non-sensitive configuration can use workflow or repository variables. Put passwords, tokens, and private keys in GitHub Actions secrets and pass only the required values to the test step. Do not print secrets or place them in reports, screenshots, traces, or committed .env files.

.github/workflows/playwright.yml YAML
- name: Run Playwright tests run: npx playwright test env: BASE_URL: ${{ vars.TEST_BASE_URL }} TEST_USER_PASSWORD: ${{ secrets.TEST_USER_PASSWORD }}

Parallel execution and sharding

Playwright Test uses workers within a job. Sharding divides tests across jobs or machines with --shard=1/3, --shard=2/3, and --shard=3/3. Add it after tests use isolated accounts and data. A faster unstable suite produces faster confusion, and merging reports introduces additional workflow steps.

Common CI-only failures

  • The local and CI Node.js or Playwright versions differ.
  • A browser or Linux dependency was not installed.
  • Tests depend on local state, a developer account, or execution order.
  • The CI environment has less CPU or different timing.
  • Time zone, locale, viewport, font, or environment variables differ.
  • The application server is not ready before tests begin.
  • A secret is unavailable to pull requests from untrusted forks.
  • Artifacts are uploaded from a path different from the configured reporter output.

Key takeaways

  • Reproduce CI commands locally before investigating workflow behavior.
  • Pin current action majors and a supported Node.js version deliberately.
  • Use npm ci and the committed lockfile for reproducible installation.
  • Retain reports and failure evidence without exposing secrets.
  • Treat caching, artifacts, workers, and sharding as different tools.
  • Stabilize and isolate tests before increasing parallel scale.

References and further reading

Was this article helpful?

Related articles