@ia-qa/self-healing 1.7.4 → 1.7.5

package/README.md

@@ -19,8 +19,11 @@ 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
@@ -122,7 +125,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,6 +1,6 @@
 {
   "name": "@ia-qa/self-healing",
-  "version": "1.7.4",
+  "version": "1.7.5",
   "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.",
   "keywords": [
     "self-healing",