Implementing Dynamic Self-Healing Locators with Playwright Fixtures (2026)

// fixtures/healing.ts
import { test as base, expect, Page, Locator } from '@playwright/test';
import { appendHeal } from './heal-ledger';
import { proposeLocator } from './llm-client';

export interface HealOptions {
  // A short, human description of what this locator targets.
  // This becomes the LLM's primary instruction, so make it meaningful.
  intent: string;
  // Hard cap so one broken page cannot trigger dozens of model calls.
  maxHealsPerTest?: number;
}

export interface HealResult {
  original: string;
  healed: string;
  intent: string;
  url: string;
  testTitle: string;
  timestamp: string;
}

class HealingContext {
  public healCount = 0;

  constructor(
    public readonly page: Page,
    public readonly testTitle: string,
    public readonly maxHeals: number,
  ) {}

  async locator(selector: string, opts: HealOptions): Promise<Locator> {
    const primary = this.page.locator(selector);

    // Fast path: selector still matches. Zero overhead, no model call.
    if ((await primary.count()) > 0) {
      return primary;
    }

    if (this.healCount >= this.maxHeals) {
      throw new Error(
        `Heal budget exhausted (${this.maxHeals}) before "${selector}" ` +
        `[intent: ${opts.intent}]. Refusing to heal further - this is likely ` +
        `a real regression, not cosmetic drift.`,
      );
    }

    return this.heal(selector, opts);
  }

  private async heal(selector: string, opts: HealOptions): Promise<Locator> {
    this.healCount += 1;

    // Compact, role-based context beats raw HTML for both cost and accuracy.
    const ariaSnapshot = await this.page.locator('body').ariaSnapshot();

    const candidate = await proposeLocator({
      brokenSelector: selector,
      intent: opts.intent,
      ariaSnapshot,
      url: this.page.url(),
    });

    const healed = this.page.locator(candidate);
    if ((await healed.count()) === 0) {
      throw new Error(
        `Self-heal failed for "${selector}" [intent: ${opts.intent}]. ` +
        `LLM proposed "${candidate}" which also matched nothing. ` +
        `Treat as a genuine failure.`,
      );
    }

    // The load-bearing line: record the heal for human triage BEFORE returning.
    const record: HealResult = {
      original: selector,
      healed: candidate,
      intent: opts.intent,
      url: this.page.url(),
      testTitle: this.testTitle,
      timestamp: new Date().toISOString(),
    };
    await appendHeal(record);
    console.warn(
      `[SELF-HEAL] "${selector}" -> "${candidate}" (${opts.intent}). ` +
      `Logged for triage. Do NOT assume this heal is correct.`,
    );

    return healed;
  }
}

type HealFixtures = { heal: HealingContext };

export const test = base.extend<HealFixtures>({
  heal: async ({ page }, use, testInfo) => {
    const ctx = new HealingContext(page, testInfo.title, 3);
    await use(ctx);
    // Surface heal count on the test result so CI can flag noisy tests.
    testInfo.annotations.push({
      type: 'self-heal-count',
      description: String(ctx.healCount),
    });
  },
});

export { expect };

// fixtures/llm-client.ts
interface ProposeInput {
  brokenSelector: string;
  intent: string;
  ariaSnapshot: string;
  url: string;
}

const SYSTEM_PROMPT = `You repair broken Playwright locators.
You are given a selector that matched ZERO elements, a short description of
what it was meant to target, and the page's ARIA accessibility snapshot.

Return ONE Playwright locator string that targets the intended element.
Rules:
- Strongly prefer role- and text-based locators, e.g.
  getByRole('button', { name: 'Submit' }) expressed as a selector,
  or a text= / [aria-label=] selector.
- Never invent an element that is not present in the snapshot.
- If nothing in the snapshot plausibly matches the intent, return the token
  NO_MATCH so the test fails honestly instead of healing to the wrong element.
- Output only the selector or NO_MATCH. No prose, no code fences.`;

export async function proposeLocator(input: ProposeInput): Promise<string> {
  const user = [
    `Intent: ${input.intent}`,
    `Broken selector: ${input.brokenSelector}`,
    `URL: ${input.url}`,
    `ARIA snapshot:`,
    input.ariaSnapshot,
  ].join('\n');

  // Use whatever provider SDK you standardize on. Keep temperature low so
  // the same broken page yields a stable proposal across runs.
  const raw = await callModel({
    system: SYSTEM_PROMPT,
    user,
    temperature: 0,
  });

  const candidate = raw.trim();
  if (candidate === 'NO_MATCH' || candidate.length === 0) {
    throw new Error(
      `LLM found no plausible match for intent "${input.intent}". ` +
      `Failing honestly rather than healing to a wrong element.`,
    );
  }
  return candidate;
}

// Replace with your provider's client. Signature kept intentionally generic.
declare function callModel(args: {
  system: string;
  user: string;
  temperature: number;
}): Promise<string>;

// fixtures/heal-ledger.ts
import { appendFile, mkdir } from 'node:fs/promises';
import { dirname } from 'node:path';
import type { HealResult } from './healing';

const LEDGER_PATH = process.env.HEAL_LEDGER ?? 'test-results/heals.jsonl';

export async function appendHeal(record: HealResult): Promise<void> {
  await mkdir(dirname(LEDGER_PATH), { recursive: true });
  await appendFile(LEDGER_PATH, JSON.stringify(record) + '\n', 'utf8');
}

// scripts/summarize-heals.ts
import { readFile } from 'node:fs/promises';

async function main() {
  const path = process.env.HEAL_LEDGER ?? 'test-results/heals.jsonl';
  const lines = (await readFile(path, 'utf8').catch(() => ''))
    .split('\n')
    .filter(Boolean);

  if (lines.length === 0) {
    console.log('No heals this run. Locators held.');
    return;
  }

  console.log(`\n=== SELF-HEAL TRIAGE (${lines.length} heals) ===`);
  console.log('Each heal below needs human eyes. A heal is a QUESTION, not a fix.\n');
  for (const line of lines) {
    const h = JSON.parse(line);
    console.log(`- [${h.testTitle}] ${h.intent}`);
    console.log(`    was: ${h.original}`);
    console.log(`    now: ${h.healed}`);
    console.log(`    at:  ${h.url}\n`);
  }
  // Non-zero exit if you want heals to fail the build until reviewed.
  if (process.env.HEALS_FAIL_BUILD === '1') process.exit(1);
}

main();

// tests/checkout.spec.ts
import { test, expect } from '../fixtures/healing';

test('user can submit the checkout form', async ({ page, heal }) => {
  await page.goto('/checkout');

  const email = await heal.locator('#email-input', {
    intent: 'the email address field in the checkout form',
  });
  await email.fill('[email protected]');

  const submit = await heal.locator('button.checkout-submit', {
    intent: 'the primary Submit button that places the order',
  });
  await submit.click();

  await expect(page.getByText('Order confirmed')).toBeVisible();
});