tamash-playwright

tamash-playwright is a plug and play self-healing solution for any Playwright test framework. All you need to do is install the package, update your AI API key details, and import test from tamash-playwright.

That's it. No code changes required if you're following standard Playwright best practices.

Why you need this

Websites change often. A button gets renamed or moved, and your test can't find it anymore — even though the app still works fine for real users. Normally, that just means a broken test.

tamash-playwright fixes this automatically. When a test can't find an element, it asks an AI model to find it on the current page and tries again. If it succeeds, your test keeps going. If not, it fails normally, just like before.

Want to see it working before you set it up yourself? Clone the sample repo — github.com/qtpsudhakarproducts/tamash-playwright-typescript-playwright — a full worked example with both a plain-locator test and a Page Object Model test, an intentionally broken selector, and step-by-step setup instructions.

Looking for the complete reference — caching, apply-heals, sharded-CI and PR automation, every env var and CLI flag? See usage.md.

Here are the detailed steps to use this package.

Step 1: Install it

npm install tamash-playwright

You also need Playwright's own test package, if you don't already have it:

npm install -D @playwright/test

Step 2: Connect an AI model

tamash-playwright needs an AI model to decide where a broken element actually went. Pick one of Ollama, OpenAI, Anthropic (Claude), or Google Gemini, and give it an API key — or, if you don't have an API key but do have a Claude or GitHub Copilot subscription, use that instead (see below).

Create a file named .env in your project folder:

# Master on/off switch. Leave this as true, or remove the line entirely.
HEALER_ENABLED=true

# Pick one: ollama | openai | anthropic | gemini | claude-subscription | copilot-subscription
HEALER_PROVIDER=ollama

# --- Ollama Cloud (https://ollama.com) ---
OLLAMA_MODEL=gpt-oss:120b
OLLAMA_API_KEY=

# --- OpenAI ---
# OPENAI_MODEL=gpt-4.1-mini
# OPENAI_API_KEY=

# --- Anthropic (Claude) ---
# ANTHROPIC_MODEL=claude-haiku-4-5
# ANTHROPIC_API_KEY=

# --- Google Gemini ---
# GEMINI_MODEL=
# GEMINI_API_KEY=

# --- Claude subscription (no API key — uses your Claude subscription) ---
# CLAUDE_SUBSCRIPTION_MODEL=haiku
# CLAUDE_CODE_OAUTH_TOKEN=

# --- GitHub Copilot subscription (no API key — uses your Copilot subscription/free tier) ---
# COPILOT_SUBSCRIPTION_MODEL=mai-code-1-flash-picker

Just fill in the API key and model for whichever one you want to use, and leave the rest as-is (or delete them).

Getting a free Ollama key (fastest way to get started)

Ollama Cloud is a quick, free way to get an API key without signing up for OpenAI/Anthropic/Gemini billing.

1. Go to ollama.com and create an account.
2. Once signed in, go to ollama.com/settings/keys.
3. Create a new API key and copy it.
4. Paste it into your .env file:

HEALER_ENABLED=true
HEALER_PROVIDER=ollama
OLLAMA_MODEL=gpt-oss:120b
OLLAMA_API_KEY=paste_your_key_here

That's all you need — no other variables required.

Using your Claude or GitHub Copilot subscription instead of an API key

If you don't have an API key issued to you but do have a personal Claude (Pro/Max/Team/Enterprise) or GitHub Copilot subscription (including the free tier), you can use that instead — no billing setup, no key to paste anywhere.

Claude subscription — works both locally and unattended in CI:

npm install -g @anthropic-ai/claude-code   # the CLI itself — needed so `claude login` exists to run.
                                            # @anthropic-ai/claude-agent-sdk (below) bundles its own
                                            # copy of the Claude Code binary too, but only for its own
                                            # internal use — it exposes no `claude` command of its own,
                                            # so this separate install is still required for the login
                                            # step below.
npm install @anthropic-ai/claude-agent-sdk # the SDK — what tamash-playwright actually calls
claude login                               # one-time, locally

