elementus-ai 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes are documented here. This project adheres to [Semantic Versioning](https://semver.org).
 
+## 1.5.0
+
+### Added
+
+- `HealEvent.suggestion` — a ready-to-use, framework-native, properly-escaped suggested replacement
+  locator (`getByRole('link', { name: 'Save' })` on Playwright, `$('aria/Save')` on WDIO, `$('~Save')`
+  on Appium). Surface it verbatim. This moves suggestion-building into the library so consumers stop
+  hand-rolling it from `resolved` — hand-rolling re-introduced quote-escaping bugs (text with
+  apostrophes) and bad role mapping (form controls suggested as `getByText`). `resolved` stays for
+  consumers that want the raw facts.
+
+### Changed
+
+- Additive on the existing `onHeal` event; no behavior change.
+
 ## 1.4.0
 
 ### Added

package/README.md

@@ -47,8 +47,8 @@ I just installed the npm package "elementus-ai" — a self-healing element resol
    - TypeScript projects: use import/export and type the override as base.extend<{ page: ElementusPage }>({ ... }) (import ElementusPage from elementus-ai) so { ai } is autocompleted and documented. Types are bundled — do NOT add @types or a "declare module" shim
    - Set actionTimeout: 10000 in playwright config (Elementus respects framework timeouts)
    - Optional heal visibility: only if the user wants healed locators surfaced, wire onHeal to the
-     framework's reporter. Build a suggested replacement from e.resolved ({ tag, text, role }), e.g.
-     getByRole(role, { name: text }). Playwright: push a testInfo "healed" annotation (HTML report) AND
+     framework's reporter. Use e.suggestion — a ready-to-use, escaped, framework-native replacement
+     locator — verbatim. Playwright: push a testInfo "healed" annotation (HTML report) AND
      testInfo.attach (so it also reaches Allure + custom reporters); optionally fail CI on heal via an
      env-gated afterEach/fixture. WebdriverIO/Appium: collect in onHeal, fail in afterTest. See
      "Detecting heals" in the README. Default off
@@ -334,7 +334,7 @@ createElementus({
   // Custom stop words
   stopWords: null,          // Set of words to ignore in descriptions
 
-  // Heal telemetry (opt-in) — called once per heal with { description, selector, method, framework, resolved }.
+  // Heal telemetry (opt-in) — called once per heal with { description, selector, method, framework, resolved, suggestion }.
   // Best-effort & isolated: a throwing callback never breaks a test. See "Detecting heals" below.
   onHeal: null,             // e.g. (e) => console.log('healed', e.selector, '→', e.description)
 })
@@ -343,7 +343,7 @@ createElementus({
 ## Detecting heals (reporting & CI)
 
 A heal is silent by default — the test still passes. To surface it, pass an `onHeal(event)` callback;
-elementus calls it **once per heal** with `{ description, selector, method, framework, resolved }`. The library only
+elementus calls it **once per heal** with `{ description, selector, method, framework, resolved, suggestion }`. The library only
 *emits* the event — turning it into a report annotation or a CI failure is framework-specific (a few lines
 on your side). It fires when the AI resolves a replacement element, so it signals "the selector drifted and
 AI stepped in", not "the action ultimately passed".
@@ -360,14 +360,8 @@ const el = createElementus({
   provider: 'gemini',
   geminiApiKey: process.env.GEMINI_API_KEY,
   onHeal: (e) => {
-    // Build a suggested replacement from the element elementus resolved to (e.resolved)
-    const r = e.resolved
-    const role = r && (r.role ?? { a: 'link', button: 'button' }[r.tag])
-    const suggestion = !r ? '(located visually — no DOM suggestion)'
-      : role && r.text ? `getByRole('${role}', { name: '${r.text}' })`
-      : r.text ? `getByText('${r.text}')`
-      : `locator('${r.tag}')`
-    const line = `${e.selector}  →  ${suggestion}` // failed locator → suggested replacement
+    // e.suggestion is a ready-to-use, escaped, framework-native replacement locator — use it verbatim.
+    const line = `${e.selector}  →  ${e.suggestion ?? '(located visually — no DOM suggestion)'}`
     try {
       const info = base.info()
       info.annotations.push({ type: 'healed', description: line })          // Playwright HTML report

package/elementus.js

@@ -377,7 +377,7 @@ const REGION_LABELS = [
  * @param {number} [userConfig.visionMaxWidth=1280] - max screenshot width (px) sent to vision LLM
  * @param {string|null} [userConfig.cacheFile=null] - opt-in fingerprint cache file (e.g. './elementus-cache.json')
  * @param {string|null} [userConfig.embeddingModel=null] - opt-in embedding model for semantic matching
- * @param {(event: { description: string, selector: string, method: string, framework: string, resolved?: { tag: string, text: string, role: string|null } }) => void} [userConfig.onHeal] - called after a heal resolves a replacement element (original selector failed, AI found it). `resolved` is the element it healed to (when known), for suggesting a replacement. Best-effort; throwing never breaks a test.
+ * @param {(event: { description: string, selector: string, method: string, framework: string, resolved?: { tag: string, text: string, role: string|null }, suggestion?: string }) => void} [userConfig.onHeal] - called after a heal resolves a replacement element (original selector failed, AI found it). `resolved` is the element it healed to; `suggestion` is a ready-to-use, framework-native replacement locator (use it verbatim). Best-effort; throwing never breaks a test.
  * @returns {{ wrap, wrapPage, wrapBrowser, locate, find, click }}
  */
 function createElementus(userConfig = {}) {
@@ -1997,6 +1997,36 @@ function createElementus(userConfig = {}) {
     return { tag: record.tag || '', text: (record.text || '').trim(), role: record.role || null }
   }
 
+  // Implicit ARIA roles for the common interactive tags (used when the element has no explicit
+  // role attribute). `input` is deliberately omitted — its role depends on its type.
+  const ROLE_BY_TAG = { a: 'link', button: 'button', select: 'combobox', textarea: 'textbox' }
+  // Escape a value for a single-quoted string literal in the suggested locator.
+  function _escSingle(s) {
+    return String(s).replace(/\\/g, '\\\\').replace(/'/g, "\\'")
+  }
+  // Collapse whitespace and cap length so the suggested locator stays one readable line.
+  function _suggestName(s) {
+    return String(s || '').replace(/\s+/g, ' ').trim().slice(0, 80)
+  }
+  // Build a ready-to-use, framework-native, properly-escaped suggested replacement locator from
+  // the resolved element. Consumers should surface event.suggestion verbatim — do NOT hand-roll it
+  // (raw text interpolation re-introduces quote-escaping and role-mapping bugs).
+  function _suggestLocator(framework, resolved) {
+    if (!resolved) return undefined
+    const tag = resolved.tag || ''
+    const name = _suggestName(resolved.text)
+    const role = resolved.role || ROLE_BY_TAG[tag] || null
+    if (framework === 'playwright') {
+      if (role && name) return `getByRole('${_escSingle(role)}', { name: '${_escSingle(name)}' })`
+      if (name) return `getByText('${_escSingle(name)}')`
+      return `locator('${_escSingle(tag || '*')}')`
+    }
+    if (framework === 'appium') {
+      return name ? `$('~${_escSingle(name)}')` : `$('${_escSingle(tag || '*')}')`
+    }
+    return name ? `$('aria/${_escSingle(name)}')` : `$('${_escSingle(tag || '*')}')`
+  }
+
   // Fire the user's onHeal(event) after a real heal — the original selector failed and the AI
   // pipeline resolved a replacement. Best-effort and fully isolated: a throwing or rejecting
   // callback must never break a test. No-op with zero overhead when onHeal is not configured.
@@ -2008,7 +2038,10 @@ function createElementus(userConfig = {}) {
     const framework = _isNative(ctx) ? 'appium' : _isPlaywright(ctx) ? 'playwright' : 'wdio'
     try {
       const event = { description, selector: selectorKey, method, framework }
-      if (resolved) event.resolved = resolved
+      if (resolved) {
+        event.resolved = resolved
+        event.suggestion = _suggestLocator(framework, resolved)
+      }
       const r = cb(event)
       if (r && typeof r.then === 'function') r.then(undefined, () => {})
     } catch {}

package/index.d.ts

@@ -54,11 +54,15 @@ export interface HealEvent {
   method: string
   /** Which driver the heal happened on. */
   framework: 'playwright' | 'wdio' | 'appium'
+  /** The element elementus resolved to (when known — absent on coordinate-only vision heals). */
+  resolved?: { tag: string; text: string; role: string | null }
   /**
-   * The element elementus resolved to (when known — absent on coordinate-only vision heals).
-   * Use it to compose a suggested replacement locator, e.g. getByRole(role, { name: text }).
+   * Ready-to-use, framework-native, properly-escaped suggested replacement locator for the failed
+   * selector (e.g. `getByRole('link', { name: 'Save' })` on Playwright, `$('aria/Save')` on WDIO).
+   * Surface it verbatim — don't hand-build one from `resolved` (that re-introduces quote-escaping
+   * and role-mapping bugs). Absent on coordinate-only vision heals.
    */
-  resolved?: { tag: string; text: string; role: string | null }
+  suggestion?: string
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elementus-ai",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Self-healing element resolution for Playwright, WDIO & Appium. AI-powered fallback when selectors break.",
   "main": "elementus.js",
   "types": "index.d.ts",