@ia-qa/self-healing 1.7.4 → 1.7.6

package/README.md

@@ -1,15 +1,22 @@
-# @ia-qa/self-healing
+# ia-qa-heal — self-healing selectors for E2E tests
+
+[![npm](https://img.shields.io/npm/v/@ia-qa/self-healing)](https://www.npmjs.com/package/@ia-qa/self-healing)
+![license](https://img.shields.io/npm/l/@ia-qa/self-healing)
+![node](https://img.shields.io/node/v/@ia-qa/self-healing)
 
 Your E2E tests break because a selector moved, not because the app is wrong. This finds the
 element again and rewrites the test.
 
-A **CLI**, a **local MCP server** for AI agents, and an accessibility-tree page mapper.
-Framework-agnostic — Playwright, Cypress, Selenium; JS/TS, Python, Java. The verdict is
-deterministic: no model decides whether your build passes.
+**The verdict is deterministic — no model decides whether your build passes.** When the repair
+is not provable, the tool refuses to guess and tells you why, rather than quietly rewriting a
+test into a green lie.
 
 **It runs entirely on your machine.** It brings its own headless Chromium, so it sees
 `localhost`, staging, or an app behind a VPN, and **nothing ever leaves the machine**.
 
+Framework-agnostic — Playwright, Cypress, Selenium; JS/TS, Python, Java. Ships a **CLI**, a
+**local MCP server** for AI agents, and an accessibility-tree page mapper.
+
 > **New here?** The [step-by-step tutorial](https://www.ia-qa.com/devtools/selector-drift/tutorial)
 > walks the whole thing with no jargon (same text as `TUTORIAL.md`, shipped in this package).
 > This README is the short reference.
@@ -19,33 +26,61 @@ deterministic: no model decides whether your build passes.
 [![ia-qa-heal repairing a broken Playwright suite: 3 failed, FIX verdict, selectors rewritten to getByRole, 3 passed, verified](https://www.ia-qa.com/media/heal-demo.gif)](https://www.ia-qa.com/media/heal-demo.mp4)
 
 `ia-qa-heal run` runs your suite, watches it break, diffs the live app against your baseline,
-rewrites the dead selectors as `getByRole(…, { exact: true })` — not as fresher CSS paths —
-then **re-runs the suite to verify** and exits on that verdict. Nothing is committed.
+rewrites the dead selectors, then **re-runs the suite to verify** and exits on that verdict.
+Nothing is committed. By default a selector is replaced by the element's new selector, in the
+style your suite already uses — CSS stays CSS. The demo adds `--locators`, which rewrites to
+`getByRole(…, { exact: true })` where that is provably safe: a locator immune to the *next*
+layout change.
 
 ▶ **[The full 49-second version](https://www.ia-qa.com/media/heal-demo.mp4)** also covers what
 deterministic healing *refuses* to guess, the MCP server answering an agent, and the HTML
 report `--report` writes for a PR.
 
-## Install and run the loop
+## Install
 
 ```bash
 npm i -D @ia-qa/self-healing
-npx ia-qa-heal init        # interactive: writes .ia-qa/config.json
 ```
 
-Then, **in this order**:
+**Four commands to your first verdict** — no baseline needed, nothing is rewritten:
+
+```bash
+npx ia-qa-heal init      # interactive: writes .ia-qa/config.json
+npx ia-qa-heal ingest    # inventory the selectors and names your tests use
+npx ia-qa-heal map       # capture the app, and bind your selectors to it
+npx ia-qa-heal audit     # does my suite still name things that exist?
+```
+
+`audit` is read-only and advisory (exit 0 unless `--strict`) — it answers on day one, before
+you have any history to compare against.
+
+**Then one command, for good:**
 
 ```bash
-npx ia-qa-heal ingest      # inventory the selectors and names your tests use
-npx ia-qa-heal map         # capture the app, and bind your selectors to it
-npx ia-qa-heal baseline    # promote that capture to "this is how it should be"
+npx ia-qa-heal baseline  # lock today's UI as the reference — once
 # … someone changes the UI …
+npx ia-qa-heal run       # runs your suite → diffs → fixes → re-runs to verify
+```
+
+`run` is the whole loop in one verb: it runs your suite, watches it break, diffs the live app
+against the baseline, rewrites the dead selectors, then **re-runs the suite to verify** and
+exits on that verdict. Nothing is committed.
+
+<details>
+<summary>Prefer the steps unbundled — <code>map</code> → <code>diff</code> → <code>fix</code></summary>
+
+```bash
 npx ia-qa-heal map
-npx ia-qa-heal diff        # PASS / FIX / BLOCK
+npx ia-qa-heal diff        # PASS / FIX / BLOCK — this is the CI gate
 npx ia-qa-heal fix --dry-run
 npx ia-qa-heal fix
 ```
 
+Use this when your suite is slow (`run` runs it twice), or when CI already captures with
+`IAQA_CAPTURE=1` — then `diff` alone costs nothing extra.
+
+</details>
+
 `ingest` comes **first**, and it is not optional if your tests locate by CSS: it is what lets
 `map` bind the strings your tests write to real elements. Re-run it when your test files
 change — `map` says so when they have. Commit `.ia-qa/` (except `session.json`): the baseline
@@ -122,7 +157,21 @@ What `fix` **refuses** is the point of the tool:
 | `unattributable` | `getByText`, `cy.contains`, `getByTitle`… name a **string, not an element**. Nothing proves the test meant the renamed button rather than a heading that never moved, so editing one would break a *passing* test |
 
 `--locators` rewrites to `getByRole(role, { name })` instead of a fresher CSS path, where that
-is provably safe — a selector that survives the next layout change.
+is provably safe — a selector that survives the next layout change. Without it, a CSS selector
+is replaced by a CSS selector: the tool does not impose a locator style on your suite.
+
+### At runtime, if you want it — `aiClick` / `aiFill`
+
+```ts
+import { aiClick } from '@ia-qa/self-healing';
+await aiClick(page, 'button#login');
+```
+
+If the normal action times out, these read the page contract, re-scan the live page, retry on
+the element that semantically matches, and log a loud warning that the test needs updating.
+Useful to keep a suite green while you triage — but it is a **stopgap, not the loop**: healing
+in memory hides the drift instead of putting it in a pull request. The verbs above edit your
+files so a human reviews the change.
 
 ## Page Objects written in CSS
 

package/package.json

@@ -1,12 +1,19 @@
 {
   "name": "@ia-qa/self-healing",
-  "version": "1.7.4",
-  "description": "Local-first self-healing for UI tests: a local MCP server + CLI that map your app's pages to a role/name/selector contract, diff selector drift (PASS/FIX/BLOCK), and apply deterministic fixes to Cypress/Playwright/Selenium tests. Runs on your machine — your app, your tests and your results never leave it.",
+  "version": "1.7.6",
+  "description": "Your Playwright, Cypress or Selenium tests break when a selector moves — this finds the element again and rewrites the test. Deterministic: no LLM decides whether your build passes. Runs entirely on your machine, with a local MCP server for agents.",
   "keywords": [
     "self-healing",
     "selectors",
+    "broken-selectors",
+    "selector-drift",
+    "locators",
+    "flaky-tests",
+    "flaky",
     "e2e",
+    "e2e-testing",
     "testing",
+    "test-automation",
     "qa",
     "playwright",
     "cypress",
@@ -20,6 +27,13 @@
   "license": "MIT",
   "author": "Jean-Christophe Jamet",
   "homepage": "https://www.ia-qa.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JcJamet/ia-qa-heal.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JcJamet/ia-qa-heal/issues"
+  },
   "type": "commonjs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",