HEALER_PROVIDER=claude-subscription
CLAUDE_SUBSCRIPTION_MODEL=haiku

For CI, generate a long-lived token once (claude setup-token) and set it as a secret instead of logging in interactively:

CLAUDE_CODE_OAUTH_TOKEN=the-token-you-copied

GitHub Copilot subscription — works locally, and unattended in GitHub Actions specifically:

npm install -g @github/copilot   # the CLI itself — needed so `copilot` exists to sign in with
npm install @github/copilot-sdk  # the SDK — what tamash-playwright actually calls (wraps the CLI,
                                  # doesn't replace it, so both installs above are required)
copilot                          # sign in once, locally

HEALER_PROVIDER=copilot-subscription
COPILOT_SUBSCRIPTION_MODEL=mai-code-1-flash-picker

In a GitHub Actions workflow, no secret is needed at all if the repo's owning account/org has Copilot enabled — just grant the job permission to use it:

permissions:
  copilot-requests: write

Gotcha, confirmed by real testing, not just docs: this only works if Copilot is enabled for whoever owns the repo — an organization, if that's who the repo belongs to. A personal Copilot subscription on your own account does not carry over to a separate organization's repos, even one you administer yourself; organizations need their own Copilot enablement (Business/Enterprise plan, or an explicit org policy), which is a different thing from an individual plan. If the job fails with Authorization error, you may need to run /login despite the permission being set correctly, this is almost certainly why.

The fix: use a personal-account PAT instead of the ambient token, so the request explicitly carries your own subscription regardless of which org's repo the workflow runs in:

1. Create a fine-grained personal access token: Resource owner = your personal account (not the org), Repository access = Public Repositories (read-only) is enough if the repo is public, Account permissions → Copilot Requests = Read.
2. Add it as a repo secret — any name works, but COPILOT_GITHUB_TOKEN is worth using specifically, since that's the exact env var the Copilot SDK checks ahead of GITHUB_TOKEN in its own auth precedence:

   env:
     COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}

Outside GitHub Actions entirely, the same PAT approach applies — set GITHUB_TOKEN (or COPILOT_GITHUB_TOKEN) to a personal access token with the "Copilot Requests" scope.

