assertrx-heal

A CI CLI that finds selectors @assertrx/playwright-reporter flagged as broken (selector-not-found / selector-ambiguous) in recent test runs, re-inspects the live page they belong to, and proposes a replacement selector — the "healing" step in AssertRx's self-healing test pipeline.

It's a heuristic, deterministic v1: no AI call yet. Every proposed fix comes with an explainable confidence score (high / medium / low / none) based on label-text similarity between the old Page Object property and the freshly-inspected page, so nothing gets silently auto-applied without a clear reason attached.

How it fits into the pipeline

playwright test (reporter uploads runs, flags broken selectors)
        │
        ▼
assertrx-heal (this CLI, run as a separate CI step)
        │
        ├── fetches recent runs for the project
        ├── finds selector-not-found / selector-ambiguous failures
        ├── for each one:
        │     ├── reads page-objects/{pageName}.ts to find which
        │     │     property the selector belongs to (e.g. "signInButton")
        │     ├── re-launches a headless browser against that page
        │     │     (from assertrx.config.json)
        │     └── ranks fresh elements against the old label to
        │           propose a replacement selector
        │
        └── POSTs suggestions to AssertRx (Test Run Details page)
              — falls back to a local assertrx-healing-report.json
                if that endpoint isn't deployed yet

Install

npm install --save-dev assertrx-heal

Requires

• The same assertrx.config.json the AssertRx VS Code extension uses (page name → URL, optional login credentials), in the workspace root.
• page-objects/{pageName}.ts files generated by "AssertRx: Generate Page Object" — used to map a broken selector back to a human-readable label. If a Page Object file is missing or the selector isn't found in it, the CLI still runs, just with a weaker match (it falls back to matching against the raw selector text instead of a real label).
• Recent runs uploaded via @assertrx/playwright-reporter for the project you're healing — this CLI reads already-uploaded run data, it doesn't parse local Playwright output itself.

Configure

ASSERTRX_API_TOKEN=trx_xxx npx assertrx-heal --project "My Project"

| Env var / flag | Required | Default | Description | |---|---|---|---| | ASSERTRX_API_TOKEN | Yes | — | Same token used by the reporter | | --project / ASSERTRX_PROJECT_NAME | Yes | — | Project name in AssertRx | | ASSERTRX_BASE_URL | No | https://api.assertrx.com | Override the API endpoint | | --config | No | <workspace>/assertrx.config.json | Path to the config file | | --workspace | No | current directory | Where to find assertrx.config.json / page-objects/ | | --limit | No | 300 | How many recent runs to scan for candidates | | --headed | No | false | Run the re-inspection browser headed (local debugging only — CI has no display) |

CI usage (GitHub Actions)

- name: Run tests
  run: npx playwright test
  env:
    ASSERTRX_API_TOKEN: ${{ secrets.ASSERTRX_API_TOKEN }}

- name: Heal broken selectors
  if: failure()
  run: npx assertrx-heal --project "My Project"
  env:
    ASSERTRX_API_TOKEN: ${{ secrets.ASSERTRX_API_TOKEN }}

Runs headless by default and always exits 0 on a normal healing pass (even if some selectors got confidence: none) — it's advisory, so it shouldn't fail your pipeline. It only exits non-zero on a hard error (missing token, unreachable API, malformed config).

What "confidence" means

| Confidence | Meaning | |---|---| | high | Strong label-text match — likely safe to apply directly | | medium | Decent match — worth a quick look before applying | | low | Weak match — surfaced so a human knows to investigate, not to auto-apply | | none | No fix proposed — either the page/Page Object couldn't be found, or the old selector still matches something (may be a timing issue, not a broken selector) |

Known limitations (v1)

• Heuristic matching only — no AI confirmation step yet. This is deliberate: the deterministic pieces (annotation reading, config parsing, source-file matching) don't need an LLM to be reliable, and keeping this version AI-free means every score is fully explainable. An --ai-confirm mode using AssertRx's AI proxy is a natural next step for cases the heuristic scores as low.
• POST /integrations/healing-suggestions doesn't exist on the API yet — suggestions are written to assertrx-healing-report.json in the workspace until it does.
• Only heals selectors that came from a spec generated via "AssertRx: Generate Test Script" (so pageNames metadata exists) and a Page Object that hasn't drifted too far from what's on disk. Hand-written specs with no .feature file behind them can't be healed — there's no page mapping to recover.
• One element list per page per run — if a page's content depends on application state the re-inspection doesn't reproduce (e.g. a specific cart contents, a feature flag), the fresh inspection may not match what actually broke in CI.

Requirements

• Node.js 18+
• An AssertRx account with API access
• Playwright browsers installed in the CI environment (same as your test job — npx playwright install --with-deps)

License

MIT