How to Run Playwright Tests in Github Actions

In modern software development, automation testing plays a crucial role in delivering high-quality applications faster. That’s where Playwright and GitHub Actions come in.

Playwright is a powerful end-to-end testing framework that allows developers to test web applications across different browsers such as Chromium, Firefox, and WebKit. On the other hand, GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that helps automate workflows directly within your GitHub repository.

When you combine Playwright with GitHub Actions, you get the ability to run automated browser tests every time code is pushed or a pull request is created. This ensures bugs are caught early, feedback is faster, and your development workflow becomes more reliable.

In this guide, we’ll walk through the step-by-step process of setting up Playwright tests in GitHub Actions so you can seamlessly integrate testing into your CI/CD pipeline.

Why Use Playwright with GitHub Actions?

Running Playwright tests in GitHub Actions provides several benefits:

• Automated browser testing on every commit or pull request, ensuring code quality without manual intervention.
• Cross-browser support with Chromium, Firefox, and WebKit, so your application is tested in real-world environments.
• Cloud execution, meaning you don’t need to maintain your own testing infrastructure.
• Detailed reporting and logs directly in the GitHub UI, making it easier to debug issues and track test performance.

By integrating Playwright with GitHub Actions, you set up a robust CI/CD testing pipeline that keeps your application stable and production-ready.

Prerequisites

Before setting up Playwright tests in GitHub Actions, make sure you have the following installed and ready:

• Node.js (LTS version, 14+): Playwright requires Node.js v14 or higher to run smoothly.
• npm: Comes bundled with Node.js and will be used to install dependencies.
• GitHub account: You’ll need a free GitHub account to create repositories and use GitHub Actions.
• Git is installed: Ensure that Git is installed on your machine so you can push code to your GitHub repository. If not, you can download git and install it on your machine.
• VS Code: Make sure Visual Studio Code (VS Code) is installed on your local machine. It will be your main code editor to write and run Playwright tests. You can download it here.
• Playwright: Install it in your project using the command:

npm init playwright@latest

npm init playwright@latest

If you’re new to Playwright, check out our beginner-friendly Playwright installation guide for a complete step-by-step setup with VS Code.

Having these prerequisites in place ensures you can run tests both locally and in the CI environment without issues.

Step 1: Local Setup

Before integrating Playwright with GitHub Actions, it’s important to confirm everything works on your local machine.

1. Verify Node.js and npm installation

Run the following commands to check if Node.js and npm are installed:

node -v
npm -v

node -v
npm -v

If you don’t see version numbers, install the latest Node.js LTS from nodejs.org.

2. Install Playwright

Initialize Playwright in your project with:

npm init playwright@latest

npm init playwright@latest

This command sets up Playwright with the required configuration files and downloads browser binaries.

3. Run Playwright tests locally

To ensure everything is set up correctly, run:

npx playwright test

npx playwright test

If the tests run successfully, you’re ready to move on to setting up GitHub Actions.

Step 2: Initialize Git and Push Your Project to GitHub

In this step, we will use Visual Studio Code (VS Code) to run all Git commands from its built-in terminal.

Follow these steps to push your Playwright project to GitHub:

1. Open Your Project in VS Code

Launch VS Code.

Go to File → Open Folder and select your Playwright project folder.

