Faruk Hasan

Software QA Engineer | Automation & AI-Driven Testing Specialist

Setting Up Playwright Tests in Your CI Pipeline with GitHub Actions

June 20, 2024
12 min read
Playwright, GitHub Actions, CI/CD, Testing

Continuous Integration (CI) is essential for any modern QA workflow—especially when you want to catch issues early and ensure your automated tests run seamlessly every time code changes. In this post, we'll walk through how to integrate Playwright tests into a CI pipeline using GitHub Actions. You'll learn:

  1. What Continuous Integration (CI) Means and why QA Engineers must be part of it
  2. Prerequisites: Git, GitHub, VS Code, Node.js, and basic GitHub Actions knowledge
  3. Step-by-Step Instructions to create a repository, clone it locally, install Playwright, and configure a GitHub Actions workflow
  4. Understanding the test-workflow.yml: triggers, jobs, and steps required to run Playwright tests automatically on every push or pull request
  5. How to Confirm that your CI pipeline is running Playwright tests correctly

By the end, you'll have a working CI pipeline so that any new or existing Playwright tests in your repository run automatically—no manual intervention needed.

Watch the full video tutorial: See a step-by-step demonstration of setting up Playwright tests with GitHub Actions.
Watch on YouTube

Why QA Engineers Need CI

What Is Continuous Integration (CI)?

Continuous Integration is a software development practice where teams frequently integrate code changes into a shared repository. Each time a developer (or QA engineer) pushes code, an automated build-and-test workflow runs to catch errors early. This process ensures:

  • Stability: New code merges don't break existing functionality.
  • Early Feedback: If a test fails, developers are alerted immediately.
  • High Code Quality: Automated tests run against every commit, reducing regressions.

The Role of QA in CI

As a QA Engineer, your responsibilities in a CI environment typically include:

  1. Adding New Tests
    Whenever you create a new Playwright test locally, it must be integrated into the shared repository so everyone—developers, other QA Engineers, and DevOps—can run that test as part of the automated suite.
  2. Running the Full Test Suite
    If the repository already has five tests and you add a sixth, the CI pipeline will automatically run "Test #6 + Tests #1–5." This confirms that your new test coexists without breaking existing checks.
  3. Detecting Failures Early
    If any of the six tests fail, the CI pipeline alerts the team. Early notification makes it easy to fix issues before they cascade into larger problems.

By integrating Playwright tests into your CI workflow, you ensure that new tests "ship" with the code and automatically validate every push or pull request.

Prerequisites

Before diving in, make sure you have:

  • A GitHub Account: You need a shared repository for CI.
  • Git Installed Locally: So you can run git clone, git add, git commit, and git push.
  • VS Code (or another editor): We'll use Visual Studio Code here.
  • Node.js Installed: Playwright requires Node.js to install packages and run tests.
  • Basic Playwright Knowledge: You should know how to write and run Playwright tests locally (e.g., npx playwright test).
  • Familiarity with GitHub Actions (basic understanding of .yml workflows).

Once these are set up, you'll be ready to follow along.

Step 1: Create & Clone the GitHub Repository

  1. Log in to GitHub, click New repository, and name it—for example: 
    ci-playwright-testing
  2. Choose Public (or Private if you have a paid GitHub plan), omit initializing with a README, and click Create repository.
  3. On the repo's main page, click the green Code button, copy the HTTPS (or SSH) URL.
  4. On your local machine, open a terminal and navigate to the folder where you want to store the project. For example: 
    cd ~/Desktop
mkdir ci-playwright-demo
cd ci-playwright-demo
  5. Clone your empty repo: 
    git clone https://github.com/<your-username>/ci-playwright-testing.git
cd ci-playwright-testing

You'll see "Cloning into 'ci-playwright-testing'… done. You appear to have cloned an empty repository." Perfect—that's exactly what we want.

Step 2: Install Playwright & Verify Demo Tests

