@validate.qa/runner 1.0.26 → 1.0.28

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 [
@@ -65779,6 +65788,7 @@ Return ONLY one valid JSON object matching the schema below. Do NOT include <thi
 8. **Auth-aware** - mark scenarios that need a signed-in session. Use process.env.TEST_USER_EMAIL / PASSWORD
 9. **No duplicates** - check existing test names before adding
 10. **All tests start from a hermetic app launch** - every generated test relaunches the app (terminate + activate, a clean cold start) and uses the app's own in-app navigation (tapping tabs / links / buttons) to reach the target screen. Steps must reflect this: say "Relaunch the app and tap Sign In" not "deep-link to the login screen". Do NOT navigate by deep-link; the app's launch + tab/drawer navigation is the only entry path. \`targetPages\` lists the screen-ids involved in the flow.
+12. **targetPages must be copied CHARACTER-FOR-CHARACTER from the screen-ids in the evidence** (they look like \`com.example.app.MainActivity#ab12cd34\`). NEVER invent, prettify, or abbreviate them \u2014 no "Landing", "AUTH", "Home Screen", or any name that is not literally in the provided screens. A scenario whose targetPages contains even ONE id not present in the evidence is REJECTED WHOLESALE by the validator, so a single made-up route silently destroys the entire scenario. If you are unsure which screen-id a step touches, use the screen-id of the screen where the flow STARTS.
 11. **Happy paths must verify the DURABLE OUTCOME, not just the trigger.** A HAPPY_PATH is NOT complete until it verifies the feature's real output. "Button tapped" / "Sheet opened" / "Spinner appeared" is NOT a happy path - that is a UI interaction test. Apply this to any feature where an action produces a result the user then sees or uses: CRUD creates, photo/file uploads, searches that return results, imports, exports, payments, messages sent, AI/ML outputs, generated documents, sync runs, analysis runs, conversion, data processing. The scenario MUST include:
     - The trigger step (Tap Submit / Generate / Send / Upload / Run / Analyze / Save / Pay / etc.)
     - A wait step for the operation to complete. Phrase it by SIGNAL, not wall-clock ("Wait for the result to appear - up to 60 seconds"). Prefer signals the app actually uses: spinner disappears, status badge flips to a success state, a new row appears, an item count increments, a success toast/snackbar shows, the screen transitions to a result screen.
@@ -67193,6 +67203,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;
@@ -329512,7 +329526,7 @@ var require_package4 = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@validate.qa/runner",
-      version: "1.0.26",
+      version: "1.0.28",
       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 [
@@ -65784,6 +65793,7 @@ Return ONLY one valid JSON object matching the schema below. Do NOT include <thi
 8. **Auth-aware** - mark scenarios that need a signed-in session. Use process.env.TEST_USER_EMAIL / PASSWORD
 9. **No duplicates** - check existing test names before adding
 10. **All tests start from a hermetic app launch** - every generated test relaunches the app (terminate + activate, a clean cold start) and uses the app's own in-app navigation (tapping tabs / links / buttons) to reach the target screen. Steps must reflect this: say "Relaunch the app and tap Sign In" not "deep-link to the login screen". Do NOT navigate by deep-link; the app's launch + tab/drawer navigation is the only entry path. \`targetPages\` lists the screen-ids involved in the flow.
+12. **targetPages must be copied CHARACTER-FOR-CHARACTER from the screen-ids in the evidence** (they look like \`com.example.app.MainActivity#ab12cd34\`). NEVER invent, prettify, or abbreviate them \u2014 no "Landing", "AUTH", "Home Screen", or any name that is not literally in the provided screens. A scenario whose targetPages contains even ONE id not present in the evidence is REJECTED WHOLESALE by the validator, so a single made-up route silently destroys the entire scenario. If you are unsure which screen-id a step touches, use the screen-id of the screen where the flow STARTS.
 11. **Happy paths must verify the DURABLE OUTCOME, not just the trigger.** A HAPPY_PATH is NOT complete until it verifies the feature's real output. "Button tapped" / "Sheet opened" / "Spinner appeared" is NOT a happy path - that is a UI interaction test. Apply this to any feature where an action produces a result the user then sees or uses: CRUD creates, photo/file uploads, searches that return results, imports, exports, payments, messages sent, AI/ML outputs, generated documents, sync runs, analysis runs, conversion, data processing. The scenario MUST include:
     - The trigger step (Tap Submit / Generate / Send / Upload / Run / Analyze / Save / Pay / etc.)
     - A wait step for the operation to complete. Phrase it by SIGNAL, not wall-clock ("Wait for the result to appear - up to 60 seconds"). Prefer signals the app actually uses: spinner disappears, status badge flips to a success state, a new row appears, an item count increments, a success toast/snackbar shows, the screen transitions to a result screen.
@@ -67198,6 +67208,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;
@@ -329517,7 +329531,7 @@ var require_package4 = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@validate.qa/runner",
-      version: "1.0.26",
+      version: "1.0.28",
       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.26",
+  "version": "1.0.28",
   "description": "validate local test runner - execute Playwright tests on your machine, connected to validate.qa cloud.",
   "bin": {
     "validate-runner": "dist/cli.js"