> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stably.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Tests on GitHub

> Run Stably-powered Playwright tests in parallel using GitHub Actions with your existing CI infrastructure.

Stably integrates seamlessly with your existing GitHub Actions workflows. Use Stably's Playwright SDK to unlock AI-powered testing capabilities including auto-heal, AI assertions, and centralized reporting—all while maintaining 100% compatibility with your existing Playwright tests.

## Prerequisites

* A GitHub repository with an existing GitHub Actions workflow (or the ability to create one)
* Node.js 20+ configured in your workflow

## Quick Setup

### 1. Install Stably Playwright SDK

Update your project dependencies to use Stably's Playwright SDK alongside Playwright:

<CodeGroup>
  ```bash npm theme={null}
  npm install --save-dev @playwright/test @stablyai/playwright-test
  ```

  ```bash yarn theme={null}
  yarn add --dev @playwright/test @stablyai/playwright-test
  ```

  ```bash pnpm theme={null}
  pnpm add -D @playwright/test @stablyai/playwright-test
  ```
</CodeGroup>

Commit the updated `package.json` and lock file to your repository.

### 2. Update Test Imports

Replace all imports from `@playwright/test` with `@stablyai/playwright-test` in your test files:

```typescript theme={null}
// Before
import { test, expect } from "@playwright/test";

// After
import { test, expect } from "@stablyai/playwright-test";
```

### 3. Configure GitHub Secrets

Add your Stably API key as a GitHub secret:

1. Get your **Team API Key** from [Stably Settings](https://app.stably.ai/settings?tab=api-key)
2. Go to your repository's `Settings > Secrets and variables > Actions`
3. Create a new secret named `STABLY_API_KEY` with your API key

### 4. Update Your GitHub Actions Workflow

Your workflow remains the same—just ensure the `STABLY_API_KEY` environment variable is set:

```yaml .github/workflows/playwright.yml theme={null}
- name: Run Stably-powered Playwright tests
  run: npx stably test
  env:
    STABLY_API_KEY: ${{ secrets.STABLY_API_KEY }}
    STABLY_PROJECT_ID: ${{ secrets.STABLY_PROJECT_ID }}
```

<Note>
  The Stably CLI is a drop-in extension for Playwright,
  so you continue using any flags you were using with `npx playwright test` with `npx stably test` instead.
</Note>

## Running Tests in Parallel

Stably works with [GitHub Actions matrix strategy](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategymatrix) to run your tests in parallel across multiple containers, reducing overall execution time and providing faster feedback.

### Example: Parallel Execution with Matrix

Here's a complete workflow that runs tests across 4 parallel containers:

```yaml .github/workflows/playwright.yml theme={null}
name: Playwright Tests
on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]

jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shardIndex: [1, 2, 3, 4]
        shardTotal: [4]
    
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      
      - name: Install dependencies
        run: npm ci
      
      - name: Install Playwright browsers
        run: npx stably install --with-deps
      
      - name: Run Playwright tests
        run: npx stably test --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
        env:
          STABLY_API_KEY: ${{ secrets.STABLY_API_KEY }}
          STABLY_PROJECT_ID: ${{ secrets.STABLY_PROJECT_ID }}
```

### How Matrix Parallelization Works

By using GitHub Actions' matrix execution strategy:

* **Multiple containers** are created automatically (4 in the example above)
* **Each container** receives a unique shard of tests to execute
* **Tests run simultaneously** across all containers, reducing total execution time
* **Results are collected** and aggregated in the Stably dashboard

You can adjust the number of parallel jobs by modifying the `shardIndex` and `shardTotal` arrays. For example, to run 8 parallel jobs:

```yaml theme={null}
strategy:
  matrix:
    shardIndex: [1, 2, 3, 4, 5, 6, 7, 8]
    shardTotal: [8]
```

## Add Stably Reporter (Optional)

To integrate with Stably's cloud platform and view test results in the dashboard, configure the reporter in your `playwright.config.ts`:

```typescript playwright.config.ts theme={null}
import { defineConfig } from "@playwright/test";
import { stablyReporter } from "@stablyai/playwright-test";

export default defineConfig({
  reporter: [
    ["list"],
    stablyReporter({ apiKey: process.env.STABLY_API_KEY, projectId: "your_project_id_here" }),
  ],
});
```

In your GitHub Actions workflow, add the environment variables:

```yaml theme={null}
- name: Run Playwright tests
  run: npx stably test
  env:
    STABLY_API_KEY: ${{ secrets.STABLY_API_KEY }}
    STABLY_PROJECT_ID: ${{ secrets.STABLY_PROJECT_ID }}
```

<Note>
  Find your **Project ID** in your project settings on the Stably Dashboard and add it to your GitHub repository secrets.
</Note>

Once configured, view comprehensive results in the [Stably dashboard](https://app.stably.ai):

* **Test execution timeline** showing parallel run progress
* **Screenshots and videos** for failed tests
* **AI-generated failure analysis** and suggested fixes
* **Historical trends** and flakiness detection
* **Detailed logs** from each parallel container

All test results from parallel containers are automatically aggregated into a single unified report, making it easy to review the complete test run regardless of how many shards executed.

## Complete Workflow Examples

<Tabs>
  <Tab title="Basic Setup">
    Minimal configuration for single-threaded execution:

    ```yaml .github/workflows/playwright.yml theme={null}
    name: Playwright Tests
    on:
      push:
        branches: [main]
      pull_request:

    jobs:
      test:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - uses: actions/setup-node@v4
            with:
              node-version: 20
          - run: npm ci
          - run: npx stably install --with-deps
          - run: npx stably test
            env:
              STABLY_API_KEY: ${{ secrets.STABLY_API_KEY }}
              STABLY_PROJECT_ID: ${{ secrets.STABLY_PROJECT_ID }}
    ```
  </Tab>

  <Tab title="Parallel with Artifacts">
    Advanced configuration with test artifacts upload:

    ```yaml .github/workflows/playwright.yml theme={null}
    name: Playwright Tests
    on:
      push:
        branches: [main, master]
      pull_request:

    jobs:
      test:
        timeout-minutes: 60
        runs-on: ubuntu-latest
        strategy:
          fail-fast: false
          matrix:
            shardIndex: [1, 2, 3, 4]
            shardTotal: [4]
        
        steps:
          - uses: actions/checkout@v4
          
          - uses: actions/setup-node@v4
            with:
              node-version: 20

          - name: Install dependencies
            run: npm ci

          - name: Install Playwright browsers
            run: npx stably install --with-deps

          - name: Run Stably-powered Playwright tests
            run: npx stably test --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
            env:
              STABLY_API_KEY: ${{ secrets.STABLY_API_KEY }}
              STABLY_PROJECT_ID: ${{ secrets.STABLY_PROJECT_ID }}

          - name: Upload test artifacts
            uses: actions/upload-artifact@v4
            if: always()
            with:
              name: playwright-report-${{ matrix.shardIndex }}
              path: playwright-report/
              retention-days: 30
    ```
  </Tab>

  <Tab title="Multiple Browsers">
    Run tests across different browsers in parallel:

    ```yaml .github/workflows/playwright.yml theme={null}
    name: Playwright Tests
    on:
      push:
        branches: [main]
      pull_request:

    jobs:
      test:
        timeout-minutes: 60
        runs-on: ubuntu-latest
        strategy:
          fail-fast: false
          matrix:
            browser: [chromium, firefox, webkit]
            shardIndex: [1, 2]
            shardTotal: [2]
        
        steps:
          - uses: actions/checkout@v4
          - uses: actions/setup-node@v4
            with:
              node-version: 20
          - run: npm ci
          - run: npx stably install --with-deps
          - name: Run tests on ${{ matrix.browser }}
            run: npx stably test --project=${{ matrix.browser }} --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
            env:
              STABLY_API_KEY: ${{ secrets.STABLY_API_KEY }}
              STABLY_PROJECT_ID: ${{ secrets.STABLY_PROJECT_ID }}
    ```
  </Tab>

  <Tab title="With Stably Reporter">
    Complete setup with Stably reporter for dashboard integration:

    ```yaml .github/workflows/playwright.yml theme={null}
    name: Playwright Tests
    on:
      push:
        branches: [main, master]
      pull_request:

    jobs:
      test:
        timeout-minutes: 60
        runs-on: ubuntu-latest
        strategy:
          fail-fast: false
          matrix:
            shardIndex: [1, 2, 3, 4]
            shardTotal: [4]
        
        steps:
          - uses: actions/checkout@v4
          
          - uses: actions/setup-node@v4
            with:
              node-version: 20
          
          - name: Install dependencies
            run: npm ci
          
          - name: Install Playwright browsers
            run: npx stably install --with-deps
          
          - name: Run Stably-powered Playwright tests
            run: npx stably test --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
            env:
              STABLY_API_KEY: ${{ secrets.STABLY_API_KEY }}
              STABLY_PROJECT_ID: ${{ secrets.STABLY_PROJECT_ID }}
    ```
  </Tab>
</Tabs>

## Next Steps

* Explore [AI assertions](/stably-sdk/ai-assertions) for intelligent test validation
* Set up [Slack notifications](/integrations/slack) for test results
* Configure [GitHub integration](/integrations/github) for PR comments and status checks