Playwright comes with a handful of sample tests so you don't have to write your own right away. We'll use those to prove the CI pipeline works end-to-end.

  1. Open the project in VS Code:
    • In VS Code, choose File → Open Folder… and select ci-playwright-testing.
  2. Initialize Playwright by running: 
    npm init playwright@latest
    • Choose TypeScript (or JavaScript if you prefer).
    • Skip GitHub Actions integration for now (we'll add that manually later).
    • When prompted to install dependencies, select Yes.

    This command creates a package.json, a playwright.config.ts (or .js), and a tests/ folder containing example specs like example.spec.ts.

  3. Open a terminal in VS Code (View → Terminal), ensure you're in ci-playwright-testing, and execute: 
    npx playwright test
    • You should see something like "Running 2 tests on 3 browsers" (Chromium, Firefox, WebKit) by default.
    • Once complete, you'll notice "All tests passed." This confirms Playwright is installed and running successfully.
  4. (Optional) Speed Up Local Runs by limiting to Chromium only:
    • In playwright.config.ts, comment out Firefox and WebKit under projects so that tests run faster locally.

Now you have a working set of demo tests in your local repo. Next: configure CI so GitHub runs these same tests every time we push.

Step 3: Create the GitHub Actions Workflow

GitHub Actions uses YAML files to define "workflows." Each workflow specifies:

  1. When to Run (trigger: push, pull_request, etc.)
  2. Which Jobs to Run (e.g., "run Playwright tests on Ubuntu")
  3. Steps Inside Each Job (e.g., "checkout code," "install dependencies," "run npx playwright test")

3.1 Create the Workflow Directory & File

  1. In VS Code's Explorer (left sidebar), ensure you're focused on the ci-playwright-testing root folder.
  2. Add a new folder: Name it 
    .github
  3. Inside .github/, add another folder: 
    workflows

    Now the path is .github/workflows/.

  4. Inside .github/workflows/, create a file named: 
    test-workflow.yml

At this point, your file structure should look like:

ci-playwright-testing/
├── .github/
│   └── workflows/
│       └── test-workflow.yml
├── package.json
├── playwright.config.ts
└── tests/
    └── example.spec.ts

3.2 Define the Workflow Contents

Open test-workflow.yml and populate it with the following:

# test-workflow.yml
name: Run Playwright Tests

# 1. Trigger: Run this workflow on every push or pull request to main
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

# 2. Jobs section: We only have one job—run Playwright tests on Ubuntu
jobs:
  test:
    # The virtual environment (runner) to use
    runs-on: ubuntu-latest

    # 3. Steps within the 'test' job
    steps:
      # 3.1. Checkout the repository code so it's available in the runner
      - name: Check out repository
        uses: actions/checkout@v3

      # 3.2. Install Node.js (LTS). This makes `node` and `npm` available.
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'  # use your preferred Node.js version

      # 3.3. Install project dependencies (i.e., Playwright, etc.)
      - name: Install npm dependencies
        run: npm install

      # 3.4. Install Playwright browsers (Chromium, Firefox, WebKit)
      - name: Install Playwright Browsers
        run: npx playwright install

      # 3.5. Run Playwright tests (headless by default)
      - name: Run Playwright Tests
        run: npx playwright test

How the Workflow Works

  1. name: Run Playwright Tests
    Gives your workflow a human-readable title.
  2. on:
    Specifies events that trigger this workflow. Here, we'll run on any push or pull_request to the main branch.
  3. jobs:
    Under jobs, we define a single job named test. You could add more jobs—linting, building, deployment—later, but for now, QA’s focus is running tests.
  4. runs-on: ubuntu-latest
    Tells GitHub to spin up a fresh Ubuntu virtual machine.
  5. steps:
    A sequence of steps to run inside that VM.
    • actions/checkout\@v3: This action fetches your repository’s files so the runner can see them.
    • actions/setup-node\@v3: Installs Node.js so you can run npm commands.
    • npm install: Installs dependencies listed in package.json, including Playwright itself.
    • npx playwright install: Downloads browser binaries (Chromium, Firefox, WebKit) so tests can run.
    • npx playwright test: Executes all tests under tests/. By default, Playwright runs tests in headless mode across the configured browsers.

Save this file. Once you commit it, GitHub Actions will detect the new workflow definition.

Step 4: Commit & Push Your Changes

With the workflow defined, we need to push everything back to GitHub so the CI pipeline can take over:

  1. Stage all changes (including test-workflow.yml):
git add .
  1. Commit with a clear message:
git commit -m "Add GitHub Actions workflow to run Playwright tests"
  1. Push to the main branch:
git push origin main

Once the push completes, navigate to your GitHub repository.

Step 5: Verify the CI Pipeline in GitHub Actions

  1. In your GitHub repo, click the Actions tab.
  2. You should see a workflow run titled “Run Playwright Tests” triggered by your recent push.
  3. Click on that workflow run, and you’ll see real-time logs:
  • Checkout repository
  • Setup Node.js
  • Install npm dependencies
  • Install Playwright Browsers
  • Run Playwright Tests

If everything is configured correctly, you’ll see green checkmarks next to each step, and the final step “Run Playwright Tests” will say something like “2 tests passed” (or however many example specs you have). If a test fails, that step will turn red, and GitHub will indicate an error—letting the team know right away that something broke.

What Happens on Future Pushes or Pull Requests?

With the workflow file in place, every push or pull request to the main branch triggers this job. In practice:

  1. Developer or QA Engineer writes a new Playwright test (e.g., tests/login.spec.ts) locally.
  2. They stage & commit the new test file, then push to main.
  3. GitHub Actions picks up the change, spins up a fresh Ubuntu VM, checks out the code, installs Node.js, installs dependencies, adds browsers, and finally runs npx playwright test.
  4. If the new test passes alongside existing tests, you’ll see green checks in GitHub Actions. If anything fails, the workflow stops at the failing step, and the team is notified immediately.

This workflow enforces that no one can merge code into main without passing the entire Playwright test suite. As your test count grows—5 tests, 10 tests, or 50 tests—Playwright simply runs them all in sequence. QA Engineers can focus on writing reliable tests, secure in the knowledge that CI will catch regressions.

Key Benefits of Integrating Playwright Into CI

  • Automated Test Runs on Every Change
    Ensures each commit or pull request is validated, catching issues before they linger.
  • Immediate Feedback
    Developers and QA instantly see pass/fail results in the Actions tab—no waiting for manual verification.
  • Improved Code Quality & Reduced Regression
    As your application evolves, your test suite evolves in lockstep, preventing old bugs from resurfacing.
  • Scalable Test Suite
    New tests “just drop in.” Whether you have 2 tests or 200, the same CI pipeline runs them all.
  • Centralized Visibility
    Anyone on the team—DevOps, QA, or Development—can inspect the workflow logs and debug failures quickly.

Tips for a Smooth CI Experience

  1. Keep Workflow YAML Lean
    If you add more jobs later (linting, building, deploying), break them into separate workflow files. Small, focused .yml files are easier to maintain.
  2. Lock Node.js & Playwright Versions
    In actions/setup-node@v3, specify an exact node-version (e.g., 18.16.0) if you want to avoid unexpected changes whenever a new LTS is released. Similarly, pin your Playwright version in package.json (e.g., "@playwright/test": "1.40.0").
  3. Cache Dependencies (Advanced)
    Once you have many npm packages, consider caching node_modules to speed up npm install. You can use actions/cache to cache ~/.npm or node_modules.
  4. Artifacts & Test Reports
    By default, Playwright generates HTML test reports. To make debugging easier, you can save those HTML reports as workflow artifacts so you can download them from GitHub Actions.

    For example, add a step after npx playwright test:

    - name: Upload Playwright Report
  uses: actions/upload-artifact@v3
  with:
    name: playwright-report
    path: playwright-report/

    This way, you can click “Artifacts” in the Actions run and download the full HTML report.

  5. Branch Protections
    Enable branch protection on main so that every pull request must have a passing CI run before merging. This enforces the rule that “all Playwright tests must pass” before code hits production.

Video Tutorial

Watch the full video tutorial: See a step-by-step demonstration of setting up Playwright tests with GitHub Actions.
Watch on YouTube

Conclusion

By following these steps, you’ve built a basic—but powerful—CI pipeline that automatically runs Playwright tests whenever code is pushed or a pull request is opened. The flow looks like this:

Developer or QA Engineer: Write or update Playwright test locally 
      ↓
git add + git commit + git push
      ↓
GitHub Actions: 
  • Checkout code 
  • Setup Node.js 
  • npm install (Playwright + dependencies)
  • npx playwright install (browser binaries) 
  • npx playwright test
      ↓
GitHub Actions UI: Green check if all tests pass, or red X if any fail

This approach enforces high-quality test coverage, reduces regression risk, and ensures that new tests become part of the shared suite instantly. As your project grows, you can expand this CI pipeline to include:

  • Linting & Formatting (ESLint, Prettier)
  • API Contract Checks (e.g., using Postman/Newman or Pact)
  • Accessibility Audits (e.g., axe-playwright)
  • Visual Regression Tests (e.g., using Playwright’s built-in snapshot functionality)
  • Deployment to Staging (CD)

But the core principle remains: push code → automated build/test → immediate feedback. By integrating Playwright into GitHub Actions, QA Engineers and developers can confidently collaborate on a stable, tested codebase. Happy testing!

Back to Blog