One thing worth knowing: only Claude and Copilot support this "subscription, no API key, works in CI too" combination — a ChatGPT or Google AI subscription can back local runs the same way (via those vendors' own CLIs), but neither vendor currently offers a way to use that subscription unattended in CI, so CI there still needs a plain API key (the existing openai/gemini providers above).

Important: set actionTimeout in your playwright.config.ts

By default, Playwright lets a broken locator retry silently for your entire test timeout before it ever throws an error — which means self-healing never gets a turn at all, since it only kicks in once an action actually fails. Set actionTimeout to something well below your test timeout so a broken locator fails fast, leaving real time for healing to run:

export default defineConfig({
  timeout: 60000, // your overall test timeout
  use: {
    actionTimeout: 8000, // must be comfortably less than the test timeout above
  },
});

Without this, healing attempts will show stage=no_snapshot in the console and never recover anything — not because healing failed, but because it never had time to run before the whole test was torn down.

Step 3: Check your setup

Run the built-in doctor command to confirm everything's wired up correctly before you rely on it:

npx tamash-playwright doctor

It checks:

1. AI connectivity — confirms HEALER_ENABLED/HEALER_PROVIDER are set correctly and actually calls your configured provider to make sure the API key and model work.
2. actionTimeout configuration — checks your playwright.config.ts for an actionTimeout set well below your test timeout (see above); flags it if missing or too close to the test timeout, since that silently starves self-healing of any time to run.
3. Vision capability — whether your configured model is expected to support the screenshot-based fallback (see below), based on its name.
4. Missing .describe() labels — scans your test files (tests/ by default, or pass --dir <path>) for locators that don't have a .describe('...') label, and flags the ones most worth fixing (raw CSS/XPath selectors first).
5. Locators written directly in test files — flags any locator defined inline in a test rather than inside a Page Object class, which is a Playwright best practice regardless of self-healing: it keeps tests readable and means a UI change only needs a fix in one place.

If it finds issues, the fastest fix is to open the project in an AI coding assistant (Claude Code, Cursor, GitHub Copilot, etc.) and ask it to address what it flagged — add .describe() calls, or extract locators into Page Object classes. You can also add a standing rule to that assistant's instructions/skill file (e.g. CLAUDE.md, .cursor/rules, .github/copilot-instructions.md) so it follows both practices automatically on any new test code going forward.

Step 4: Use it in your tests

Change one line at the top of your test file — everything else about how you write tests stays exactly the same:

// Before
import { test, expect } from '@playwright/test';

// After
import { test, expect } from 'tamash-playwright';

That's it. Write your tests as normal:

import { test, expect } from 'tamash-playwright';

test('logs in', async ({ page }) => {
  await page.goto('/');
  const txtUserName = page.locator('input[name="username"]').describe('User Name Textbox');
  await txtUserName.fill('testadmin');

  const txtPassword = page.locator('input[placeholder="Password"]').describe('Password Textbox');
  await txtPassword.fill('secret');

  const btnLogin = page.locator('button[type="submit"]').describe('Login Button');
  await btnLogin.click();

  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
});

A quick tip for better results

If you're using plain CSS selectors (like page.locator('input[name="username"]')) rather than Playwright's more descriptive locators (getByRole, getByPlaceholder, etc.), it helps to add a short, human-readable label so the healer knows what it's actually looking for. Chain .describe('...') right onto the locator:

test('login test using CSS Selectors', async ({ page }) => {
  await page.goto('https://example.com/auth/login');

  const txtUserName = page.locator('input[name="username"]').describe('User Name Textbox');
  await txtUserName.fill('testadmin');

  const txtPassword = page.locator('input[placeholder="Password"]').describe('Password Textbox');
  await txtPassword.fill('secret');

  const btnLogin = page.locator('button[type="submit"]').describe('Login Button');
  await btnLogin.click();

  await expect(page.locator('h6')).toHaveText('Dashboard');
});

This step is optional, but recommended — without it, the healer has to guess purely from a broken CSS selector, which gives it a lot less to work with.

Local vs CI, at a glance

Everything below applies identically in both places — same package, same behavior — but a few things are worth knowing up front before you get to the details:

| | Locally | In CI | | --- | --- | --- | | Healing | Runs automatically on every npx playwright test, using the .env file from Step 2. | Runs automatically the same way — set the same variables as CI secrets/environment variables on your test job instead of a .env file (there's a real example in Running apply-heals in CI). | | Caching (below) | Persists on disk across every run — a real, ongoing saving the longer you keep working. | Only helps within one run — most runners start from a fresh checkout each time, so it doesn't carry over between separate CI runs. apply-heals landing the real fix is what actually stops repeat AI calls in CI, not the cache. | | apply-heals (below) | Run manually whenever you want, preview with --dry-run, review the diff yourself, commit when ready. | Runs automatically after your test job and opens a PR for review — nothing ever auto-commits to your branch. | | Provider choice | Any provider works, including claude-subscription/copilot-subscription off a personal subscription with no API key. | Only ollama/openai/anthropic/gemini (a real API key), claude-subscription (a CLAUDE_CODE_OAUTH_TOKEN), or copilot-subscription on GitHub Actions actually run unattended — a claude-subscription/copilot-subscription config that relies on a local interactive login won't authenticate in CI. See above. |

What else it heals — no extra setup needed

Beyond a single broken click/fill/getByRole on the main page, all of this works automatically once you've done Steps 1–2:

• Popups and extra tabs. A page opened via context.newPage(), window.open, or a target="_blank" link is just as healing-aware as your main page — no manual wrapping needed.
• Elements inside <iframe>s. page.frameLocator('#my-iframe') and anything chained off it heals the same way, scoped correctly to the iframe's own document.
• Most of the Playwright API surface, not just clicks and fills — check, selectOption, dragTo, dispatchEvent, read methods like textContent/getAttribute/isChecked, screenshot, and more. Methods that can't be safely healed by guessing a replacement element (dragTo, drop) are still reported honestly on failure, they're just never silently retried with a different element.

When there's no name to match: finding elements by structure

Sometimes the broken element has no useful identity of its own — a plain <input> with no name, no working placeholder, and a label that's visually right next to it but never actually linked (no <label for>, no aria-labelledby). A human finds it instantly by sight; matching purely on accessible name has nothing to grab onto.

For exactly these cases, tamash-playwright reads a structural map of the whole page — not just a flat list of named elements — so the AI can point at the exact element even when it has no name of its own. Once it has that, a separate step (no extra AI call) works out the most stable way to describe it for next time:

• If the element has real identity — an id, test id, accessible role and name, label, or placeholder — that's used directly.
• If not, but a label sits right next to it in the page's own structure, the fix anchors on that nearby text instead — and only after confirming it genuinely points at the same element, not just one that happens to match.
• If neither applies, it falls back to whatever Playwright's own locator-generation logic can produce, even a positional one — but flags it for review rather than treating it as fully trusted (see below), since a selector that depends on element order can silently point at the wrong thing later if the page changes.

You don't configure any of this — it happens automatically, and every candidate is verified against the live page (real DOM identity, not just "a match was found") before anything gets used.

When a fix needs a second look

Not every healed selector is equally durable. One with a real id, test id, or accessible name is about as solid as anything a human would write by hand. One that only had a nearby label or a positional fallback to work with is correct right now, but worth a glance before you fully rely on it — the page could change in a way that fools it later.

tamash-playwright tells you which is which — look for needsReview=yes in the console line, a self-heal-needs-review annotation in the HTML report, or a [NEEDS REVIEW] tag in apply-heals's output (see below). Nothing is blocked or held back because of it; it's a hint about where to look first, not a gate.

When text alone isn't enough: vision fallback

Sometimes an element has nothing useful to match on by text — an icon-only button with no label, or several visually distinct elements that all look identical in the accessibility tree. If your configured model supports image input (e.g. gpt-4o, claude-haiku-4-5, gemini-3.6-flash), tamash-playwright automatically falls back to a screenshot-based search after the normal text-based attempt fails — no separate setup, it just uses the same provider and API key from Step 2. Run npx tamash-playwright doctor to check whether your configured model is expected to support this.

Not paying for the same heal twice

Once a locator heals successfully, tamash-playwright remembers the fix in .tamash-playwright/heals.jsonl — the same file apply-heals reads (see below). The next time that exact locator breaks the same way, it tries the previously-confirmed selector first, with no ARIA snapshot and no AI call. Only if that no longer works (the page changed again) does it fall through to a fresh snapshot-and-AI-call, exactly as before — so there's no correctness risk in trying the cached selector, only a cost/time saving when it still works.

Locally, this is a real, ongoing saving: .tamash-playwright/heals.jsonl lives on your disk and persists across every npx playwright test you run, for as long as you keep working on that checkout — the same broken locator only ever costs one AI call, no matter how many times you re-run your tests afterward.

In CI, this only helps within one run, not across separate ones — most CI runners start from a fresh checkout every time, so .tamash-playwright/ (gitignored, never committed) doesn't carry over from yesterday's run to today's. What actually eliminates repeat AI calls in CI is apply-heals merging the real fix into your source — once that lands, the locator isn't broken anymore and healing never needs to run for it again. The cache still earns its keep within a single run, though: if the same broken locator shows up in several tests in one run (a shared Page Object method, say), only the first one pays for a fresh AI call — every other occurrence in that same run reuses it for free. You'll see it in the console line as provider=cache with no token count, instead of the real provider name:

[self-healer] tests/sampletest.spec.ts:13 — locator.fill "User Name Textbox (placeholder "xyz")" -> HEALED [provider=cache, vision=no, actionRecovery=no, suggested="role:textbox:Username"] — locator.fill: Timeout 8000ms exceeded.

A cache hit doesn't re-log itself (there's nothing new to record), so the log doesn't grow just from repeated confirmations of the same already-known fix — it only grows when a new AI call produces a fresh suggestion. If the original heal was flagged needsReview (see above), the cached replay keeps flagging it on every run that reuses it, not just the first — a fragile fix doesn't quietly stop being worth a look just because it's been cached.

Making a heal permanent: apply-heals

Runtime healing (including the caching above) never touches your source code — the original locator stays broken in your test file or Page Object forever, healed at runtime on every run, until you fix it yourself. apply-heals closes that loop: it rewrites the original broken locator to the selector that actually worked, so the next run doesn't need healing — from cache or otherwise — at all.

npx playwright test          # heals at runtime, and records what it healed
npx tamash-playwright apply-heals --dry-run   # preview the source changes it would make
npx tamash-playwright apply-heals             # write them

[FIX] src/pages/loginpage.ts:11
  - .locator('input[name="username1"]')
  + .getByRole("textbox", { name: "Username" })

1 fix(es) applied to 1 file(s), 0 skipped.
Review the changes (e.g. `git diff`) before committing.

A fix derived from a nearby label or a positional fallback (see above) is marked the same way as everywhere else:

[FIX] [NEEDS REVIEW] tests/employee-id.spec.ts:31
  - .getByPlaceholder('Employee')
  + .locator('div').filter({ hasText: 'Employee Id' }).getByRole('textbox')
  ⚠ No stable identity of its own — durable selector anchors on nearby text instead. Please verify this still targets the right element if the page layout changes.

A few things worth knowing:

• Nothing is applied automatically. apply-heals is a separate, deliberate command — a test run never edits your source on its own.
• Only real selector fixes are eligible. A heal only qualifies if it's text/ARIA-based (not just an ephemeral visual-match-only fallback that never resolved to anything reusable — see below) and the locator itself was actually replaced (not an action-recovery heal, where the original locator was already correct and only the action needed help).
• Only the matched call is touched. .describe('...') and everything else on the line is left exactly as written; only the .locator(...)/.getByRole(...)/etc. call itself is replaced.
• Always review the diff before committing — this rewrites your source files, so treat it like any other automated code change: check git diff, run your tests again, and commit deliberately.

Proving a fix actually works: verify-heals.cjs

Every real (non---dry-run) apply-heals run also writes .tamash-playwright/verify-heals.cjs — a ready-to-run script that re-runs exactly the tests affected by that run, with healing turned off:

node .tamash-playwright/verify-heals.cjs

A pass proves the rewritten selectors work on their own — not just "worked while healing was still there to catch a mistake." It's a plain Node script (portable across Windows/macOS/Linux, no shell-specific env var syntax to get wrong) that calls Playwright's own CLI with your existing config, so there's nothing to configure — just run it after apply-heals, locally or as a CI step.

Every run also writes a before/after report to .tamash-playwright/ — apply-heals-report.json (machine-readable) and apply-heals-report.md (human-readable, one section per fix with the exact before/after code). This is what feeds the PR body in the CI pattern below, so a reviewer sees the actual change without digging through logs — worth knowing about even if you only ever run this locally, since it's a persisted record of every fix beyond whatever's still in your scrollback.

Those two filenames always mean "the latest run" — each run overwrites them. Since .tamash-playwright/ is gitignored (never committed), that would otherwise mean a second run erases all trace of the first. To keep a real history, every run also archives a timestamped copy of both reports, plus the raw heals.jsonl that produced them, under .tamash-playwright/history/ — nothing in there is ever overwritten or deleted by a later run, so it's safe to just leave it accumulating, or clean it out yourself whenever you want.

Running apply-heals in CI (sharded or not)

apply-heals never touches git itself — in CI, that means the fix only exists in that job's ephemeral checkout unless something turns it into a real, reviewable change. The recommended shape: a separate job that runs after your test job(s), downloads whatever got healed, and opens a PR rather than pushing straight to a branch.

If your suite runs sharded (--shard=N/M across multiple CI machines), each shard only sees its own slice of what got healed — .tamash-playwright/heals.jsonl ends up fragmented, one partial file per shard. --logs-dir is built for exactly this: point it at a directory containing any number of heals.jsonl files, nested however you like, and it merges all of them before planning fixes (deduplicating by keeping only the newest entry per file:line, so two shards healing the same line is harmless):

npx tamash-playwright apply-heals --logs-dir shard-logs

A GitHub Actions example — each test job uploads its own log as an artifact; a separate job merges them, applies the fixes on a fresh branch, re-runs the suite against just those fixes to prove they actually work, and only then opens a PR (labeled with whether verification passed, either way):

jobs:
  test:
    # ...your existing test job(s), sharded or not — the part that matters here is that healing
    # needs the same variables from Step 2, set as CI secrets/environment variables instead of a
    # local .env file (which won't exist on the runner and shouldn't be committed anyway).
    runs-on: ubuntu-latest
    env:
      HEALER_ENABLED: true
      HEALER_PROVIDER: ollama
      OLLAMA_MODEL: gpt-oss:120b
      OLLAMA_API_KEY: ${{ secrets.OLLAMA_API_KEY }}   # set via `gh secret set OLLAMA_API_KEY`
    steps:
      - run: npx playwright test
      - uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with:
          name: heals-log-${{ strategy.job-index }}
          path: .tamash-playwright/heals.jsonl
          if-no-files-found: ignore

  apply-heals:
    needs: test
    if: ${{ !cancelled() && github.event_name == 'push' }}   # not pull_request — see note below
    runs-on: ubuntu-latest
    # Two pushes close together would otherwise race on the same heal branch/PR — whichever
    # finished last could clobber the other mid-update. Queues instead (never cancels an
    # in-progress run) so each one always starts from a clean, fully-finished state.
    concurrency:
      group: apply-heals-${{ github.ref }}
      cancel-in-progress: false
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: lts/* }
      - run: npm ci

      - uses: actions/download-artifact@v4
        with:
          pattern: heals-log-*
          path: shard-logs
        continue-on-error: true   # no artifact at all when nothing needed healing — the common case
      - run: npx tamash-playwright apply-heals --logs-dir shard-logs

      - name: Check whether any fixes were applied
        id: check
        run: echo "changed=$(git diff --quiet || echo true)" >> "$GITHUB_OUTPUT"

      # apply-heals already wrote .tamash-playwright/verify-heals.cjs — it knows exactly which
      # tests were affected and sets HEALER_ENABLED=false itself, so there's nothing to parse or
      # configure here. A pass proves the *written* fix works standalone — leaving healing on
      # could let a still-broken selector get silently re-healed at runtime again, reporting green
      # without ever proving the applied source fix was actually correct.
      - name: Verify the healed selectors work on their own
        id: verify
        if: steps.check.outputs.changed == 'true'
        run: node .tamash-playwright/verify-heals.cjs
        continue-on-error: true

      # Captured via the step's own id so Compose PR body can link straight to it — otherwise it's
      # uploaded correctly but nobody reviewing the PR would know it exists.
      - name: Upload verification report
        id: upload-verification-report
        if: steps.check.outputs.changed == 'true' && !cancelled()
        uses: actions/upload-artifact@v4
        with:
          name: apply-heals-verification-report
          path: playwright-report/

      # apply-heals already wrote .tamash-playwright/apply-heals-report.md with a before/after per
      # fix — this prepends the verification result so the PR body is one linked story (what
      # broke, what changed, whether it's proven to work) instead of three things to go find.
      - name: Compose PR body
        if: steps.check.outputs.changed == 'true'
        run: |
          {
            echo "Auto-generated by \`tamash-playwright apply-heals\` after self-healing kicked in during CI."
            echo ""
            if [ "${{ steps.verify.outcome }}" = "success" ]; then
              echo "**Verification run (healing disabled): ✅ passed.**"
            else
              echo "**Verification run (healing disabled): ⚠️ FAILED — review carefully before merging.**"
            fi
            echo "[Full test execution report](${{ steps.upload-verification-report.outputs.artifact-url }})"
            echo ""
            cat .tamash-playwright/apply-heals-report.md
          } > .tamash-playwright/pr-body.md

      # branch is suffixed with the ref so two different branches healing at the same time (if
      # your trigger isn't restricted to a single branch) never fight over one physical heal
      # branch — the concurrency group above only serializes runs on the *same* ref.
      - name: Open PR with healed selectors
        if: steps.check.outputs.changed == 'true'
        uses: peter-evans/create-pull-request@v6
        with:
          commit-message: "fix: apply self-healed selectors from CI"
          title: "Apply self-healed selectors on ${{ github.ref_name }} (verification ${{ steps.verify.outcome == 'success' && 'passed' || 'FAILED' }})"
          body-path: .tamash-playwright/pr-body.md
          branch: tamash-playwright/apply-heals-${{ github.ref_name }}
          delete-branch: true

      - name: Fail the job if verification didn't pass
        if: steps.check.outputs.changed == 'true' && steps.verify.outcome != 'success'
        run: exit 1   # PR is still opened above for review — this just keeps CI status honest

One more thing worth flagging if you copy this: .tamash-playwright/ needs to be in your .gitignore. peter-evans/create-pull-request commits whatever differs from HEAD in the working tree — without the ignore, the report/log files themselves would get swept into the PR alongside the actual source fix.

A few choices worth calling out:

• Gated on push, not pull_request. A pull_request run from a fork gets a read-only GITHUB_TOKEN (so it couldn't open a PR anyway), and "open a PR to fix this still-open PR" isn't a sensible flow regardless. Running after merges to main/master avoids both problems.
• The PR is opened either way, verification passed or failed — a failed verification is still worth a human's attention (maybe the fix is right and something else was flaky); it just gets an honest label instead of a silent false-positive. The final step fails the job itself when verification fails, so CI status stays truthful even though the PR still exists for review.
• peter-evans/create-pull-request is a no-op if there's nothing to commit, so the job is safe to run on every push — it only ever opens a PR when there's an actual fix to review, and reuses the same branch/PR on subsequent runs rather than piling up duplicates.

Want a browsable dashboard, not just PR diffs and CI logs? You can add a third job that publishes a combined report — the initial run, what got healed, and the post-fix verification, plus every past run archived and browsable — to GitHub Pages. See the "Publishing a healing dashboard to GitHub Pages" section of usage.md for the full recipe.

Checking what actually happened

Every healing attempt — whether it succeeded or not — shows up in Playwright's own HTML report (npx playwright show-report), no separate report to check:

• An annotation on the test summarizing what happened, e.g. Recovered using ollama:gpt-oss:120b (role:button:Submit) — plus a separate self-heal-needs-review annotation when the fix is the kind worth a second look (see above).
• A JSON attachment with the full detail: which provider was used, whether the vision or action-recovery fallback was involved, the AI's suggested selector, token cost, and — if it didn't heal — which stage it stopped at (e.g. ai_declined, replay_failed).
• Exactly where in your own code the locator was created — a test file or a Page Object class, whichever it really is — so you know which line to go fix even if you never look at the healing report again.

The same detail is also printed to the console as it happens, one line per attempt:

[self-healer] src/pages/loginpage.ts:11 — locator.fill "Username Textbox" -> HEALED [provider=ollama:gpt-oss:120b, vision=no, actionRecovery=no, suggested="role:textbox:Username", 620 tokens (489 input + 131 output)] — locator.fill: Timeout 8000ms exceeded.

License

Free to use, including commercially. The source code may not be copied, modified, redistributed, or resold without prior written permission. See the LICENSE file included in this package for the full terms.

Support

For questions or concerns, contact us at [email protected].