@ia-qa/self-healing 0.10.3 → 1.0.0

package/README.md

@@ -151,6 +151,66 @@ Only if all four fail does it error, listing the three fixes. `map_app` exposes
    ```
    If the selector fails, the helper re-scans the live page, matches the element by role + accessible name (exact, then fuzzy Dice ≥ 0.6 — or your own `llmResolver`), retries on the healed selector, and logs a warning telling you to update the test and re-map.
 
+## Page Object Models — one file to keep in sync
+
+A POM already does what this tool wants: it lifts every selector out of the tests and into **one file**. That is also the one file drift keeps breaking. `map` → `diff` → `fix` treats it like any other test file — the selector is a quoted string literal, so `fix` rewrites it in place.
+
+```ts
+// login.page.ts — the only place a selector is written
+export class LoginPage {
+  readonly emailSelector = '#email';
+  readonly passwordSelector = '#password';
+  readonly submitSelector = 'button#login';
+  // used everywhere as page.fill(this.emailSelector, …)
+}
+```
+
+A developer reworks the login form: `button#login` becomes `button.btn-primary`. The whole suite goes red through this one file. Heal it:
+
+```bash
+npx ia-qa-heal map      # capture the new contract
+npx ia-qa-heal diff     # 🔧 healable  button "Log in"  button#login → button.btn-primary
+npx ia-qa-heal ingest   # inventory the POM's selector literals (optional — lets fix find the file itself)
+npx ia-qa-heal fix .ia-qa/baseline/login.json .ia-qa/mapping/login.json login.page.ts
+```
+
+```diff
+  export class LoginPage {
+    readonly emailSelector = '#email';
+    readonly passwordSelector = '#password';
+-   readonly submitSelector = 'button#login';
++   readonly submitSelector = 'button.btn-primary';
+  }
+```
+
+One line changes and every test that goes through `LoginPage` is fixed at once — the POM is exactly the leverage `fix` is built for. Review with `git diff`, run your suite, commit. Nothing was committed for you.
+
+**One naming detail.** `ingest` recognises a POM property as a selector when its name contains `selector`/`Selector` (`submitSelector`, above) or when the value is a framework call it already knows (`this.page.locator('#login')`). That is what lists the file in `.ia-qa/usage.json`, so `diff` can annotate it and `fix` can find it with no path given. A plainly-named property (`loginButton = '#login'`) is invisible to that inventory — but `fix` still rewrites its literal when you pass the POM file on the command line, because the rewrite is keyed on the string, not the property name.
+
+## In CI
+
+`diff` returns an exit code, so a pipeline can gate on drift — `0` = PASS/FIX, `1` = BLOCK, `2` = bad input:
+
+```yaml
+# .github/workflows/selector-drift.yml
+name: Selector drift
+on: [pull_request]
+jobs:
+  drift:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '20' }
+      - run: npm ci
+      - run: npx playwright install --with-deps chromium
+      - run: npm start &          # your app on its usual port
+      - run: npx ia-qa-heal map   # re-capture into .ia-qa/mapping/
+      - run: npx ia-qa-heal diff  # 0 = PASS/FIX · 1 = BLOCK · 2 = bad input
+```
+
+`diff` with no arguments compares the committed `.ia-qa/baseline/` against what `map` just re-captured — which is why the baseline has to be in git. Add `--report drift-report.html` to attach a branded HTML report to the build, and `--strict` to fail on FIX too. The full workflow (report upload, artifact, `--strict`) is in **[TUTORIAL.md → Putting it in CI](TUTORIAL.md#8-putting-it-in-ci)**.
+
 ## Map artifacts
 
 Beyond one contract per page, every `map` run rebuilds two views of the whole app. Both are derived entirely from the mappings on disk (no extra page visit) and rebuilt on every run, including `map <page>`, so they never drift out of date.

package/TUTORIAL.md

@@ -463,6 +463,9 @@ No. This tool brings its own browser. One install, not two.
 **Cypress or Playwright or Selenium?**
 All of them, and any language. The `fix` command replaces the selector wherever it appears as a quoted string — that's the same in JavaScript, Python, Java, C#, Ruby.
 
+**I use a Page Object Model — does that work?**
+That's the best case. A POM keeps every selector in one file, so a broken selector is one property to fix, not a hunt across the suite. `fix` rewrites the selector string right there in the POM, and every test that uses it is fixed at once. (Tip: if your selector properties are named `…Selector`, `ia-qa-heal ingest` inventories them too, so `fix` finds the file on its own — otherwise just pass the POM file to `fix`.)
+
 **Why is my "renamed" element not fixed automatically?**
 Because the selector still works — your test isn't broken. But the button now says something different, which might be a real change worth failing on. Only a human knows.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ia-qa/self-healing",
-  "version": "0.10.3",
+  "version": "1.0.0",
   "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 — nothing leaves it.",
   "keywords": [
     "self-healing",