| | |

Playwright 22 ๐ŸŽญ CI Integration โ€” GitHub Actions and npx playwright install-deps

โฑ๏ธ Estimated read: 9 min | |

Automating end-to-end test execution within continuous integration pipelines is critical for catching regressions before code reaches production. However, transitioning a Playwright test suite from a local developer workstation to a remote CI runnerโ€”such as GitHub Actionsโ€”introduces significant environmental challenges. Clean virtual machines lack pre-installed browser binaries, shared libraries, and graphical display drivers required by modern web rendering engines like Chromium, Firefox, and WebKit. Without proper environment provisioning, test runs fail immediately with missing shared library errors or launch crashes.

To bridge this gap, Playwright provides robust automation tools designed specifically for continuous integration servers, most notably the npx playwright install-deps command, which automatically detects missing Linux system packages and installs them via native package managers. Mastering CI integration involves structuring workflow YAML files, caching browser binaries and node modules across builds, handling headless display configurations, and archiving test trace artifacts for post-execution debugging. This chapter explores automated dependency installation, GitHub Actions workflow configuration, caching strategies, and artifact management.

Key point: Running Playwright inside headless continuous integration environments requires installing mandatory operating system browser dependencies via npx playwright install-deps and configuring reliable caching mechanisms to prevent build timeouts.

Why X exists

The missing system library problem.

Standard continuous integration runner images (such as Ubuntu runners on GitHub Actions) lack the low-level shared libraries, graphics drivers, and system dependencies required to execute compiled browser binaries.

The ephemeral runner initialization cost.

Every CI build runs on a fresh, ephemeral virtual machine, meaning all Node modules, dependency packages, and browser binaries must be downloaded and configured from scratch on every pipeline trigger.

The headless display server requirement.

Executing browser test suites in headless server environments often requires virtual framebuffer management to prevent rendering crashes or viewport initialization failures on systems without physical displays.

The flaky artifact retention challenge.

When a test fails inside a remote CI container, developers cannot inspect the live browser state directly, necessitating automated artifact retention for traces, videos, and screenshots.

The version drift hazard.

Allowing CI pipelines to pull arbitrary browser versions without locking Playwright package versions causes silent regression mismatches between local testing environments and production CI servers.

a. Provisioning Operating System Dependencies with install-deps

Playwright browser binaries rely on numerous operating system packages, including GLib, NSS, D-Bus, and various font rendering libraries. On Linux CI runners, missing a single shared library causes browser launch routines to throw fatal errors. The npx playwright install-deps command inspects the host operating system, identifies missing packages, and installs them using the system package manager with appropriate administrative privileges.

Bash

# Automatically install missing OS shared libraries required by Playwright browsers
npx playwright install --with-deps

Bash

# Install only operating system dependencies without downloading browser binaries
npx playwright install-deps

Invoking npx playwright install --with-deps combines browser binary downloading with system dependency installation in a single atomic step. This is the standard command used in continuous integration build scripts to prepare clean virtual machines before executing test suites.

b. Structuring GitHub Actions Workflows for Playwright

GitHub Actions manages continuous integration workflows through YAML configuration files stored in .github/workflows/. A robust Playwright workflow must handle Node.js environment setup, package dependency installation, browser binary downloading, test execution, and artifact uploading.

YAML

# .github/workflows/playwright.yml
name: Playwright Tests
on:
  push:
    branches: [ main, master ]
  pull_request:
    branches: [ main, master ]
jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: 20
        cache: 'npm'
    - name: Install dependencies
      run: npm ci
    - name: Install Playwright Browsers and OS Dependencies
      run: npx playwright install --with-deps
    - name: Run Playwright test suite
      run: npx playwright test
    - uses: actions/upload-artifact@v4
      if: ${{ !cancelled() }}
      with:
        name: playwright-report
        path: playwright-report/
        retention-days: 30

This workflow definition checks out the repository, configures Node.js 20 with npm caching, installs project packages, provisions system and browser binaries, executes the test suite, and uploads the generated HTML report artifact even if test steps fail.

c. Caching Playwright Browsers and Node Modules

Because downloading browser binaries (~/.cache/ms-playwright) and node_modules on every build consumes valuable CI minutes and bandwidth, configuring GitHub Actions caching is essential for maintaining fast feedback loops.

YAML

    - name: Cache Playwright Browsers
      uses: actions/cache@v4
      id: playwright-cache
      with:
        path: ~/.cache/ms-playwright
        key: ${{ runner.os }}-playwright-${{ hashFiles('**/package-lock.json') }}
        restore-keys: |
          ${{ runner.os }}-playwright-

