@validate.qa/runner 1.0.25 → 1.0.27

package/dist/cli.js

@@ -1029,9 +1029,39 @@ var require_mobile_source_parser = __commonJS({
     function isEditableElement(el) {
       return EDITABLE_CLASS_RE.test(el.role.trim());
     }
+    function xpathAttrLiteral(value) {
+      if (!value.includes("'"))
+        return `'${value}'`;
+      if (!value.includes('"'))
+        return `"${value}"`;
+      return `concat('${value.split("'").join(`', "'", '`)}')`;
+    }
+    function semanticXPath(el, platform3) {
+      const cls = nonBlank(el.role) ?? "*";
+      const a11y = nonBlank(el.accessibilityId);
+      if (a11y) {
+        return platform3 === "ANDROID" ? `//${cls}[@content-desc=${xpathAttrLiteral(a11y)}]` : `//${cls}[@name=${xpathAttrLiteral(a11y)}]`;
+      }
+      const rid = nonBlank(el.resourceId);
+      if (platform3 === "ANDROID" && rid)
+        return `//${cls}[@resource-id=${xpathAttrLiteral(rid)}]`;
+      const text = nonBlank(el.text);
+      if (text && !isEditableElement(el)) {
+        return platform3 === "ANDROID" ? `//${cls}[@text=${xpathAttrLiteral(text)}]` : `//${cls}[@label=${xpathAttrLiteral(text)}]`;
+      }
+      return void 0;
+    }
+    function nonBlank(value) {
+      if (typeof value !== "string")
+        return void 0;
+      const trimmed = value.trim();
+      return trimmed.length > 0 ? trimmed : void 0;
+    }
     function buildLocatorBundle(el, platform3) {
       const bundle = {
-        xpath: el.xpath,
+        // Attribute-anchored xpath when the element has identity; the absolute
+        // indexed path only for identity-less elements (nothing else can find them).
+        xpath: semanticXPath(el, platform3) ?? el.xpath,
         className: el.role
       };
       if (el.accessibilityId)
@@ -1544,7 +1574,7 @@ function buildStepTarget(metadata, selector) {
     locatorBundle.xpath,
     selector
   ];
-  const fallbacks = fallbackCandidates.map(nonEmpty).filter((value, index, list) => typeof value === "string" && value !== primary && list.indexOf(value) === index);
+  const fallbacks = fallbackCandidates.map(nonEmpty).filter((value, index, list) => typeof value === "string" && value !== primary && list.indexOf(value) === index).filter((value) => !value.startsWith("/hierarchy") && !(value.startsWith("/") && value.length > 120));
   return {
     primary,
     fallbacks,
@@ -1675,8 +1705,6 @@ function selectorCandidatesForStep(step) {
       candidates.push(`id=${bundle.resourceId}`);
     if (nonEmpty(bundle.xpath))
       candidates.push(bundle.xpath);
-    if (nonEmpty(bundle.className))
-      candidates.push(`class=${bundle.className}`);
   }
   if (nonEmpty(target.primary))
     candidates.push(selectorForValue(target.primary));
@@ -1684,7 +1712,7 @@ function selectorCandidatesForStep(step) {
     if (nonEmpty(fallback))
       candidates.push(selectorForValue(fallback));
   }
-  return candidates.filter((value, index, list) => list.indexOf(value) === index);
+  return candidates.filter((value) => !value.startsWith("/hierarchy") && !(value.startsWith("/") && !value.startsWith("//") && value.length > 120)).filter((value, index, list) => list.indexOf(value) === index).slice(0, 4);
 }
 function buildAppiumCode(testName, target, steps) {
   const appId = target?.appId ?? "com.example.app";
@@ -1694,74 +1722,118 @@ function buildAppiumCode(testName, target, steps) {
   const platformVersion = target?.platformVersion;
   const launchMode = target?.launchMode;
   const deeplink = target?.deeplink;
-  const hasSwipe = steps.some((s) => s.action === "swipe" || s.action === "scroll");
+  const boundsOf = (step) => step.metadata?.bounds;
+  const centerOf = (b) => ({ x: Math.round(b.x + b.width / 2), y: Math.round(b.y + b.height / 2) });
+  const atLiteral = (b) => {
+    const c = centerOf(b);
+    return `{ x: ${c.x}, y: ${c.y} }`;
+  };
+  const used = {
+    find: false,
+    tap: false,
+    tapAt: false,
+    typeInto: false,
+    clearField: false,
+    expectVisible: false,
+    expectText: false,
+    swipe: false,
+    wait: false
+  };
+  for (const step of steps) {
+    const hasSelector = selectorCandidatesForStep(step).length > 0;
+    const bounds = boundsOf(step);
+    switch (step.action) {
+      case "tap":
+        if (hasSelector) {
+          used.tap = true;
+          used.find = true;
+          if (bounds)
+            used.tapAt = true;
+        } else if (bounds)
+          used.tapAt = true;
+        break;
+      case "type":
+        used.typeInto = true;
+        if (hasSelector)
+          used.find = true;
+        if (bounds)
+          used.tapAt = true;
+        break;
+      case "clear":
+        used.clearField = true;
+        if (hasSelector)
+          used.find = true;
+        if (bounds)
+          used.tapAt = true;
+        break;
+      case "assertVisible":
+        if (hasSelector) {
+          used.expectVisible = true;
+          used.find = true;
+        }
+        break;
+      case "assertText":
+        if (hasSelector) {
+          used.expectText = true;
+          used.find = true;
+        }
+        break;
+      case "swipe":
+      case "scroll":
+        used.swipe = true;
+        break;
+      case "waitForElement":
+        if (hasSelector) {
+          used.wait = true;
+          used.find = true;
+        }
+        break;
+      default:
+        break;
+    }
+  }
+  const helperLines = [];
+  if (used.find)
+    helperLines.push(`// First selector that resolves wins \u2014 the runner's exact fallback chain.`, `async function find(driver: WebdriverIO.Browser, selectors: string[]) {`, `  for (const sel of selectors) {`, `    try { const el = await driver.$(sel); if (await el.isExisting()) return el; } catch { /* try next */ }`, `  }`, `  throw new Error('No locator resolved. Tried: ' + JSON.stringify(selectors));`, `}`, ``);
+  if (used.tapAt)
+    helperLines.push(`async function tapAt(driver: WebdriverIO.Browser, x: number, y: number) {`, `  await driver.performActions([{ type: 'pointer', id: 'finger1', parameters: { pointerType: 'touch' }, actions: [`, `    { type: 'pointerMove', duration: 0, x, y }, { type: 'pointerDown', button: 0 }, { type: 'pause', duration: 100 }, { type: 'pointerUp', button: 0 },`, `  ] }]);`, `}`, ``);
+  if (used.tap)
+    helperLines.push(`// Locator-first tap; falls back to the recorded coordinates like the runner.`, `async function tap(driver: WebdriverIO.Browser, selectors: string[], at?: { x: number; y: number }) {`, used.tapAt ? `  try { await (await find(driver, selectors)).click(); } catch (err) { if (!at) throw err; await tapAt(driver, at.x, at.y); }` : `  await (await find(driver, selectors)).click();`, `}`, ``);
+  if (used.typeInto)
+    helperLines.push(`// addValue (append) matches replay exactly; with recorded coordinates it`, `// taps to focus first (placeholder locators go stale once the keyboard opens).`, `async function typeInto(driver: WebdriverIO.Browser, selectors: string[], text: string, at?: { x: number; y: number }) {`, ...used.tapAt ? [
+      `  if (at) {`,
+      `    try {`,
+      `      await tapAt(driver, at.x, at.y);`,
+      `      await driver.pause(${MOBILE_FOCUS_SETTLE_MS});`,
+      `      await (await driver.getActiveElement() as unknown as WebdriverIO.Element).addValue(text);`,
+      `      return;`,
+      `    } catch { /* fall through to locator path */ }`,
+      `  }`
+    ] : [], `  await (await find(driver, selectors)).addValue(text);`, `}`, ``);
+  if (used.clearField)
+    helperLines.push(`async function clearField(driver: WebdriverIO.Browser, selectors: string[], at?: { x: number; y: number }) {`, ...used.tapAt ? [
+      `  if (at) {`,
+      `    try {`,
+      `      await tapAt(driver, at.x, at.y);`,
+      `      await driver.pause(${MOBILE_FOCUS_SETTLE_MS});`,
+      `      await (await driver.getActiveElement() as unknown as WebdriverIO.Element).clearValue();`,
+      `      return;`,
+      `    } catch { /* fall through to locator path */ }`,
+      `  }`
+    ] : [], `  await (await find(driver, selectors)).clearValue();`, `}`, ``);
+  if (used.expectVisible)
+    helperLines.push(`async function expectVisible(driver: WebdriverIO.Browser, selectors: string[]) {`, `  if (!(await (await find(driver, selectors)).isDisplayed())) {`, `    throw new Error('Assertion failed: element not displayed: ' + JSON.stringify(selectors));`, `  }`, `}`, ``);
+  if (used.expectText)
+    helperLines.push(`// Contains-match over text-like attributes \u2014 mirrors the runtime executor.`, `async function expectText(driver: WebdriverIO.Browser, selectors: string[], expected: string) {`, `  if (expected.length === 0) throw new Error('assertText step is missing expected text');`, `  const el = await find(driver, selectors);`, `  const values: string[] = [];`, `  const push = (v: unknown) => { if (typeof v === 'string' && v.trim() && !values.includes(v.trim())) values.push(v.trim()); };`, `  push(await el.getText().catch(() => ''));`, `  for (const attr of ['text', 'content-desc', 'contentDescription', 'name', 'label', 'value']) push(await el.getAttribute(attr).catch(() => ''));`, `  if (!values.some((v) => v.includes(expected))) {`, `    throw new Error('Assertion failed: expected text to contain ' + JSON.stringify(expected) + ' but got ' + JSON.stringify(values));`, `  }`, `}`, ``);
+  if (used.swipe)
+    helperLines.push(`// Centred W3C swipe with the executor's geometry (full distance, clamped to 80% of the axis).`, `async function swipe(driver: WebdriverIO.Browser, direction: 'up' | 'down' | 'left' | 'right', distance: number) {`, `  let rect: { width: number; height: number } | undefined;`, `  for (let i = 0; i < 3 && !rect; i++) {`, `    try { const r = await driver.getWindowRect(); if (r && r.width > 0 && r.height > 0) rect = r; } catch { await driver.pause(Math.pow(2, i) * 100); }`, `  }`, `  if (!rect) throw new Error('Could not determine device window size');`, `  const vertical = direction === 'up' || direction === 'down';`, `  const travel = Math.min(distance, Math.max(1, Math.round((vertical ? rect.height : rect.width) * 0.8)));`, `  const cx = Math.round(rect.width / 2), cy = Math.round(rect.height / 2), half = Math.round(travel / 2);`, `  const sx = direction === 'left' ? cx + half : direction === 'right' ? cx - half : cx;`, `  const sy = direction === 'up' ? cy + half : direction === 'down' ? cy - half : cy;`, `  const ex = direction === 'left' ? cx - half : direction === 'right' ? cx + half : cx;`, `  const ey = direction === 'up' ? cy - half : direction === 'down' ? cy + half : cy;`, `  await driver.performActions([{ type: 'pointer', id: 'finger1', parameters: { pointerType: 'touch' }, actions: [`, `    { type: 'pointerMove', duration: 0, x: sx, y: sy }, { type: 'pointerDown', button: 0 }, { type: 'pointerMove', duration: 300, x: ex, y: ey }, { type: 'pointerUp', button: 0 },`, `  ] }]);`, `}`, ``);
   const setupLines = [
-    `// Standalone WebdriverIO script \u2014 runnable as-is with \`node\`/\`tsx\`.`,
-    `// Prerequisites:`,
-    `//   1. npm i webdriverio`,
-    `//   2. An Appium server reachable on http://localhost:4723`,
-    `//   3. A booted device/simulator matching the capabilities below`,
-    `// This is NOT a WDIO testrunner spec: it uses the standalone remote() client`,
-    `// (driver.$, no auto-injected $/expect/describe globals) so it has no harness`,
-    `// dependency and runs with a plain \`tsx ${toInlineCommentText(testName)}.spec.ts\`.`,
+    `// ${toInlineCommentText(testName)} \u2014 ${steps.length} step(s), exported from validate.qa.`,
+    `// Runnable standalone: \`npm i webdriverio\`, Appium on :4723, booted device. The`,
+    `// canonical execution source is the steps JSON; this script mirrors it 1:1.`,
     `import { remote } from 'webdriverio';`,
     ``,
-    `// Resolve the first selector that exists, mirroring the runner's locator`,
-    `// fallback chain so a stale primary the runner would recover from doesn't fail`,
-    `// the exported script.`,
-    `async function findFirst(driver: WebdriverIO.Browser, selectors: string[]) {`,
-    `  let __lastError: unknown;`,
-    `  for (const __sel of selectors) {`,
-    `    try {`,
-    `      const __el = await driver.$(__sel);`,
-    `      if (await __el.isExisting()) return __el;`,
-    `    } catch (err) { __lastError = err; }`,
-    `  }`,
-    `  throw new Error('No locator resolved. Tried: ' + JSON.stringify(selectors) + (__lastError ? ' (last error: ' + String(__lastError) + ')' : ''));`,
-    `}`,
-    ``,
-    `async function __tapAt(driver: WebdriverIO.Browser, x: number, y: number) {`,
-    `  await driver.performActions([{ type: 'pointer', id: 'finger1', parameters: { pointerType: 'touch' }, actions: [{ type: 'pointerMove', duration: 0, x, y }, { type: 'pointerDown', button: 0 }, { type: 'pause', duration: 100 }, { type: 'pointerUp', button: 0 }] }]);`,
-    `}`,
-    ``,
-    `async function __typeIntoFocused(driver: WebdriverIO.Browser, text: string) {`,
-    `  try {`,
-    `    await (await driver.getActiveElement() as unknown as WebdriverIO.Element).addValue(text);`,
-    `  } catch {`,
-    `    await driver.keys(text);`,
-    `  }`,
-    `}`,
-    ``,
-    `async function __clearFocused(driver: WebdriverIO.Browser) {`,
-    `  await (await driver.getActiveElement() as unknown as WebdriverIO.Element).clearValue();`,
-    `}`,
-    ``,
-    `async function __textCandidates(el: WebdriverIO.Element) {`,
-    `  const __values: string[] = [];`,
-    `  const __push = (__value: unknown) => {`,
-    `    if (typeof __value !== 'string') return;`,
-    `    const __trimmed = __value.trim();`,
-    `    if (__trimmed.length === 0 || __values.includes(__trimmed)) return;`,
-    `    __values.push(__trimmed);`,
-    `  };`,
-    `  __push(await el.getText().catch(() => ''));`,
-    `  for (const __attr of ['text', 'content-desc', 'contentDescription', 'name', 'label', 'value']) {`,
-    `    __push(await el.getAttribute(__attr).catch(() => ''));`,
-    `  }`,
-    `  return __values;`,
-    `}`,
-    ...hasSwipe ? [
-      ``,
-      `// Read the device window with a few retries (matches the runtime executor).`,
-      `async function __getWindowRect(driver: WebdriverIO.Browser) {`,
-      `  for (let __i = 0; __i < 3; __i++) {`,
-      `    try { const __r = await driver.getWindowRect(); if (__r && __r.width > 0 && __r.height > 0) return __r; } catch { /* retry */ }`,
-      `    await driver.pause(Math.pow(2, __i) * 100);`,
-      `  }`,
-      `  throw new Error('Could not determine device window size');`,
-      `}`
-    ] : [],
-    ``,
+    ...helperLines,
     `async function main() {`,
     `  const driver = await remote({`,
     `    path: '/',`,
@@ -1782,108 +1854,45 @@ function buildAppiumCode(testName, target, steps) {
       `    // the same entry screen as during recording.`,
       platform3 === "iOS" ? `    await driver.execute('mobile: deepLink', { url: ${toJsStringLiteral(deeplink)}, bundleId: ${toJsStringLiteral(appId)} });` : `    await driver.execute('mobile: deepLink', { url: ${toJsStringLiteral(deeplink)}, package: ${toJsStringLiteral(appId)} });`,
       ``
-    ] : [],
-    `    // Canonical execution source: steps JSON`
+    ] : []
   ];
   const stepLines = steps.flatMap((step) => {
-    const lines = [`    // Step ${step.order + 1}: ${toInlineCommentText(step.description)}`];
+    const lines = [`    // ${step.order + 1}. ${toInlineCommentText(step.description)}`];
     const candidates = selectorCandidatesForStep(step);
-    const candidatesLiteral = `[${candidates.map(toJsStringLiteral).join(", ")}]`;
+    const sel = `[${candidates.map(toJsStringLiteral).join(", ")}]`;
     const hasSelector = candidates.length > 0;
-    const bounds = step.metadata?.bounds;
+    const bounds = boundsOf(step);
+    const at = bounds ? `, ${atLiteral(bounds)}` : "";
     if (step.action === "tap" && hasSelector) {
-      if (bounds) {
-        const x = Math.round(bounds.x + bounds.width / 2);
-        const y = Math.round(bounds.y + bounds.height / 2);
-        lines.push(`    try {`);
-        lines.push(`      await (await findFirst(driver, ${candidatesLiteral})).click();`);
-        lines.push(`    } catch {`);
-        lines.push(`      await driver.performActions([{ type: 'pointer', id: 'finger1', parameters: { pointerType: 'touch' }, actions: [{ type: 'pointerMove', duration: 0, x: ${x}, y: ${y} }, { type: 'pointerDown', button: 0 }, { type: 'pause', duration: 100 }, { type: 'pointerUp', button: 0 }] }]);`);
-        lines.push(`    }`);
-      } else {
-        lines.push(`    await (await findFirst(driver, ${candidatesLiteral})).click();`);
-      }
+      lines.push(`    await tap(driver, ${sel}${at});`);
     } else if (step.action === "tap" && bounds) {
-      const x = Math.round(bounds.x + bounds.width / 2);
-      const y = Math.round(bounds.y + bounds.height / 2);
-      lines.push(`    await driver.performActions([{ type: 'pointer', id: 'finger1', parameters: { pointerType: 'touch' }, actions: [{ type: 'pointerMove', duration: 0, x: ${x}, y: ${y} }, { type: 'pointerDown', button: 0 }, { type: 'pause', duration: 100 }, { type: 'pointerUp', button: 0 }] }]);`);
-    } else if (step.action === "type" && hasSelector) {
-      if (bounds) {
-        const x = Math.round(bounds.x + bounds.width / 2);
-        const y = Math.round(bounds.y + bounds.height / 2);
-        lines.push(`    try {`);
-        lines.push(`      await __tapAt(driver, ${x}, ${y});`);
-        lines.push(`      await driver.pause(${MOBILE_FOCUS_SETTLE_MS});`);
-        lines.push(`      await __typeIntoFocused(driver, ${toJsStringLiteral(step.value ?? "")});`);
-        lines.push(`    } catch {`);
-        lines.push(`      await (await findFirst(driver, ${candidatesLiteral})).addValue(${toJsStringLiteral(step.value ?? "")});`);
-        lines.push(`    }`);
-      } else {
-        lines.push(`    await (await findFirst(driver, ${candidatesLiteral})).addValue(${toJsStringLiteral(step.value ?? "")});`);
-      }
-    } else if (step.action === "type" && bounds) {
-      const x = Math.round(bounds.x + bounds.width / 2);
-      const y = Math.round(bounds.y + bounds.height / 2);
-      lines.push(`    await __tapAt(driver, ${x}, ${y});`);
-      lines.push(`    await driver.pause(${MOBILE_FOCUS_SETTLE_MS});`);
-      lines.push(`    await __typeIntoFocused(driver, ${toJsStringLiteral(step.value ?? "")});`);
-    } else if (step.action === "clear" && hasSelector) {
-      lines.push(`    await (await findFirst(driver, ${candidatesLiteral})).clearValue();`);
-    } else if (step.action === "clear" && bounds) {
-      const x = Math.round(bounds.x + bounds.width / 2);
-      const y = Math.round(bounds.y + bounds.height / 2);
-      lines.push(`    await __tapAt(driver, ${x}, ${y});`);
-      lines.push(`    await driver.pause(${MOBILE_FOCUS_SETTLE_MS});`);
-      lines.push(`    await __clearFocused(driver);`);
+      const c = centerOf(bounds);
+      lines.push(`    await tapAt(driver, ${c.x}, ${c.y});`);
+    } else if (step.action === "type" && (hasSelector || bounds)) {
+      lines.push(`    await typeInto(driver, ${sel}, ${toJsStringLiteral(step.value ?? "")}${at});`);
+    } else if (step.action === "clear" && (hasSelector || bounds)) {
+      lines.push(`    await clearField(driver, ${sel}${at});`);
     } else if (step.action === "assertVisible" && hasSelector) {
-      lines.push(`    if (!(await (await findFirst(driver, ${candidatesLiteral})).isDisplayed())) {`);
-      lines.push(`      throw new Error('Assertion failed: element not displayed: ' + ${toJsStringLiteral(candidatesLiteral)});`);
-      lines.push(`    }`);
+      lines.push(`    await expectVisible(driver, ${sel});`);
     } else if (step.action === "assertText" && hasSelector) {
-      lines.push(`    {`);
-      lines.push(`      const __expected = ${toJsStringLiteral(step.assertion ?? "")};`);
-      lines.push(`      if (__expected.length === 0) throw new Error('assertText step is missing expected text');`);
-      lines.push(`      const __actual = await __textCandidates(await findFirst(driver, ${candidatesLiteral}));`);
-      lines.push(`      if (!__actual.some((__value) => __value.includes(__expected))) {`);
-      lines.push(`        throw new Error('Assertion failed: expected text to contain ' + JSON.stringify(__expected) + ' but got ' + JSON.stringify(__actual));`);
-      lines.push(`      }`);
-      lines.push(`    }`);
+      lines.push(`    await expectText(driver, ${sel}, ${toJsStringLiteral(step.assertion ?? "")});`);
     } else if (step.action === "back") {
       lines.push(`    await driver.back();`);
     } else if (step.action === "home") {
-      if (platform3 === "iOS") {
-        lines.push(`    await driver.execute('mobile: pressButton', { name: 'home' });`);
-      } else {
-        lines.push(`    await driver.pressKeyCode(3);`);
-      }
+      lines.push(platform3 === "iOS" ? `    await driver.execute('mobile: pressButton', { name: 'home' });` : `    await driver.pressKeyCode(3); // KEYCODE_HOME \u2014 same endpoint as record/replay`);
     } else if (step.action === "swipe" || step.action === "scroll") {
       const rawDir = nonEmpty(step.metadata?.direction);
       const swipeDir = rawDir && ["down", "left", "right"].includes(rawDir) ? rawDir : "up";
       const rawDist = step.metadata?.distance;
       const swipeDist = typeof rawDist === "number" && Number.isFinite(rawDist) && rawDist > 0 ? Math.min(rawDist, MOBILE_MAX_SWIPE_DISTANCE) : MOBILE_DEFAULT_SWIPE_DISTANCE;
-      const vertical = swipeDir === "up" || swipeDir === "down";
-      const startXExpr = swipeDir === "left" ? "__cx + __half" : swipeDir === "right" ? "__cx - __half" : "__cx";
-      const startYExpr = swipeDir === "up" ? "__cy + __half" : swipeDir === "down" ? "__cy - __half" : "__cy";
-      const endXExpr = swipeDir === "left" ? "__cx - __half" : swipeDir === "right" ? "__cx + __half" : "__cx";
-      const endYExpr = swipeDir === "up" ? "__cy - __half" : swipeDir === "down" ? "__cy + __half" : "__cy";
-      lines.push(`    {`);
-      lines.push(`      const __rect = await __getWindowRect(driver);`);
-      lines.push(`      const __w = __rect.width, __h = __rect.height;`);
-      lines.push(`      const __axis = ${vertical ? "__h" : "__w"};`);
-      lines.push(`      const __travel = Math.min(${swipeDist}, Math.max(1, Math.round(__axis * 0.8)));`);
-      lines.push(`      const __cx = Math.round(__w / 2), __cy = Math.round(__h / 2), __half = Math.round(__travel / 2);`);
-      lines.push(`      const __startX = ${startXExpr}, __startY = ${startYExpr};`);
-      lines.push(`      const __endX = ${endXExpr}, __endY = ${endYExpr};`);
-      lines.push(`      await driver.performActions([{ type: 'pointer', id: 'finger1', parameters: { pointerType: 'touch' }, actions: [{ type: 'pointerMove', duration: 0, x: __startX, y: __startY }, { type: 'pointerDown', button: 0 }, { type: 'pointerMove', duration: 300, x: __endX, y: __endY }, { type: 'pointerUp', button: 0 }] }]);`);
-      lines.push(`    }`);
+      lines.push(`    await swipe(driver, '${swipeDir}', ${swipeDist});`);
     } else if (step.action === "launchApp") {
-      lines.push(`    // App is launched by capabilities`);
+      lines.push(`    // App is launched by the capabilities above`);
     } else if (step.action === "waitForElement" && hasSelector) {
-      lines.push(`    await (await findFirst(driver, ${candidatesLiteral})).waitForExist({ timeout: 10000 });`);
+      lines.push(`    await (await find(driver, ${sel})).waitForExist({ timeout: 10000 });`);
     } else {
       lines.push(`    // Manual action required for: ${step.action}`);
     }
-    lines.push("");
     return lines;
   });
   return [
@@ -66590,6 +66599,7 @@ var require_mobile_generator = __commonJS({
 ## Rules
 - Re-snapshot before every assertion so the ref is fresh.
 - Assert the OUTCOME of the flow (the new screen / new content), not the control you just tapped.
+- Assert only DURABLE elements \u2014 screen chrome that exists on every visit (tab labels, headers, nav bars, the entity you just created). NEVER assert one-time / data-dependent UI: empty-state CTAs ("Add Your First \u2026", "Get Started", "No items yet"), onboarding banners, or counters \u2014 they vanish as soon as the account has data, and the test then fails forever on a healthy app.
 - Do NOT trigger irreversible side effects (real payments, sending messages to others) \u2014 note them and assert what you safely can.
 - Stay inside this app.${targetLine} Do not open or use app stores, browsers, email apps, settings, or any other app. If an action leaves the target app, the runner will relaunch the target app and reject that action.
 - Do ONLY the actions this scenario needs. Do NOT re-open a menu you already opened, re-select an option that is already selected, toggle a setting back and forth, or repeat a step that already succeeded \u2014 EVERY action you take is baked into the generated test verbatim, so each extra action becomes a permanent junk step.
@@ -67192,6 +67202,10 @@ ${statePacket}` },
         return null;
       const elements = snapshot.screen.elements;
       const stableAnchors = elements.filter((el) => hasStableId(el) && !isAlwaysPresentContainer(el));
+      stableAnchors.sort((a, b) => {
+        const labelled2 = (el) => nonEmpty2(el.text) || nonEmpty2(el.label) ? 0 : 1;
+        return labelled2(a) - labelled2(b);
+      });
       const contentfulNonButton = stableAnchors.find((el) => !/button/i.test(el.role) && (nonEmpty2(el.label) || nonEmpty2(el.text)));
       if (contentfulNonButton)
         return contentfulNonButton;
@@ -67980,6 +67994,7 @@ Reason over steps + error + tree + registry and return working healed steps. Do
 1. ERROR: which step failed, on what locator/assertion? "element not found"/"no such element" almost always means a WRONG LOCATOR on a screen that DOES exist \u2014 pick a stronger IDENTITY locator that is actually present in the captured tree: a resource-id, an accessibility-id/content-desc, or an EXACT @text= predicate (never a loose contains()). Do NOT declare a feature absent from one failed locator.
 2. STEP RESULTS: which steps passed before the failure.
 3. TREE: does the current screen match what the failed step expects?
+3b. STALE EMPTY-STATE ASSERT: a failing assert on one-time / data-dependent UI (empty-state CTAs like "Add Your First \u2026", "No items yet", onboarding banners) is NOT a locator problem \u2014 the element is gone because the account now has data. REPLACE the assertion with a durable landing-screen anchor (tab label, header, nav bar) that proves the same outcome (verdict fix).
 4. ENTRY-SCREEN DRIFT ("unexpected screen"/"screen drift"): the app started on a DIFFERENT screen than recorded; the fix is usually a MISSING NAVIGATION step (e.g. tap "Get Started" before the recorded first step). Author it from the tree if you can (verdict fix); if a single static tree is insufficient, return needs_device.
 ## Response \u2014 STRICT JSON, exactly one verdict:
 {"verdict":"fix","steps":[<FULL healed MobileTestStep array, all steps, your changes applied, order/metadata preserved>],"reason":"what changed and why","confidence":0.0-1.0}
@@ -68488,6 +68503,7 @@ The recorded flow may have expected a DIFFERENT starting screen than the one sho
 1. Compare the recorded first step's expected screen to the LIVE tree.
 2. If they differ, PREPEND the missing navigation step(s), authored from IDENTITY locators (resource-id, accessibility-id, or EXACT @text=) that are PRESENT in the LIVE tree \u2014 never a loose contains().
 3. If a locator is simply wrong, swap it for a stronger identity locator present in the LIVE tree.
+3b. If the failing step ASSERTS one-time / data-dependent UI (an empty-state CTA like "Add Your First \u2026") that is absent from the LIVE tree while the screen is otherwise correct, the assert is STALE \u2014 replace it with a durable element of the same screen (tab label, header, nav bar) and keep the rest.
 4. If you cannot yet SEE the screen you need, use "observe" to advance ONE step, then you will be re-shown the new live screen.
 ## Response \u2014 STRICT JSON, exactly one verdict:
 {"verdict":"fix","steps":[<FULL healed MobileTestStep array, all steps incl. any prepended navigation, order/metadata coherent>],"reason":"what changed and why","confidence":0.0-1.0}
@@ -329509,7 +329525,7 @@ var require_package4 = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@validate.qa/runner",
-      version: "1.0.25",
+      version: "1.0.27",
       description: "validate local test runner - execute Playwright tests on your machine, connected to validate.qa cloud.",
       bin: {
         "validate-runner": "dist/cli.js"

package/dist/cli.mjs

@@ -1034,9 +1034,39 @@ var require_mobile_source_parser = __commonJS({
     function isEditableElement(el) {
       return EDITABLE_CLASS_RE.test(el.role.trim());
     }
+    function xpathAttrLiteral(value) {
+      if (!value.includes("'"))
+        return `'${value}'`;
+      if (!value.includes('"'))
+        return `"${value}"`;
+      return `concat('${value.split("'").join(`', "'", '`)}')`;
+    }
+    function semanticXPath(el, platform3) {
+      const cls = nonBlank(el.role) ?? "*";
+      const a11y = nonBlank(el.accessibilityId);
+      if (a11y) {
+        return platform3 === "ANDROID" ? `//${cls}[@content-desc=${xpathAttrLiteral(a11y)}]` : `//${cls}[@name=${xpathAttrLiteral(a11y)}]`;
+      }
+      const rid = nonBlank(el.resourceId);
+      if (platform3 === "ANDROID" && rid)
+        return `//${cls}[@resource-id=${xpathAttrLiteral(rid)}]`;
+      const text = nonBlank(el.text);
+      if (text && !isEditableElement(el)) {
+        return platform3 === "ANDROID" ? `//${cls}[@text=${xpathAttrLiteral(text)}]` : `//${cls}[@label=${xpathAttrLiteral(text)}]`;
+      }
+      return void 0;
+    }
+    function nonBlank(value) {
+      if (typeof value !== "string")
+        return void 0;
+      const trimmed = value.trim();
+      return trimmed.length > 0 ? trimmed : void 0;
+    }
     function buildLocatorBundle(el, platform3) {
       const bundle = {
-        xpath: el.xpath,
+        // Attribute-anchored xpath when the element has identity; the absolute
+        // indexed path only for identity-less elements (nothing else can find them).
+        xpath: semanticXPath(el, platform3) ?? el.xpath,
         className: el.role
       };
       if (el.accessibilityId)
@@ -1549,7 +1579,7 @@ function buildStepTarget(metadata, selector) {
     locatorBundle.xpath,
     selector
   ];
-  const fallbacks = fallbackCandidates.map(nonEmpty).filter((value, index, list) => typeof value === "string" && value !== primary && list.indexOf(value) === index);
+  const fallbacks = fallbackCandidates.map(nonEmpty).filter((value, index, list) => typeof value === "string" && value !== primary && list.indexOf(value) === index).filter((value) => !value.startsWith("/hierarchy") && !(value.startsWith("/") && value.length > 120));
   return {
     primary,
     fallbacks,
@@ -1680,8 +1710,6 @@ function selectorCandidatesForStep(step) {
       candidates.push(`id=${bundle.resourceId}`);
     if (nonEmpty(bundle.xpath))
       candidates.push(bundle.xpath);
-    if (nonEmpty(bundle.className))
-      candidates.push(`class=${bundle.className}`);
   }
   if (nonEmpty(target.primary))
     candidates.push(selectorForValue(target.primary));
@@ -1689,7 +1717,7 @@ function selectorCandidatesForStep(step) {
     if (nonEmpty(fallback))
       candidates.push(selectorForValue(fallback));
   }
-  return candidates.filter((value, index, list) => list.indexOf(value) === index);
+  return candidates.filter((value) => !value.startsWith("/hierarchy") && !(value.startsWith("/") && !value.startsWith("//") && value.length > 120)).filter((value, index, list) => list.indexOf(value) === index).slice(0, 4);
 }
 function buildAppiumCode(testName, target, steps) {
   const appId = target?.appId ?? "com.example.app";
@@ -1699,74 +1727,118 @@ function buildAppiumCode(testName, target, steps) {
   const platformVersion = target?.platformVersion;
   const launchMode = target?.launchMode;
   const deeplink = target?.deeplink;
-  const hasSwipe = steps.some((s) => s.action === "swipe" || s.action === "scroll");
+  const boundsOf = (step) => step.metadata?.bounds;
+  const centerOf = (b) => ({ x: Math.round(b.x + b.width / 2), y: Math.round(b.y + b.height / 2) });
+  const atLiteral = (b) => {
+    const c = centerOf(b);
+    return `{ x: ${c.x}, y: ${c.y} }`;
+  };
+  const used = {
+    find: false,
+    tap: false,
+    tapAt: false,
+    typeInto: false,
+    clearField: false,
+    expectVisible: false,
+    expectText: false,
+    swipe: false,
+    wait: false
+  };
+  for (const step of steps) {
+    const hasSelector = selectorCandidatesForStep(step).length > 0;
+    const bounds = boundsOf(step);
+    switch (step.action) {
+      case "tap":
+        if (hasSelector) {
+          used.tap = true;
+          used.find = true;
+          if (bounds)
+            used.tapAt = true;
+        } else if (bounds)
+          used.tapAt = true;
+        break;
+      case "type":
+        used.typeInto = true;
+        if (hasSelector)
+          used.find = true;
+        if (bounds)
+          used.tapAt = true;
+        break;
+      case "clear":
+        used.clearField = true;
+        if (hasSelector)
+          used.find = true;
+        if (bounds)
+          used.tapAt = true;
+        break;
+      case "assertVisible":
+        if (hasSelector) {
+          used.expectVisible = true;
+          used.find = true;
+        }
+        break;
+      case "assertText":
+        if (hasSelector) {
+          used.expectText = true;
+          used.find = true;
+        }
+        break;
+      case "swipe":
+      case "scroll":
+        used.swipe = true;
+        break;
+      case "waitForElement":
+        if (hasSelector) {
+          used.wait = true;
+          used.find = true;
+        }
+        break;
+      default:
+        break;
+    }
+  }
+  const helperLines = [];
+  if (used.find)
+    helperLines.push(`// First selector that resolves wins \u2014 the runner's exact fallback chain.`, `async function find(driver: WebdriverIO.Browser, selectors: string[]) {`, `  for (const sel of selectors) {`, `    try { const el = await driver.$(sel); if (await el.isExisting()) return el; } catch { /* try next */ }`, `  }`, `  throw new Error('No locator resolved. Tried: ' + JSON.stringify(selectors));`, `}`, ``);
+  if (used.tapAt)
+    helperLines.push(`async function tapAt(driver: WebdriverIO.Browser, x: number, y: number) {`, `  await driver.performActions([{ type: 'pointer', id: 'finger1', parameters: { pointerType: 'touch' }, actions: [`, `    { type: 'pointerMove', duration: 0, x, y }, { type: 'pointerDown', button: 0 }, { type: 'pause', duration: 100 }, { type: 'pointerUp', button: 0 },`, `  ] }]);`, `}`, ``);
+  if (used.tap)
+    helperLines.push(`// Locator-first tap; falls back to the recorded coordinates like the runner.`, `async function tap(driver: WebdriverIO.Browser, selectors: string[], at?: { x: number; y: number }) {`, used.tapAt ? `  try { await (await find(driver, selectors)).click(); } catch (err) { if (!at) throw err; await tapAt(driver, at.x, at.y); }` : `  await (await find(driver, selectors)).click();`, `}`, ``);
+  if (used.typeInto)
+    helperLines.push(`// addValue (append) matches replay exactly; with recorded coordinates it`, `// taps to focus first (placeholder locators go stale once the keyboard opens).`, `async function typeInto(driver: WebdriverIO.Browser, selectors: string[], text: string, at?: { x: number; y: number }) {`, ...used.tapAt ? [
+      `  if (at) {`,
+      `    try {`,
+      `      await tapAt(driver, at.x, at.y);`,
+      `      await driver.pause(${MOBILE_FOCUS_SETTLE_MS});`,
+      `      await (await driver.getActiveElement() as unknown as WebdriverIO.Element).addValue(text);`,
+      `      return;`,
+      `    } catch { /* fall through to locator path */ }`,
+      `  }`
+    ] : [], `  await (await find(driver, selectors)).addValue(text);`, `}`, ``);
+  if (used.clearField)
+    helperLines.push(`async function clearField(driver: WebdriverIO.Browser, selectors: string[], at?: { x: number; y: number }) {`, ...used.tapAt ? [
+      `  if (at) {`,
+      `    try {`,
+      `      await tapAt(driver, at.x, at.y);`,
+      `      await driver.pause(${MOBILE_FOCUS_SETTLE_MS});`,
+      `      await (await driver.getActiveElement() as unknown as WebdriverIO.Element).clearValue();`,
+      `      return;`,
+      `    } catch { /* fall through to locator path */ }`,
+      `  }`
+    ] : [], `  await (await find(driver, selectors)).clearValue();`, `}`, ``);
+  if (used.expectVisible)
+    helperLines.push(`async function expectVisible(driver: WebdriverIO.Browser, selectors: string[]) {`, `  if (!(await (await find(driver, selectors)).isDisplayed())) {`, `    throw new Error('Assertion failed: element not displayed: ' + JSON.stringify(selectors));`, `  }`, `}`, ``);
+  if (used.expectText)
+    helperLines.push(`// Contains-match over text-like attributes \u2014 mirrors the runtime executor.`, `async function expectText(driver: WebdriverIO.Browser, selectors: string[], expected: string) {`, `  if (expected.length === 0) throw new Error('assertText step is missing expected text');`, `  const el = await find(driver, selectors);`, `  const values: string[] = [];`, `  const push = (v: unknown) => { if (typeof v === 'string' && v.trim() && !values.includes(v.trim())) values.push(v.trim()); };`, `  push(await el.getText().catch(() => ''));`, `  for (const attr of ['text', 'content-desc', 'contentDescription', 'name', 'label', 'value']) push(await el.getAttribute(attr).catch(() => ''));`, `  if (!values.some((v) => v.includes(expected))) {`, `    throw new Error('Assertion failed: expected text to contain ' + JSON.stringify(expected) + ' but got ' + JSON.stringify(values));`, `  }`, `}`, ``);
+  if (used.swipe)
+    helperLines.push(`// Centred W3C swipe with the executor's geometry (full distance, clamped to 80% of the axis).`, `async function swipe(driver: WebdriverIO.Browser, direction: 'up' | 'down' | 'left' | 'right', distance: number) {`, `  let rect: { width: number; height: number } | undefined;`, `  for (let i = 0; i < 3 && !rect; i++) {`, `    try { const r = await driver.getWindowRect(); if (r && r.width > 0 && r.height > 0) rect = r; } catch { await driver.pause(Math.pow(2, i) * 100); }`, `  }`, `  if (!rect) throw new Error('Could not determine device window size');`, `  const vertical = direction === 'up' || direction === 'down';`, `  const travel = Math.min(distance, Math.max(1, Math.round((vertical ? rect.height : rect.width) * 0.8)));`, `  const cx = Math.round(rect.width / 2), cy = Math.round(rect.height / 2), half = Math.round(travel / 2);`, `  const sx = direction === 'left' ? cx + half : direction === 'right' ? cx - half : cx;`, `  const sy = direction === 'up' ? cy + half : direction === 'down' ? cy - half : cy;`, `  const ex = direction === 'left' ? cx - half : direction === 'right' ? cx + half : cx;`, `  const ey = direction === 'up' ? cy - half : direction === 'down' ? cy + half : cy;`, `  await driver.performActions([{ type: 'pointer', id: 'finger1', parameters: { pointerType: 'touch' }, actions: [`, `    { type: 'pointerMove', duration: 0, x: sx, y: sy }, { type: 'pointerDown', button: 0 }, { type: 'pointerMove', duration: 300, x: ex, y: ey }, { type: 'pointerUp', button: 0 },`, `  ] }]);`, `}`, ``);
   const setupLines = [
-    `// Standalone WebdriverIO script \u2014 runnable as-is with \`node\`/\`tsx\`.`,
-    `// Prerequisites:`,
-    `//   1. npm i webdriverio`,
-    `//   2. An Appium server reachable on http://localhost:4723`,
-    `//   3. A booted device/simulator matching the capabilities below`,
-    `// This is NOT a WDIO testrunner spec: it uses the standalone remote() client`,
-    `// (driver.$, no auto-injected $/expect/describe globals) so it has no harness`,
-    `// dependency and runs with a plain \`tsx ${toInlineCommentText(testName)}.spec.ts\`.`,
+    `// ${toInlineCommentText(testName)} \u2014 ${steps.length} step(s), exported from validate.qa.`,
+    `// Runnable standalone: \`npm i webdriverio\`, Appium on :4723, booted device. The`,
+    `// canonical execution source is the steps JSON; this script mirrors it 1:1.`,
     `import { remote } from 'webdriverio';`,
     ``,
-    `// Resolve the first selector that exists, mirroring the runner's locator`,
-    `// fallback chain so a stale primary the runner would recover from doesn't fail`,
-    `// the exported script.`,
-    `async function findFirst(driver: WebdriverIO.Browser, selectors: string[]) {`,
-    `  let __lastError: unknown;`,
-    `  for (const __sel of selectors) {`,
-    `    try {`,
-    `      const __el = await driver.$(__sel);`,
-    `      if (await __el.isExisting()) return __el;`,
-    `    } catch (err) { __lastError = err; }`,
-    `  }`,
-    `  throw new Error('No locator resolved. Tried: ' + JSON.stringify(selectors) + (__lastError ? ' (last error: ' + String(__lastError) + ')' : ''));`,
-    `}`,
-    ``,
-    `async function __tapAt(driver: WebdriverIO.Browser, x: number, y: number) {`,
-    `  await driver.performActions([{ type: 'pointer', id: 'finger1', parameters: { pointerType: 'touch' }, actions: [{ type: 'pointerMove', duration: 0, x, y }, { type: 'pointerDown', button: 0 }, { type: 'pause', duration: 100 }, { type: 'pointerUp', button: 0 }] }]);`,
-    `}`,
-    ``,
-    `async function __typeIntoFocused(driver: WebdriverIO.Browser, text: string) {`,
-    `  try {`,
-    `    await (await driver.getActiveElement() as unknown as WebdriverIO.Element).addValue(text);`,
-    `  } catch {`,
-    `    await driver.keys(text);`,
-    `  }`,
-    `}`,
-    ``,
-    `async function __clearFocused(driver: WebdriverIO.Browser) {`,
-    `  await (await driver.getActiveElement() as unknown as WebdriverIO.Element).clearValue();`,
-    `}`,
-    ``,
-    `async function __textCandidates(el: WebdriverIO.Element) {`,
-    `  const __values: string[] = [];`,
-    `  const __push = (__value: unknown) => {`,
-    `    if (typeof __value !== 'string') return;`,
-    `    const __trimmed = __value.trim();`,
-    `    if (__trimmed.length === 0 || __values.includes(__trimmed)) return;`,
-    `    __values.push(__trimmed);`,
-    `  };`,
-    `  __push(await el.getText().catch(() => ''));`,
-    `  for (const __attr of ['text', 'content-desc', 'contentDescription', 'name', 'label', 'value']) {`,
-    `    __push(await el.getAttribute(__attr).catch(() => ''));`,
-    `  }`,
-    `  return __values;`,
-    `}`,
-    ...hasSwipe ? [
-      ``,
-      `// Read the device window with a few retries (matches the runtime executor).`,
-      `async function __getWindowRect(driver: WebdriverIO.Browser) {`,
-      `  for (let __i = 0; __i < 3; __i++) {`,
-      `    try { const __r = await driver.getWindowRect(); if (__r && __r.width > 0 && __r.height > 0) return __r; } catch { /* retry */ }`,
-      `    await driver.pause(Math.pow(2, __i) * 100);`,
-      `  }`,
-      `  throw new Error('Could not determine device window size');`,
-      `}`
-    ] : [],
-    ``,
+    ...helperLines,
     `async function main() {`,
     `  const driver = await remote({`,
     `    path: '/',`,
@@ -1787,108 +1859,45 @@ function buildAppiumCode(testName, target, steps) {
       `    // the same entry screen as during recording.`,
       platform3 === "iOS" ? `    await driver.execute('mobile: deepLink', { url: ${toJsStringLiteral(deeplink)}, bundleId: ${toJsStringLiteral(appId)} });` : `    await driver.execute('mobile: deepLink', { url: ${toJsStringLiteral(deeplink)}, package: ${toJsStringLiteral(appId)} });`,
       ``
-    ] : [],
-    `    // Canonical execution source: steps JSON`
+    ] : []
   ];
   const stepLines = steps.flatMap((step) => {
-    const lines = [`    // Step ${step.order + 1}: ${toInlineCommentText(step.description)}`];
+    const lines = [`    // ${step.order + 1}. ${toInlineCommentText(step.description)}`];
     const candidates = selectorCandidatesForStep(step);
-    const candidatesLiteral = `[${candidates.map(toJsStringLiteral).join(", ")}]`;
+    const sel = `[${candidates.map(toJsStringLiteral).join(", ")}]`;
     const hasSelector = candidates.length > 0;
-    const bounds = step.metadata?.bounds;
+    const bounds = boundsOf(step);
+    const at = bounds ? `, ${atLiteral(bounds)}` : "";
     if (step.action === "tap" && hasSelector) {
-      if (bounds) {
-        const x = Math.round(bounds.x + bounds.width / 2);
-        const y = Math.round(bounds.y + bounds.height / 2);
-        lines.push(`    try {`);
-        lines.push(`      await (await findFirst(driver, ${candidatesLiteral})).click();`);
-        lines.push(`    } catch {`);
-        lines.push(`      await driver.performActions([{ type: 'pointer', id: 'finger1', parameters: { pointerType: 'touch' }, actions: [{ type: 'pointerMove', duration: 0, x: ${x}, y: ${y} }, { type: 'pointerDown', button: 0 }, { type: 'pause', duration: 100 }, { type: 'pointerUp', button: 0 }] }]);`);
-        lines.push(`    }`);
-      } else {
-        lines.push(`    await (await findFirst(driver, ${candidatesLiteral})).click();`);
-      }
+      lines.push(`    await tap(driver, ${sel}${at});`);
     } else if (step.action === "tap" && bounds) {
-      const x = Math.round(bounds.x + bounds.width / 2);
-      const y = Math.round(bounds.y + bounds.height / 2);
-      lines.push(`    await driver.performActions([{ type: 'pointer', id: 'finger1', parameters: { pointerType: 'touch' }, actions: [{ type: 'pointerMove', duration: 0, x: ${x}, y: ${y} }, { type: 'pointerDown', button: 0 }, { type: 'pause', duration: 100 }, { type: 'pointerUp', button: 0 }] }]);`);
-    } else if (step.action === "type" && hasSelector) {
-      if (bounds) {
-        const x = Math.round(bounds.x + bounds.width / 2);
-        const y = Math.round(bounds.y + bounds.height / 2);
-        lines.push(`    try {`);
-        lines.push(`      await __tapAt(driver, ${x}, ${y});`);
-        lines.push(`      await driver.pause(${MOBILE_FOCUS_SETTLE_MS});`);
-        lines.push(`      await __typeIntoFocused(driver, ${toJsStringLiteral(step.value ?? "")});`);
-        lines.push(`    } catch {`);
-        lines.push(`      await (await findFirst(driver, ${candidatesLiteral})).addValue(${toJsStringLiteral(step.value ?? "")});`);
-        lines.push(`    }`);
-      } else {
-        lines.push(`    await (await findFirst(driver, ${candidatesLiteral})).addValue(${toJsStringLiteral(step.value ?? "")});`);
-      }
-    } else if (step.action === "type" && bounds) {
-      const x = Math.round(bounds.x + bounds.width / 2);
-      const y = Math.round(bounds.y + bounds.height / 2);
-      lines.push(`    await __tapAt(driver, ${x}, ${y});`);
-      lines.push(`    await driver.pause(${MOBILE_FOCUS_SETTLE_MS});`);
-      lines.push(`    await __typeIntoFocused(driver, ${toJsStringLiteral(step.value ?? "")});`);
-    } else if (step.action === "clear" && hasSelector) {
-      lines.push(`    await (await findFirst(driver, ${candidatesLiteral})).clearValue();`);
-    } else if (step.action === "clear" && bounds) {
-      const x = Math.round(bounds.x + bounds.width / 2);
-      const y = Math.round(bounds.y + bounds.height / 2);
-      lines.push(`    await __tapAt(driver, ${x}, ${y});`);
-      lines.push(`    await driver.pause(${MOBILE_FOCUS_SETTLE_MS});`);
-      lines.push(`    await __clearFocused(driver);`);
+      const c = centerOf(bounds);
+      lines.push(`    await tapAt(driver, ${c.x}, ${c.y});`);
+    } else if (step.action === "type" && (hasSelector || bounds)) {
+      lines.push(`    await typeInto(driver, ${sel}, ${toJsStringLiteral(step.value ?? "")}${at});`);
+    } else if (step.action === "clear" && (hasSelector || bounds)) {
+      lines.push(`    await clearField(driver, ${sel}${at});`);
     } else if (step.action === "assertVisible" && hasSelector) {
-      lines.push(`    if (!(await (await findFirst(driver, ${candidatesLiteral})).isDisplayed())) {`);
-      lines.push(`      throw new Error('Assertion failed: element not displayed: ' + ${toJsStringLiteral(candidatesLiteral)});`);
-      lines.push(`    }`);
+      lines.push(`    await expectVisible(driver, ${sel});`);
     } else if (step.action === "assertText" && hasSelector) {
-      lines.push(`    {`);
-      lines.push(`      const __expected = ${toJsStringLiteral(step.assertion ?? "")};`);
-      lines.push(`      if (__expected.length === 0) throw new Error('assertText step is missing expected text');`);
-      lines.push(`      const __actual = await __textCandidates(await findFirst(driver, ${candidatesLiteral}));`);
-      lines.push(`      if (!__actual.some((__value) => __value.includes(__expected))) {`);
-      lines.push(`        throw new Error('Assertion failed: expected text to contain ' + JSON.stringify(__expected) + ' but got ' + JSON.stringify(__actual));`);
-      lines.push(`      }`);
-      lines.push(`    }`);
+      lines.push(`    await expectText(driver, ${sel}, ${toJsStringLiteral(step.assertion ?? "")});`);
     } else if (step.action === "back") {
       lines.push(`    await driver.back();`);
     } else if (step.action === "home") {
-      if (platform3 === "iOS") {
-        lines.push(`    await driver.execute('mobile: pressButton', { name: 'home' });`);
-      } else {
-        lines.push(`    await driver.pressKeyCode(3);`);
-      }
+      lines.push(platform3 === "iOS" ? `    await driver.execute('mobile: pressButton', { name: 'home' });` : `    await driver.pressKeyCode(3); // KEYCODE_HOME \u2014 same endpoint as record/replay`);
     } else if (step.action === "swipe" || step.action === "scroll") {
       const rawDir = nonEmpty(step.metadata?.direction);
       const swipeDir = rawDir && ["down", "left", "right"].includes(rawDir) ? rawDir : "up";
       const rawDist = step.metadata?.distance;
       const swipeDist = typeof rawDist === "number" && Number.isFinite(rawDist) && rawDist > 0 ? Math.min(rawDist, MOBILE_MAX_SWIPE_DISTANCE) : MOBILE_DEFAULT_SWIPE_DISTANCE;
-      const vertical = swipeDir === "up" || swipeDir === "down";
-      const startXExpr = swipeDir === "left" ? "__cx + __half" : swipeDir === "right" ? "__cx - __half" : "__cx";
-      const startYExpr = swipeDir === "up" ? "__cy + __half" : swipeDir === "down" ? "__cy - __half" : "__cy";
-      const endXExpr = swipeDir === "left" ? "__cx - __half" : swipeDir === "right" ? "__cx + __half" : "__cx";
-      const endYExpr = swipeDir === "up" ? "__cy - __half" : swipeDir === "down" ? "__cy + __half" : "__cy";
-      lines.push(`    {`);
-      lines.push(`      const __rect = await __getWindowRect(driver);`);
-      lines.push(`      const __w = __rect.width, __h = __rect.height;`);
-      lines.push(`      const __axis = ${vertical ? "__h" : "__w"};`);
-      lines.push(`      const __travel = Math.min(${swipeDist}, Math.max(1, Math.round(__axis * 0.8)));`);
-      lines.push(`      const __cx = Math.round(__w / 2), __cy = Math.round(__h / 2), __half = Math.round(__travel / 2);`);
-      lines.push(`      const __startX = ${startXExpr}, __startY = ${startYExpr};`);
-      lines.push(`      const __endX = ${endXExpr}, __endY = ${endYExpr};`);
-      lines.push(`      await driver.performActions([{ type: 'pointer', id: 'finger1', parameters: { pointerType: 'touch' }, actions: [{ type: 'pointerMove', duration: 0, x: __startX, y: __startY }, { type: 'pointerDown', button: 0 }, { type: 'pointerMove', duration: 300, x: __endX, y: __endY }, { type: 'pointerUp', button: 0 }] }]);`);
-      lines.push(`    }`);
+      lines.push(`    await swipe(driver, '${swipeDir}', ${swipeDist});`);
     } else if (step.action === "launchApp") {
-      lines.push(`    // App is launched by capabilities`);
+      lines.push(`    // App is launched by the capabilities above`);
     } else if (step.action === "waitForElement" && hasSelector) {
-      lines.push(`    await (await findFirst(driver, ${candidatesLiteral})).waitForExist({ timeout: 10000 });`);
+      lines.push(`    await (await find(driver, ${sel})).waitForExist({ timeout: 10000 });`);
     } else {
       lines.push(`    // Manual action required for: ${step.action}`);
     }
-    lines.push("");
     return lines;
   });
   return [
@@ -66595,6 +66604,7 @@ var require_mobile_generator = __commonJS({
 ## Rules
 - Re-snapshot before every assertion so the ref is fresh.
 - Assert the OUTCOME of the flow (the new screen / new content), not the control you just tapped.
+- Assert only DURABLE elements \u2014 screen chrome that exists on every visit (tab labels, headers, nav bars, the entity you just created). NEVER assert one-time / data-dependent UI: empty-state CTAs ("Add Your First \u2026", "Get Started", "No items yet"), onboarding banners, or counters \u2014 they vanish as soon as the account has data, and the test then fails forever on a healthy app.
 - Do NOT trigger irreversible side effects (real payments, sending messages to others) \u2014 note them and assert what you safely can.
 - Stay inside this app.${targetLine} Do not open or use app stores, browsers, email apps, settings, or any other app. If an action leaves the target app, the runner will relaunch the target app and reject that action.
 - Do ONLY the actions this scenario needs. Do NOT re-open a menu you already opened, re-select an option that is already selected, toggle a setting back and forth, or repeat a step that already succeeded \u2014 EVERY action you take is baked into the generated test verbatim, so each extra action becomes a permanent junk step.
@@ -67197,6 +67207,10 @@ ${statePacket}` },
         return null;
       const elements = snapshot.screen.elements;
       const stableAnchors = elements.filter((el) => hasStableId(el) && !isAlwaysPresentContainer(el));
+      stableAnchors.sort((a, b) => {
+        const labelled2 = (el) => nonEmpty2(el.text) || nonEmpty2(el.label) ? 0 : 1;
+        return labelled2(a) - labelled2(b);
+      });
       const contentfulNonButton = stableAnchors.find((el) => !/button/i.test(el.role) && (nonEmpty2(el.label) || nonEmpty2(el.text)));
       if (contentfulNonButton)
         return contentfulNonButton;
@@ -67985,6 +67999,7 @@ Reason over steps + error + tree + registry and return working healed steps. Do
 1. ERROR: which step failed, on what locator/assertion? "element not found"/"no such element" almost always means a WRONG LOCATOR on a screen that DOES exist \u2014 pick a stronger IDENTITY locator that is actually present in the captured tree: a resource-id, an accessibility-id/content-desc, or an EXACT @text= predicate (never a loose contains()). Do NOT declare a feature absent from one failed locator.
 2. STEP RESULTS: which steps passed before the failure.
 3. TREE: does the current screen match what the failed step expects?
+3b. STALE EMPTY-STATE ASSERT: a failing assert on one-time / data-dependent UI (empty-state CTAs like "Add Your First \u2026", "No items yet", onboarding banners) is NOT a locator problem \u2014 the element is gone because the account now has data. REPLACE the assertion with a durable landing-screen anchor (tab label, header, nav bar) that proves the same outcome (verdict fix).
 4. ENTRY-SCREEN DRIFT ("unexpected screen"/"screen drift"): the app started on a DIFFERENT screen than recorded; the fix is usually a MISSING NAVIGATION step (e.g. tap "Get Started" before the recorded first step). Author it from the tree if you can (verdict fix); if a single static tree is insufficient, return needs_device.
 ## Response \u2014 STRICT JSON, exactly one verdict:
 {"verdict":"fix","steps":[<FULL healed MobileTestStep array, all steps, your changes applied, order/metadata preserved>],"reason":"what changed and why","confidence":0.0-1.0}
@@ -68493,6 +68508,7 @@ The recorded flow may have expected a DIFFERENT starting screen than the one sho
 1. Compare the recorded first step's expected screen to the LIVE tree.
 2. If they differ, PREPEND the missing navigation step(s), authored from IDENTITY locators (resource-id, accessibility-id, or EXACT @text=) that are PRESENT in the LIVE tree \u2014 never a loose contains().
 3. If a locator is simply wrong, swap it for a stronger identity locator present in the LIVE tree.
+3b. If the failing step ASSERTS one-time / data-dependent UI (an empty-state CTA like "Add Your First \u2026") that is absent from the LIVE tree while the screen is otherwise correct, the assert is STALE \u2014 replace it with a durable element of the same screen (tab label, header, nav bar) and keep the rest.
 4. If you cannot yet SEE the screen you need, use "observe" to advance ONE step, then you will be re-shown the new live screen.
 ## Response \u2014 STRICT JSON, exactly one verdict:
 {"verdict":"fix","steps":[<FULL healed MobileTestStep array, all steps incl. any prepended navigation, order/metadata coherent>],"reason":"what changed and why","confidence":0.0-1.0}
@@ -329514,7 +329530,7 @@ var require_package4 = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@validate.qa/runner",
-      version: "1.0.25",
+      version: "1.0.27",
       description: "validate local test runner - execute Playwright tests on your machine, connected to validate.qa cloud.",
       bin: {
         "validate-runner": "dist/cli.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@validate.qa/runner",
-  "version": "1.0.25",
+  "version": "1.0.27",
   "description": "validate local test runner - execute Playwright tests on your machine, connected to validate.qa cloud.",
   "bin": {
     "validate-runner": "dist/cli.js"