Saola GitHub Agent

Runs in your CI on pull requests. It reviews the PR diff, explores your running app with Playwright, and commits generated e2e specs back onto the same branch.

Setup

1. Add a repository secret: SAOLA_API_TOKEN (from your Saola account).
2. Add a workflow that starts your app, then runs the agent. Copy examples/workflow.yml into .github/workflows/, or use:

name: Saola E2E Agent

on:
  pull_request:
    types: [opened, synchronize]

concurrency:
  group: saola-agent-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  saola-agent:
    runs-on: ubuntu-latest
    env:
      BASE_URL: http://localhost:3000
    permissions:
      contents: write
      pull-requests: write
      checks: write
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}
          fetch-depth: 0

      # Start your app so it is reachable in this job
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm ci
      - run: npm run build
      - run: npm start &
      - run: npx wait-on ${{ env.BASE_URL }}

      - name: Saola GitHub Agent
        run: npx --yes @saola.ai/github-agent@latest run --base-url ${{ env.BASE_URL }} --output-dir e2e/saola
        env:
          SAOLA_API_TOKEN: ${{ secrets.SAOLA_API_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Replace the npm ci / build / start steps with whatever boots your app. Point BASE_URL at that URL.

Permissions

| Permission | Why | | --- | --- | | contents: write | Commit and push generated tests to the PR branch | | pull-requests: write | Post or update the run summary on the PR | | checks: write | Attach check status when applicable |

GITHUB_TOKEN is provided by Actions; you only need to add SAOLA_API_TOKEN.

Options

| Flag | Default | Description | | --- | --- | --- | | --base-url | required | URL of the app under test in the job | | --output-dir | e2e/saola | Where generated Playwright specs are written | | --browser | chromium | chromium, firefox, or webkit | | --max-tests-per-pr | 3 | Cap on tests generated for a single PR | | --dry-run-commit | off | Write files but do not commit or push |

Requirements

• Node.js 20+
• Your app reachable at --base-url before the agent starts