By caching the ms-playwright directory based on the hash of package-lock.json, subsequent workflow runs skip downloading browser binaries when dependencies remain unchanged, reducing total pipeline duration significantly.

Complete Example Session

YAML

# ============================================
# PART 1: COMPLETE GITHUB ACTIONS WORKFLOW STRUCTURE
# ============================================
name: E2E Verification Pipeline
on: [push]

YAML

# ============================================
# PART 2: JOB ENVIRONMENT CONFIGURATION
# ============================================
jobs:
  e2e:
    runs-on: ubuntu-latest
    container:
      image: mcr.microsoft.com/playwright:v1.45.0-jammy

YAML

# ============================================
# PART 3: REPOSITORY CHECKOUT STEP
# ============================================
    steps:
    - name: Checkout Source Code
      uses: actions/checkout@v4

YAML

# ============================================
# PART 4: NODE.JS SETUP STEP
# ============================================
    - name: Setup Node Runtime
      uses: actions/setup-node@v4
      with:
        node-version: 20
        cache: 'npm'

YAML

# ============================================
# PART 5: DEPENDENCY INSTALLATION STEP
# ============================================
    - name: Install Node Packages
      run: npm ci

YAML

# ============================================
# PART 6: BROWSER INSTALLATION COMMAND
# ============================================
    - name: Ensure Browsers Installed
      run: npx playwright install --with-deps

YAML

# ============================================
# PART 7: TEST EXECUTION COMMAND WITH RETRIES
# ============================================
    - name: Execute Test Suite
      run: npx playwright test --retries=2
      env:
        CI: true

YAML

# ============================================
# PART 8: ARTIFACT UPLOAD CONFIGURATION
# ============================================
    - name: Upload Test Artifacts
      uses: actions/upload-artifact@v4
      if: failure()
      with:
        name: failure-traces
        path: test-results/

TypeScript

// ============================================
// PART 9: PLAYWRIGHT CONFIGURATION FOR CI RUNS
// ============================================
import { defineConfig } from '@playwright/test';

export default defineConfig({
  reporter: 'html',
  use: {
    trace: 'on-first-retry',
  },
});

TypeScript

// ============================================
// PART 10: WORKFLOW FINALIZATION
// ============================================
// CI pipeline setup completed and verified for automated execution

Quick Reference

GitHub Actions Workflow Actions

ActionPurpose
actions/checkout@v4Checks out repository source code into the runner
actions/setup-node@v4Installs specified Node.js version and configures caching
actions/cache@v4Caches arbitrary directories (like ms-playwright) across builds
actions/upload-artifact@v4Uploads test reports and trace files for download

Playwright CI CLI Commands

CommandAction Performed
npx playwright installDownloads browser binaries for Chromium, Firefox, and WebKit
npx playwright install-depsInstalls required Linux OS shared libraries
npx playwright install --with-depsCombines browser binary download and OS dependency installation
npx playwright test --retries=2Runs tests with automated retries for flaky network interactions

Best Practices

โœ… Do This:

YAML

run: npx playwright install --with-deps                                     // โœ…

โŒ Don’t Do This:

YAML

run: npx playwright install // omitting system dependencies on CI runners   // โŒ

โœ… Do This:

YAML

uses: actions/upload-artifact@v4                                            // โœ…

โŒ Don’t Do This:

YAML

// omit uploading test reports and traces when CI test runs fail             // โŒ

โœ… Do This:

TypeScript

use: { trace: 'on-first-retry' }                                            // โœ…

โŒ Don’t Do This:

TypeScript

use: { trace: 'on' } // record heavy traces on every test pass unconditionally // โŒ

โœ… Do This:

YAML

timeout-minutes: 60                                                         // โœ…

โŒ Don’t Do This:

YAML

// leave workflow timeout unconfigured, risking infinite hanging jobs        // โŒ

Common Pitfalls

PitfallWhy It HappensFix
error while loading shared libraries: libnspr4.soRunning Playwright on Linux CI without installing system dependenciesRun npx playwright install --with-deps in your workflow steps
CI build timeout during browser downloadsDownloading browser binaries on every build without cachingImplement caching for the ~/.cache/ms-playwright directory
Missing test reports on failureUsing outdated actions/upload-artifact@v3 syntax or omitting conditional guardsUpdate to actions/upload-artifact@v4 and use if: ${{ !cancelled() }}
Version mismatch between local and CIUsing npx playwright install without locking package versionsEnsure Playwright package version in package.json matches browser binaries

Real-World Examples

1. Installing Browsers and Dependencies in GitHub Actions

YAML

- name: Install Playwright and OS Dependencies
  run: npx playwright install --with-deps

2. Caching Playwright Browser Binaries Across Runs

YAML