Open the Terminal inside VS Code by pressing Ctrl + ` (backtick) or navigating to View → Terminal.

2. Verify Git is installed

Run the command given below in the terminal to verify git is installed in your system.

git --version

git --version

3. Configure your Git identity (one-time)

You need to configure your git identity by providing your git name and email.

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

4. Add a Sensible .gitignore

When you push your project to GitHub, you don’t want to include every single file from your local machine. Some files are auto-generated, temporary, or only useful on your computer; they don’t belong in your repository.

That’s where a .gitignore file comes in. It tells Git which files and folders to ignore so they won’t be tracked or pushed to GitHub.

For a Playwright project (Node.js-based), a sensible .gitignore usually includes things like:

# Playwright
node_modules/
/test-results/
/playwright-report/
/blob-report/
/playwright/.cache/
/tests-examples/

# Playwright
node_modules/
/test-results/
/playwright-report/
/blob-report/
/playwright/.cache/
/tests-examples/

Steps to add .gitignore:

• In VS Code, create a new file named .gitignore in the root of your project.
• Copy the example above into the file.
• Save the file.

Now, any files or folders listed in .gitignore will not show up in your commits.

5. Initialize a Git repository

Navigate to your project’s root directory in the terminal, then run the following commands to initialize Git and check its status.

git init
git status

git init
git status

6. Add All Files to Git:

Now that Git has been initialized in your project, the next step is to add your project files to the staging area. The staging area is like a “holding space” where Git tracks the files you want to include in your next commit.

To add all files in your project (including your .gitignore file), run the following command in your VS Code terminal:

git add .

git add .

After running this, all files that are not ignored by .gitignore will be staged for commit.

7. Commit Your Project

git commit -m "Initial commit - Playwright project setup"

git commit -m "Initial commit - Playwright project setup"

This saves your project files in the local repository.

8. Create a New Repository on GitHub

• Go to GitHub and sign in.
• Click the + icon in the top right → New repository.

• Give it a name (e.g., playwright-tests) and set it to public or private as needed.
• Click Create repository.

• You will be redirected to the Repository Quick setup guide page.

9. Link Your Local Project to GitHub

From GitHub’s Repository Quick setup guide page, copy the repository’s HTTPS URL

Run the following command in VS Code terminal (replace the URL with yours):

git remote add origin https://github.com/your-username/playwright-tests.git

git remote add origin https://github.com/your-username/playwright-tests.git

10. Push Your Code to GitHub

git branch -M main
git push -u origin main

git branch -M main
git push -u origin main

This pushes your local project to the GitHub repository.

11. Verify the Push

• Refresh your GitHub repository page.
• You should now see all your project files uploaded successfully.

Now your project is safely stored on GitHub, and you’re ready to configure GitHub Actions for running Playwright tests.

Step 3: Create a GitHub Actions Workflow on GitHub

To run Playwright tests automatically, we need to create a GitHub Actions workflow. A workflow is a YAML file stored inside the .github/workflows/ folder of your repository. It tells GitHub when to run your tests, which environment to use, and the exact steps to follow.

Instead of creating this file in VS Code, we will create it directly on GitHub:

• Open your GitHub repository in the browser.
• Make sure you are in the root directory of your project (e.g., playwright-tests).
• Click on the Add file → Create new file button.

• In the file name box, type:

.github/workflows/playwright.yml

.github/workflows/playwright.yml

This automatically places the file inside the right folder structure.

• Paste the following workflow configuration into the editor:

name: Playwright Tests

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm install

      - name: Install Playwright Browsers
        run: npx playwright install --with-deps

      - name: Run Playwright tests
        run: npx playwright test

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

name: Playwright Tests

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm install

      - name: Install Playwright Browsers
        run: npx playwright install --with-deps

      - name: Run Playwright tests
        run: npx playwright test

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

• Click the “Commit changes” button to save your changes.

What This Workflow Does

• Triggers: Runs whenever you push code or open a pull request on the main branch.
• Environment: Uses Ubuntu with Node.js 18.
• Steps:
  • Check out your repository.
  • Install Node.js and dependencies.
  • Install Playwright browsers.
  • Run Playwright tests.
  • Upload the HTML report as an artifact.

Once you commit this file, go to your repository’s Actions tab. You’ll see the workflow running automatically every time you push or make a pull request.

Step 4: Viewing Test Results in GitHub Actions

Once your workflow runs successfully, you can access Playwright test results from GitHub Actions.

Access the Workflow Results

• Go to your GitHub repository.
• Click the Actions tab.
• Select the latest workflow run.
• Within the run, you will see logs for each step (e.g., checkout, install, run tests, etc.).

If tests fail, GitHub will clearly mark which ones failed.

Download Playwright HTML Report from Artifacts

Since we added the upload-artifact step in the workflow, the Playwright HTML report is saved as an artifact.

To download it:

• In the workflow run summary, scroll to the Artifacts section (at the bottom of the page).
• Click on playwright-report to download the ZIP file.

• Extract the ZIP file on your local machine.
• Inside the folder, open index.html in your browser.
  • This gives you the interactive Playwright test report.

Additional Tips and Best Practices

When setting up Playwright tests with GitHub Actions, here are some additional tips to improve your CI/CD workflow:

1. Running Tests in Parallel (Sharding)

Playwright supports test sharding, which allows you to split tests across multiple jobs to speed up execution.

strategy:
  matrix:
    shardIndex: [1, 2]
  fail-fast: false

steps:
  - name: Run tests in parallel
    run: npx playwright test --shard=${{ matrix.shardIndex }}/2

strategy:
  matrix:
    shardIndex: [1, 2]
  fail-fast: false

steps:
  - name: Run tests in parallel
    run: npx playwright test --shard=${{ matrix.shardIndex }}/2

This example runs tests in two shards (splits). You can increase the number of shards based on your project size.

2. Running on Multiple Operating Systems

To ensure cross-platform compatibility, you can configure your workflow to run tests on Ubuntu, Windows, and macOS.

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]

runs-on: ${{ matrix.os }}

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]

runs-on: ${{ matrix.os }}

This ensures your app works consistently across different environments.

3. Using Environment Variables

You can pass secrets or configuration values (like API keys, credentials, or test URLs) using GitHub secrets.

env:
  BASE_URL: ${{ secrets.BASE_URL }}

env:
  BASE_URL: ${{ secrets.BASE_URL }}

Inside Playwright, you can use:

test('example', async ({ page }) => {
  await page.goto(process.env.BASE_URL);
});

test('example', async ({ page }) => {
  await page.goto(process.env.BASE_URL);
});

4. Debugging with Traces and Artifacts

Playwright provides trace files and videos to debug failing tests. Enable them in your config:

use: {
  trace: 'on-first-retry',
  video: 'retain-on-failure',
}

use: {
  trace: 'on-first-retry',
  video: 'retain-on-failure',
}

Artifacts (like HTML reports, traces, and videos) are automatically available in the GitHub Actions workflow under Artifacts. This helps you debug test failures quickly.

Resources & Further Reading

Here are some useful resources to deepen your understanding:

• Playwright Continuous Integration (CI) Documentation
• GitHub Actions Documentation
• Playwright Trace Viewer Guide

Final Words

Setting up Playwright with GitHub is a powerful way to streamline your test automation workflow. By committing your project to GitHub and configuring GitHub Actions, you can automatically run tests on every push or pull request. This ensures faster feedback, more reliable builds, and consistent results across different environments.

With best practices like adding a .gitignore, creating a clean Playwright workflow file, running tests in parallel, and testing across multiple operating systems, your team can achieve true CI/CD efficiency. You also benefit from detailed reports, debugging with traces, and easy access to artifacts directly from the Actions tab.

If you follow the steps in this guide, you’ll have a fully automated Playwright CI/CD pipeline on GitHub, helping you deliver quality software faster and with greater confidence.

Aravind

Hi, I’m Aravind — a seasoned Automation Test Engineer with over 17 years of hands-on experience in the software testing industry. I specialize in tech troubleshooting and tools like Selenium, Playwright, Appium, JMeter, and Excel automation. Through this blog, I share practical tutorials, expert tips, and real-world insights to help testers and developers improve their automation skills.In addition to software testing, I also explore tech trends and user-focused topics, including Snapchat guides, codeless test automation, and more.