@healflow/playwright

Runtime auto-healing Playwright plugin — detect failures, heal at runtime, and write local artifacts.

Overview

Wraps Playwright's page and locator APIs to automatically retry failed actions (selectors, timing, overlays, iframes, auth, and more). Writes run summaries to .healflow/ after each test run.

Works local-first — no backend or dashboard required.

Installation

npm install @healflow/playwright @healflow/cli @playwright/test
npx healflow init

Playwright version: Test against @playwright/[email protected]. Newer versions (e.g. 1.60+) may break the custom reporter until compatibility is updated.

Quick start

npx playwright test
npx healflow report    # opens .healflow/report.html

Manual config

// playwright.config.ts
import { defineConfig } from '@playwright/test';
import { withHealFlow } from '@healflow/playwright/auto';

export default withHealFlow(
  defineConfig({
    testDir: './tests',
    reporter: [['html'], ['@healflow/playwright']],
  }),
);

Healing fixtures

Import from generated fixtures (created by healflow init):

import { test, expect } from './healflow.fixtures';

Or wire manually:

import { test as base } from '@playwright/test';
import { healflowFixture } from '@healflow/playwright';

export const test = base.extend(healflowFixture());

Local artifacts

After each run, .healflow/ contains:

| File | Purpose | | ------------- | ------------------------------------ | | report.html | Human-readable heal summary | | heals.json | Runtime heals applied during the run | | fixes.json | AST fix proposals (dry-run) | | run.json | Full run metadata |

Configuration

Set options in healflow.yml:

mode: local
output: verbose

healing:
  selector: true
  timing: true
  overlay: true
  iframe: true
  shadowDom: true
  auth: true
  network: true
  navigation: true
  mobile: true
  i18n: true
  upload: true
  multiTab: true

# Optional cloud sync
backend:
  url: https://api.healflow.example
  organizationId: my-org
  repositoryId: my-repo
  token: hf_...

Environment variables: HEALFLOW_API_URL, HEALFLOW_ORG_ID, HEALFLOW_REPO_ID, HEALFLOW_TOKEN.

Exports

| Subpath | Purpose | | ----------------------------------- | --------------------------------------------- | | @healflow/playwright | healflowFixture, wrapPage, plugin options | | @healflow/playwright/auto | withHealFlow() config wrapper | | @healflow/playwright/reporter | Custom Playwright reporter | | @healflow/playwright/setup-global | Global setup hook |

Runtime healing categories

HealFlow walks the T0→T5 runtime ladder on every healable locator/page action:

| Technique | Purpose | | -------------- | ---------------------------------------------------------------- | | T0 Retry | Condition-based waits (visibility, network idle, spinner hidden) | | T1 Scope | Parent-chain scoping | | T2 Normalize | Role / label / text strategy migration | | T3 Fingerprint | DOM attribute & aria similarity | | T4 Trace | Frame/shadow/navigation hints from Playwright error context | | T5 History | Reuse prior heals from .healflow/heals.json |

Categories enabled by default: selector, timing, overlay, iframe, shadow DOM, auth/session, network, navigation, mobile, i18n, upload, multi-tab.

Each runtime heal records matrixEntryId, succeededTechnique, and healMode in .healflow/heals.json.

Product bugs and assertion values are never auto-fixed.

Cloud sync (optional)

When backend is configured, the reporter syncs heals to the HealFlow API after each run. See @healflow/cli for healflow ingest.

Development

pnpm --filter @healflow/playwright build
pnpm --filter @healflow/playwright typecheck

Related packages

• @healflow/cli — healflow init, doctor, report
• @healflow/classification — runtime error classification

License

MIT