GitHub Actions with Playwright: Automate Browser Testing Like a Pro

Why Playwright?

Playwright is a powerful tool for end-to-end testing in modern browsers (Chromium, Firefox, WebKit). It automates interactions like clicking buttons, filling forms, and validating page content. With GitHub Actions, you can run these tests automatically on every code change!

Example: Auto-Test a Web Page with Playwright

Let’s create a workflow that:

1. Runs Playwright tests on every push to GitHub.

2. Generates a test report.

3. Uploads the report as an artifact for debugging.

Step 1: Set Up Your Playwright Project

1. Initialize a Node.js project:

   npm init -y

2. Install Playwright:

   npm install --save-dev @playwright/test

3. Create a sample test file (e.g., tests/example.spec.js):

   const { test, expect } = require('@playwright/test');
   
   test('Check GitHub title', async ({ page }) => {
     await page.goto('https://github.com');
     await expect(page).toHaveTitle('GitHub: Let’s build from here · GitHub');
   });

4. Run tests locally to verify:

   npx playwright test

Step 2: Create the GitHub Actions Workflow

Create .github/workflows/playwright.yml and add this fully explained configuration:

name: Playwright Tests

on: [push] # Trigger on every push to any branch

jobs:
  test-browsers:
    # Run tests on a GitHub-hosted Ubuntu machine
    runs-on: ubuntu-latest

    # Configure timeouts and retries (optional)
    timeout-minutes: 10
    strategy:
      retry: 1 # Retry failed tests once

    steps:
      # Step 1: Checkout code from the repo
      - name: Checkout repository
        uses: actions/checkout@v4

      # Step 2: Set up Node.js with a specific version
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20' # Playwright works best with Node 18+

      # Step 3: Install dependencies (including Playwright)
      - name: Install dependencies
        run: npm ci # Uses package-lock.json for exact versions

      # Step 4: Install Playwright browsers & system dependencies
      - name: Install Playwright
        run: npx playwright install --with-deps

      # Step 5: Run Playwright tests
      - name: Run tests
        run: npx playwright test

      # Step 6: Upload HTML test report as an artifact (if tests fail)
      - name: Upload test report
        if: failure() # Only upload on failure
        uses: actions/upload-artifact@v4
        with:
          name: playwright-report
          path: playwright-report/

Breaking Down the Workflow File

1. name: Playwright Tests

   • Friendly name for your workflow (visible in the Actions tab).

2. on: [push]

   • Triggers the workflow every time code is pushed to any branch.

3. runs-on: ubuntu-latest

   • Uses a clean Ubuntu virtual machine provided by GitHub.

4. timeout-minutes and retry

   • Prevents hung workflows and retries flaky tests once.

5. Steps Explained:

   • Checkout repository: Copies your code into the workflow environment.

   • Setup Node.js: Installs Node.js v20 (required for Playwright).

   • Install dependencies: Uses npm ci for a faster, secure install.

   • Install Playwright: Installs browsers (Chromium, Firefox, WebKit) and system dependencies (like libraries for headless mode).

   • Run tests: Executes all Playwright tests in the tests/ folder.

   • Upload test report: If tests fail, uploads the playwright-report/ folder as a downloadable artifact for debugging.

What Happens When You Push Code?

1. GitHub spins up a fresh Ubuntu machine.

2. Your code is cloned, Node.js is set up, and dependencies are installed.

3. Playwright downloads browsers (takes 1-2 minutes on first run).

4. Tests run headlessly (no visible browser UI).

5. Results:

   • Pass: Workflow completes with a green checkmark.

   • Fail: Red X appears, and you can download the playwright-report to see screenshots, traces, and error logs.

Bonus: Speed Up Future Runs with Caching

Add this step after Install dependencies to cache Playwright browsers:

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

Real-World Use Cases

• Test login flows, checkout processes, or API calls.

• Run tests across multiple browsers in parallel.

• Integrate with CI/CD pipelines to block broken code from deploying.

Why This Workflow Rocks

• Catch visual regressions: Playwright takes screenshots on failure.

• Test cross-browser compatibility: Run against Chromium, Firefox, and WebKit.

• Debug easily: Download HTML reports with traces and videos.

Final Tip: Check the Playwright GitHub Action docs for advanced configurations like parallel testing or sharding!

(Now go automate those tests—your team will love you for it!) 🚀