Run Playwright AI Agents in CI with GitHub Actions: Auto-Heal Failing Tests (2026)

Running Claude with the Playwright MCP Server on your laptop is great for exploring an app and drafting tests. But the real payoff comes when AI works inside your pipeline: fixing broken tests while you sleep, drafting tests for new features, and opening pull requests for a human to review.

This guide shows how to run Playwright AI agents in GitHub Actions — safely. You will set up a normal test job, add an AI "healer" job that only runs when tests fail, and add guardrails so the agent can never merge code, leak secrets, or run up a surprise bill.

What AI Agents Should (and Shouldn't) Do in CI

Before writing YAML, decide what job the AI actually has. A good rule: AI proposes, humans approve.

Your regular Playwright tests stay exactly as they are: fast, deterministic, and free to run. The AI jobs sit around them and only do work when there is something to fix or build.

The Pipeline Architecture

The setup in this guide has three pieces:

1. Test job — runs npx playwright test on every push and pull request, and uploads the report and traces when something fails.
2. Heal job — runs only if the test job failed. It starts Claude Code with the Playwright MCP Server in headless mode, lets it reproduce and fix the failure, and opens a pull request with the change.
3. Nightly job (optional) — on a schedule, asks the agent to explore a staging flow and draft missing tests as a PR.

You need two things in the repository first:

• An ANTHROPIC_API_KEY secret (Settings → Secrets and variables → Actions).
• A CI-specific MCP config file, so the browser runs headless and isolated.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless", "--isolated"]
    }
  }
}

Step 1: The Normal Test Job

If you already run Playwright in GitHub Actions, this will look familiar (the full basics are in the Playwright GitHub Actions CI/CD guide). The only additions are an id so later jobs can react to failure, and uploading traces for the agent to read:

name: Playwright Tests
on:
  pull_request:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report
          path: |
            playwright-report/
            test-results/

Make sure your playwright.config.ts records traces on failure (trace: 'retain-on-failure' or 'on-first-retry'). Traces are the single most useful input you can give an AI debugger — see the Trace Viewer tutorial.

Step 2: Add an AI Healer Job

Now add a second job to the same workflow. It runs only when test fails, uses Anthropic's official Claude Code GitHub Action, and connects it to the Playwright MCP Server from the config file above:

  heal:
    needs: test
    if: failure() && github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx playwright install --with-deps
      - uses: actions/download-artifact@v4
        with:
          name: playwright-report

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Playwright tests failed on this pull request.
            1. Read the failures in test-results/ and playwright-report/.
            2. Reproduce each failure with the Playwright MCP browser tools.
            3. Decide: is the TEST wrong (changed locator, text, timing)
               or is the APP broken? Only fix tests. Never edit app code.
            4. Run `npx playwright test` to confirm your fix passes.
            5. Write a short summary of each root cause to HEAL_REPORT.md.
          claude_args: |
            --mcp-config .github/mcp-ci.json
            --allowedTools "mcp__playwright,Read,Edit,Write,Bash(npx playwright test:*)"
            --max-turns 40

      - uses: peter-evans/create-pull-request@v7
        with:
          branch: ai-heal/${{ github.head_ref }}
          base: ${{ github.head_ref }}
          title: "AI heal: fix failing Playwright tests"
          body-path: HEAL_REPORT.md
          add-paths: tests/**

A few details matter here:

• The prompt forbids editing app code. A healer that "fixes" a test by hiding a real bug is worse than no healer. Asking it to classify test problem vs app problem first is the most important line in the whole workflow.
• --allowedTools is a whitelist. The agent can use the Playwright MCP tools, edit files, and run Playwright — nothing else. No arbitrary shell commands, no git push.
• The fix arrives as a pull request into your branch, via add-paths: tests/**, so only test files can be included. You review and merge it like any teammate's change.

Using Playwright's Built-in Test Agents

Playwright v1.56+ ships its own planner, generator, and healer agents. You can generate their definitions for Claude Code once, commit them, and let the CI job use them:

npx playwright init-agents --loop=claude
git add .claude/ && git commit -m "chore: add Playwright test agents"

Then shorten the CI prompt to delegate to the healer:

Use the Playwright test healer agent to fix the failing tests.
Only modify files under tests/. Summarize root causes in HEAL_REPORT.md.

This gives you Playwright's tuned healer instructions instead of writing your own, and the agent definitions are versioned in your repo so every run behaves the same.

Step 3 (Optional): Nightly Test Generation

The same pattern can draft new tests. A scheduled workflow asks the agent to explore one staging flow per night and propose tests for anything not yet covered:

on:
  schedule:
    - cron: '0 2 * * 1-5'   # 02:00 UTC, weekdays
  workflow_dispatch:

# ...same setup steps as the heal job...
          prompt: |
            Explore the checkout flow on https://staging.example.com.
            Compare it with tests/checkout/. Write Playwright tests for
            any scenario that is not covered, using role-based locators.
            Run them until they pass. Do not modify existing tests.

Combine this with a saved login session so the agent starts authenticated on staging — the setup is in Playwright MCP Authentication.

Guardrails: Security & Cost

AI in a pipeline needs the same discipline as any other automation with credentials. Use this checklist before turning it on:

1. Never auto-merge. The agent opens PRs; a human approves them.
2. Whitelist tools with --allowedTools. Start narrow and widen only when needed.
3. Cap the work with --max-turns and a job timeout-minutes. A stuck agent should fail fast, not loop for an hour.
4. Only fire on failure (if: failure()). Passing builds should cost nothing.
5. Staging only. Point agents at test environments and test accounts. Consider --allowed-origins on the MCP server to keep the browser on your domains.
6. Secrets stay in GitHub Secrets. Never put API keys or passwords in prompts, config files, or CLAUDE.md.
7. Set a spend limit on your Anthropic API key so a misconfigured workflow can't surprise you.

Measuring Whether It's Worth It

Track three numbers for the first month:

If the wrong-fix rate is high, tighten the prompt and give the agent better context in CLAUDE.md (test conventions, what counts as a real bug). If acceptance is low, the problem is usually brittle tests — the flaky tests fix guide and ARIA snapshots help more than a smarter agent.

Frequently Asked Questions

Meet Your Instructor

Asim Noaman

Senior QA Automation Engineer & AI Testing Specialist

With years of hands-on experience building test automation frameworks for production applications, Asim specializes in combining traditional QA methodologies with cutting-edge AI tools. He has helped teams adopt Playwright and AI-driven testing workflows to ship faster with fewer bugs.

Udemy Instructor Published course author

Playwright + AI Expert Specialized in AI-powered QA

Production Experience Enterprise-grade frameworks

Connect on LinkedIn