- name: Cache Playwright Browsers
  uses: actions/cache@v4
  with:
    path: ~/.cache/ms-playwright
    key: ${{ runner.os }}-playwright-${{ hashFiles('**/package-lock.json') }}

3. Running Playwright Inside an Official Docker Container

YAML

jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: mcr.microsoft.com/playwright:v1.45.0-jammy
      options: --user root

4. Uploading Playwright HTML Reports on Test Completion

YAML

- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: playwright-html-report
    path: playwright-report/

5. Executing Tests with CI Environment Variable Flag

YAML

- name: Run E2E Tests
  run: npx playwright test
  env:
    CI: true

6. Configuring Trace Recording on First Retry

TypeScript

export default defineConfig({
  use: {
    trace: 'on-first-retry',
  },
});

7. Setting Job Timeouts to Prevent Hanging Pipelines

YAML

jobs:
  e2e:
    timeout-minutes: 45
    runs-on: ubuntu-latest

8. Installing Only Operating System Dependencies

YAML

- name: Install OS Dependencies Only
  run: npx playwright install-deps

9. Capturing Video Artifacts on Test Failure

TypeScript

export default defineConfig({
  use: {
    video: 'retain-on-failure',
  },
});

10. Running Specific Project Suites in CI

YAML

- name: Run Chromium Tests Only
  run: npx playwright test --project=chromium

Visual

Standard CI Runner vs. Playwright Provisioned Runner

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ STANDARD CI RUNNER: Clean VM lacking system libraries โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                            โ”‚
                            โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ PROVISIONED RUNNER: `npx playwright install --with-deps`โ”‚
โ”‚ Installs GLib, NSS, D-Bus & Browser Binaries           โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

GitHub Actions Pipeline Execution Flow

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ Checkout Code โ”€โ”€โ–บ Setup Node โ”€โ”€โ–บ Install npm Packages  โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                            โ”‚
                            โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ Cache Check โ”€โ”€โ–บ Install Browsers (`ms-playwright`)     โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                            โ”‚
                            โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ Execute Tests (`playwright test`) โ”€โ”€โ–บ Upload Artifacts โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Caching Optimization Architecture

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ package-lock.json Hash Match?                          โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
โ”‚ โ€ข YES โ”€โ”€โ–บ Restore Cached ~/.cache/ms-playwright       โ”‚
โ”‚ โ€ข NO  โ”€โ”€โ–บ Download Fresh Binaries & Update Cache       โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Summary

ItemValue
ConceptContinuous Integration Integration for Playwright
Critical Commandnpx playwright install --with-deps
OS Dependency Toolnpx playwright install-deps
Workflow PlatformGitHub Actions (.github/workflows/)
Caching Directory~/.cache/ms-playwright
Artifact Actionactions/upload-artifact@v4
Execution FlagCI: true environment variable
Failure DebuggingTraces, videos, and HTML report archiving
Pipeline ProtectionJob timeout limits and automated test retries
Official AlternativeMicrosoft Playwright Docker base images

Key takeaways:

  • Provision system dependencies. Always execute npx playwright install --with-deps on Linux CI runners to supply missing shared libraries required by browser binaries.
  • Automate GitHub Actions workflows. Structure YAML configuration files to handle code checkout, Node setup, package installation, and test execution seamlessly.
  • Implement browser caching. Cache the ms-playwright binary directory using actions/cache keyed against package-lock.json to accelerate pipeline run times.
  • Retain test failure artifacts. Upload HTML reports, traces, and videos using actions/upload-artifact@v4 to inspect failed CI runs without local reproduction.
  • Configure automated retries. Enable test retries on CI environments to mitigate intermittent network latency and flaky external service calls.
  • Leverage Docker containers. Utilize official Microsoft Playwright container images as an alternative to installing system dependencies manually on base runners.

Remember: Integrating Playwright into continuous integration pipelines transforms local test validation into robust automated quality gates. By combining npx playwright install --with-deps, efficient browser caching, and reliable artifact retention, engineering teams can maintain fast, stable, and dependable end-to-end testing workflows.

Was this helpful?


Stop using slow, ad-bloated tool sites! ๐Ÿคฎ

๐Ÿ”Ž Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
โœ… Finance (Mortgage, Interest, Inflation)
โœ… Tech (Base64, JSON, Dev Suite, IP)
โœ… Health (BMI, BMR, TDEE)
โœ… Productivity (Timer, Workspace, QR)

โšก๏ธ Fast & Private
๐Ÿ”’ No data leaves your device
๐Ÿ’Ž 100% Free

๐Ÿ”— Use it now: https://tools.kandz.me
๐Ÿ”– Bookmark itโ€”youโ€™ll need it later!