elementus-ai 1.4.0 → 1.5.1

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes are documented here. This project adheres to [Semantic Versioning](https://semver.org).
 
+## 1.5.1
+
+### Fixed
+
+- Suggestion/`resolved` quality for **form controls**. A healed `<input>`/`<select>`/`<textarea>` now
+  reports its implicit ARIA **role** (`<input type="submit">` → `button`, text inputs → `textbox`,
+  checkbox/radio/range/number → their roles) and a proper **accessible name** (a button-like input's
+  `value`, e.g. `Login`, instead of its `name` attribute). So the heal suggests
+  `getByRole('button', { name: 'Login' })` instead of the previous `getByText('login-button')` — which
+  would never match a form control. `_suggestLocator` also never falls back to `getByText` for a form
+  control (it uses a tag locator when no role/name is available).
+
+### Changed
+
+- `textOf` (element label derivation, used for both matching and suggestions) now prefers a button-like
+  input's `value` over its `name`/`title`/`alt` attributes; a text input's current value stays a last
+  resort. No public API change — the `resolved`/`suggestion` shapes are unchanged, just more accurate.
+
+## 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 = {}) {
@@ -800,10 +800,19 @@ function createElementus(userConfig = {}) {
       function textOf(el) {
         const t = el.textContent.trim().replace(/\s+/g, ' ')
         if (t) return t
-        for (const attr of ['aria-label', 'placeholder', 'name', 'title', 'alt']) {
+        for (const attr of ['aria-label', 'placeholder']) {
           const v = el.getAttribute(attr)
           if (v && v.trim()) return v.trim().replace(/\s+/g, ' ')
         }
+        // Button-like inputs: `value` is the visible label, e.g. <input type="submit" value="Login">
+        if (el.tagName === 'INPUT' && /^(submit|button|reset)$/i.test(el.type) && el.value) {
+          return String(el.value).trim().replace(/\s+/g, ' ')
+        }
+        for (const attr of ['name', 'title', 'alt']) {
+          const v = el.getAttribute(attr)
+          if (v && v.trim()) return v.trim().replace(/\s+/g, ' ')
+        }
+        // Text inputs/textarea: current value last (it's user-entered content, not a label)
         if ((el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') && el.type !== 'password' && el.value) {
           return String(el.value).trim().replace(/\s+/g, ' ')
         }
@@ -824,6 +833,7 @@ function createElementus(userConfig = {}) {
           text,
           tag:  el.tagName.toLowerCase(),
           role: el.getAttribute('role') || null,
+          type: el.type || '',
           href: el.getAttribute('href') || null,
           docX: Math.round(rect.left + window.scrollX + rect.width / 2),
           docY: Math.round(rect.top + window.scrollY + rect.height / 2),
@@ -1013,10 +1023,19 @@ function createElementus(userConfig = {}) {
         function textOf(el) {
           const t = el.textContent.trim().replace(/\s+/g, ' ')
           if (t) return t
-          for (const attr of ['aria-label', 'placeholder', 'name', 'title', 'alt']) {
+          for (const attr of ['aria-label', 'placeholder']) {
+            const v = el.getAttribute(attr)
+            if (v && v.trim()) return v.trim().replace(/\s+/g, ' ')
+          }
+          // Button-like inputs: `value` is the visible label, e.g. <input type="submit" value="Login">
+          if (el.tagName === 'INPUT' && /^(submit|button|reset)$/i.test(el.type) && el.value) {
+            return String(el.value).trim().replace(/\s+/g, ' ')
+          }
+          for (const attr of ['name', 'title', 'alt']) {
             const v = el.getAttribute(attr)
             if (v && v.trim()) return v.trim().replace(/\s+/g, ' ')
           }
+          // Text inputs/textarea: current value last (it's user-entered content, not a label)
           if ((el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') && el.type !== 'password' && el.value) {
             return String(el.value).trim().replace(/\s+/g, ' ')
           }
@@ -1035,6 +1054,7 @@ function createElementus(userConfig = {}) {
           classes: typeof el.className === 'string' ? el.className.trim() : '',
           name: el.getAttribute('name') || '',
           role: el.getAttribute('role') || '',
+          type: el.type || '',
           href: el.getAttribute('href') || '',
           text: textOf(el),
           neighborText: el.parentElement
@@ -1341,10 +1361,19 @@ function createElementus(userConfig = {}) {
         function textOf(el) {
           const t = el.textContent.trim().replace(/\s+/g, ' ')
           if (t) return t
-          for (const attr of ['aria-label', 'placeholder', 'name', 'title', 'alt']) {
+          for (const attr of ['aria-label', 'placeholder']) {
+            const v = el.getAttribute(attr)
+            if (v && v.trim()) return v.trim().replace(/\s+/g, ' ')
+          }
+          // Button-like inputs: `value` is the visible label, e.g. <input type="submit" value="Login">
+          if (el.tagName === 'INPUT' && /^(submit|button|reset)$/i.test(el.type) && el.value) {
+            return String(el.value).trim().replace(/\s+/g, ' ')
+          }
+          for (const attr of ['name', 'title', 'alt']) {
             const v = el.getAttribute(attr)
             if (v && v.trim()) return v.trim().replace(/\s+/g, ' ')
           }
+          // Text inputs/textarea: current value last (it's user-entered content, not a label)
           if ((el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') && el.type !== 'password' && el.value) {
             return String(el.value).trim().replace(/\s+/g, ' ')
           }
@@ -1356,6 +1385,7 @@ function createElementus(userConfig = {}) {
         return {
           uid: existing || uid,
           tag: el.tagName.toLowerCase(),
+          type: el.type || '',
           text: textOf(el),
           href: el.getAttribute('href') || null,
           docX: Math.round(rect.left + window.scrollX + rect.width / 2),
@@ -1364,7 +1394,7 @@ function createElementus(userConfig = {}) {
       }, uid, { timeout: 5000 })
       console.log(`[Resolve] Aria grounded <${record.tag}> "${record.text}" via ref=${ref}`)
       const locator = await _makeLocator(ctx, `[data-elementus="${record.uid}"]`)
-      return { tag: record.tag, text: record.text, href: record.href, docX: record.docX, docY: record.docY, _locator: locator, _uid: record.uid }
+      return { tag: record.tag, type: record.type, text: record.text, href: record.href, docX: record.docX, docY: record.docY, _locator: locator, _uid: record.uid }
     } catch (err) {
       console.log(`[Resolve] Aria ref resolution failed (${err.message}) — falling through`)
       return null
@@ -1693,10 +1723,19 @@ function createElementus(userConfig = {}) {
       function textOf(el) {
         const t = el.textContent.trim().replace(/\s+/g, ' ')
         if (t) return t
-        for (const attr of ['aria-label', 'placeholder', 'name', 'title', 'alt']) {
+        for (const attr of ['aria-label', 'placeholder']) {
+          const v = el.getAttribute(attr)
+          if (v && v.trim()) return v.trim().replace(/\s+/g, ' ')
+        }
+        // Button-like inputs: `value` is the visible label, e.g. <input type="submit" value="Login">
+        if (el.tagName === 'INPUT' && /^(submit|button|reset)$/i.test(el.type) && el.value) {
+          return String(el.value).trim().replace(/\s+/g, ' ')
+        }
+        for (const attr of ['name', 'title', 'alt']) {
           const v = el.getAttribute(attr)
           if (v && v.trim()) return v.trim().replace(/\s+/g, ' ')
         }
+        // Text inputs/textarea: current value last (it's user-entered content, not a label)
         if ((el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') && el.type !== 'password' && el.value) {
           return String(el.value).trim().replace(/\s+/g, ' ')
         }
@@ -1992,9 +2031,63 @@ function createElementus(userConfig = {}) {
   // Facts about the element the last heal resolved to (tag/text/role) — set during resolution,
   // read once by _notifyHeal. Framework-agnostic; consumers format a suggested replacement locator.
   let _lastResolved = null
+  // Implicit ARIA role for native interactive elements with no explicit `role` attribute, derived
+  // from the tag (and an input's `type`). Lets the heal suggest a correct getByRole(...) — e.g. a
+  // submit input becomes role 'button', not a dead getByText(...).
+  function _implicitRole(tag, type, href) {
+    if (tag === 'a') return href ? 'link' : null
+    if (tag === 'button') return 'button'
+    if (tag === 'select') return 'combobox'
+    if (tag === 'textarea') return 'textbox'
+    if (tag === 'input') {
+      const t = (type || '').toLowerCase()
+      if (t === 'submit' || t === 'button' || t === 'reset' || t === 'image') return 'button'
+      if (t === 'checkbox') return 'checkbox'
+      if (t === 'radio') return 'radio'
+      if (t === 'range') return 'slider'
+      if (t === 'number') return 'spinbutton'
+      if (t === 'hidden') return null
+      return 'textbox' // text/email/search/tel/url/password/date/…
+    }
+    return null
+  }
   function _resolvedFacts(record) {
     if (!record) return null
-    return { tag: record.tag || '', text: (record.text || '').trim(), role: record.role || null }
+    const tag = (record.tag || '').toLowerCase()
+    return { tag, text: (record.text || '').trim(), role: record.role || _implicitRole(tag, record.type, record.href) }
+  }
+
+  // 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)}' })`
+      // getByText matches visible text content — never right for a form control (its label lives in
+      // value/label/placeholder, not text), so fall back to a tag locator instead of a dead getByText.
+      const isFormControl = tag === 'input' || tag === 'select' || tag === 'textarea'
+      if (name && !isFormControl) 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
@@ -2008,7 +2101,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.1",
   "description": "Self-healing element resolution for Playwright, WDIO & Appium. AI-powered fallback when selectors break.",
   "main": "elementus.js",
   "types": "index.d.ts",