@validate.qa/runner 1.0.67 → 1.0.68

package/dist/cli.js

@@ -978,7 +978,7 @@ var require_mobile_source_parser = __commonJS({
       const value = nonEmpty3(attrs.value);
       const label = name ?? labelAttr ?? value;
       const accessibilityId = name;
-      const text = value && value !== label ? value : labelAttr && labelAttr !== label ? labelAttr : void 0;
+      const text = labelAttr ?? (isStateValueRole(role) ? void 0 : value);
       const bounds = parseIOSBounds(attrs);
       const enabled = attrBoolDefaultTrue(attrs.enabled);
       const visible = attrBoolDefaultTrue(attrs.visible);
@@ -1125,6 +1125,42 @@ var require_mobile_source_parser = __commonJS({
         }
       }
     }
+    function annotateIdentityUniqueness(elements) {
+      const a11yCounts = /* @__PURE__ */ new Map();
+      const ridCounts = /* @__PURE__ */ new Map();
+      const textCounts = /* @__PURE__ */ new Map();
+      const bump = (map2, value) => {
+        const key = value?.trim();
+        if (!key)
+          return;
+        map2.set(key, (map2.get(key) ?? 0) + 1);
+      };
+      for (const element of elements) {
+        bump(a11yCounts, element.accessibilityId);
+        bump(ridCounts, element.resourceId);
+        const identityValues = new Set([element.text, element.accessibilityId].map((value) => value?.trim()).filter((value) => Boolean(value)));
+        for (const value of identityValues)
+          bump(textCounts, value);
+      }
+      const isUnique = (map2, value) => {
+        const key = value?.trim();
+        if (!key)
+          return void 0;
+        return (map2.get(key) ?? 0) <= 1;
+      };
+      for (const element of elements) {
+        const accessibilityId = isUnique(a11yCounts, element.accessibilityId);
+        const resourceId = isUnique(ridCounts, element.resourceId);
+        const text = isUnique(textCounts, element.text);
+        if (accessibilityId === void 0 && resourceId === void 0 && text === void 0)
+          continue;
+        element.identityUnique = {
+          ...accessibilityId !== void 0 ? { accessibilityId } : {},
+          ...resourceId !== void 0 ? { resourceId } : {},
+          ...text !== void 0 ? { text } : {}
+        };
+      }
+    }
     function flatten(root, platform3) {
       const out = [];
       const stack = [];
@@ -1170,6 +1206,7 @@ var require_mobile_source_parser = __commonJS({
         }
       }
       markRepeatedBottomBarNavigation(out);
+      annotateIdentityUniqueness(out);
       return out;
     }
     function fnv1a(input) {
@@ -1251,6 +1288,13 @@ var require_mobile_source_parser = __commonJS({
     function isEditableElement(el) {
       return EDITABLE_CLASS_RE.test(el.role.trim());
     }
+    var STATE_VALUE_CLASS_RE = /(XCUIElementTypeSwitch|XCUIElementTypeToggle|XCUIElementTypeSlider|XCUIElementTypeStepper|XCUIElementTypePageIndicator|XCUIElementTypeProgressIndicator|XCUIElementTypeSegmentedControl|XCUIElementTypePicker|XCUIElementTypePickerWheel|ToggleButton|SeekBar|ProgressBar|RatingBar|NumberPicker)$/;
+    function isStateValueRole(role) {
+      return STATE_VALUE_CLASS_RE.test(role.trim());
+    }
+    function isStateValueElement(el) {
+      return isStateValueRole(el.role);
+    }
     function xpathAttrLiteral(value) {
       if (!value.includes("'"))
         return `'${value}'`;
@@ -1261,17 +1305,18 @@ var require_mobile_source_parser = __commonJS({
     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;
+      const rid = platform3 === "ANDROID" ? nonBlank(el.resourceId) : void 0;
+      const text = isEditableElement(el) || isStateValueElement(el) ? void 0 : nonBlank(el.text);
+      const a11yXpath = a11y ? platform3 === "ANDROID" ? `//${cls}[@content-desc=${xpathAttrLiteral(a11y)}]` : `//${cls}[@name=${xpathAttrLiteral(a11y)}]` : void 0;
+      const ridXpath = rid ? `//${cls}[@resource-id=${xpathAttrLiteral(rid)}]` : void 0;
+      const textXpath = text ? platform3 === "ANDROID" ? `//${cls}[@text=${xpathAttrLiteral(text)}]` : `//${cls}[@label=${xpathAttrLiteral(text)}]` : void 0;
+      const candidates = [
+        { xpath: a11yXpath, unique: el.identityUnique?.accessibilityId },
+        { xpath: ridXpath, unique: el.identityUnique?.resourceId },
+        { xpath: textXpath, unique: el.identityUnique?.text }
+      ];
+      const uniqueFirst = candidates.find((c) => c.xpath && c.unique !== false);
+      return (uniqueFirst ?? candidates.find((c) => c.xpath))?.xpath;
     }
     function nonBlank(value) {
       if (typeof value !== "string")
@@ -1280,30 +1325,40 @@ var require_mobile_source_parser = __commonJS({
       return trimmed.length > 0 ? trimmed : void 0;
     }
     function buildLocatorBundle(el, platform3) {
+      const durableText = el.text && !isEditableElement(el) && !isStateValueElement(el) ? el.text : void 0;
       const bundle = {
         // 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)
+      const a11yUnique = el.identityUnique?.accessibilityId !== false;
+      const ridUnique = el.identityUnique?.resourceId !== false;
+      const textUnique = el.identityUnique?.text !== false;
+      const hasUniqueAlternativeToA11y = Boolean(el.resourceId && platform3 === "ANDROID" && ridUnique || durableText && textUnique);
+      const hasUniqueAlternativeToRid = Boolean(el.accessibilityId && a11yUnique || durableText && textUnique);
+      const includeA11y = Boolean(el.accessibilityId && (a11yUnique || !hasUniqueAlternativeToA11y));
+      const includeRid = Boolean(platform3 === "ANDROID" && el.resourceId && (ridUnique || !hasUniqueAlternativeToRid));
+      if (includeA11y && el.accessibilityId)
         bundle.accessibilityId = el.accessibilityId;
-      if (platform3 === "ANDROID" && el.resourceId)
+      if (includeRid && el.resourceId)
         bundle.resourceId = el.resourceId;
-      if (el.text && !isEditableElement(el))
-        bundle.text = el.text;
-      if (platform3 === "ANDROID" && el.accessibilityId)
+      if (durableText)
+        bundle.text = durableText;
+      if (includeA11y && platform3 === "ANDROID" && el.accessibilityId)
         bundle.contentDesc = el.accessibilityId;
       return bundle;
     }
     function preferredLocator(el) {
-      if (el.accessibilityId)
-        return el.accessibilityId;
-      if (el.resourceId)
-        return el.resourceId;
-      if (el.text && !isEditableElement(el))
-        return el.text;
-      return el.xpath;
+      const durableText = el.text && !isEditableElement(el) && !isStateValueElement(el) ? el.text : void 0;
+      const candidates = [
+        { value: el.accessibilityId, unique: el.identityUnique?.accessibilityId },
+        { value: el.resourceId, unique: el.identityUnique?.resourceId },
+        { value: durableText, unique: el.identityUnique?.text }
+      ];
+      const uniqueFirst = candidates.find((c) => c.value && c.unique !== false);
+      const chosen = (uniqueFirst ?? candidates.find((c) => c.value))?.value;
+      return chosen ?? el.xpath;
     }
     function buildScreenSignal(elements, root, platform3) {
       const signal = {
@@ -1966,6 +2021,11 @@ function isEditableMobileClassName(className) {
     return false;
   return /(EditText|AutoCompleteTextView|XCUIElementTypeTextField|XCUIElementTypeSecureTextField|XCUIElementTypeSearchField|XCUIElementTypeTextView)$/.test(className.trim());
 }
+function isStateValueMobileClassName(className) {
+  if (!className)
+    return false;
+  return /(XCUIElementTypeSwitch|XCUIElementTypeToggle|XCUIElementTypeSlider|XCUIElementTypeStepper|XCUIElementTypePageIndicator|XCUIElementTypeProgressIndicator|XCUIElementTypeSegmentedControl|XCUIElementTypePicker|XCUIElementTypePickerWheel|ToggleButton|SeekBar|ProgressBar|RatingBar|NumberPicker)$/.test(className.trim());
+}
 function mobileCredentialPlaceholder(key) {
   return `{{${key}}}`;
 }
@@ -2095,9 +2155,10 @@ function buildStepTarget(metadata, selector) {
     locatorBundle.resourceId,
     // For editable fields the text attribute IS the currently-typed value — a
     // self-invalidating locator that only matches while the recorded text is
-    // still in the field (and it can leak typed input into locators). Static
-    // elements keep their text fallback.
-    isEditableMobileClassName(locatorBundle.className) ? void 0 : locatorBundle.text,
+    // still in the field (and it can leak typed input into locators). State
+    // controls' text is their current state ("1"/"ON") and collides with every
+    // same-state sibling. Static elements keep their text fallback.
+    isEditableMobileClassName(locatorBundle.className) || isStateValueMobileClassName(locatorBundle.className) ? void 0 : locatorBundle.text,
     locatorBundle.contentDesc,
     locatorBundle.xpath,
     selector
@@ -2253,7 +2314,9 @@ function mobileLocatorBundleHasIdentity(bundle) {
     return false;
   if (nonEmpty(bundle.accessibilityId) || nonEmpty(bundle.resourceId))
     return true;
-  if (nonEmpty(bundle.text) || nonEmpty(bundle.contentDesc))
+  if (nonEmpty(bundle.text) && !isStateValueMobileClassName(bundle.className))
+    return true;
+  if (nonEmpty(bundle.contentDesc))
     return true;
   const xpath = nonEmpty(bundle.xpath);
   return !!xpath && isIdentityMobileXpath(xpath);
@@ -2274,23 +2337,27 @@ function selectorCandidatesForStep(step) {
       candidates.push(`~${bundle.accessibilityId}`);
     if (nonEmpty(bundle.resourceId))
       candidates.push(`id=${bundle.resourceId}`);
+    if (nonEmpty(bundle.xpath))
+      candidates.push(bundle.xpath);
     const isGateStep = step.action === "waitForElement" || step.action === "assertVisible" || step.action === "assertText";
-    const textIdentity = isGateStep || !isEditableMobileClassName(bundle.className) ? bundle.text : void 0;
+    const textIdentity = (isGateStep || !isEditableMobileClassName(bundle.className)) && !isStateValueMobileClassName(bundle.className) ? bundle.text : void 0;
     for (const value of [textIdentity, bundle.contentDesc]) {
       const trimmed = nonEmpty(value);
       if (trimmed)
         candidates.push(identityTextXpath(trimmed));
     }
-    if (nonEmpty(bundle.xpath))
-      candidates.push(bundle.xpath);
   }
   const hasExplicitResourceId = !!nonEmpty(bundle?.resourceId);
+  const bundleContributedIdentity = candidates.some((value) => !(value.startsWith("/") || value.startsWith("(//")) || isIdentityMobileXpath(value));
   const pushValueCandidates = (value) => {
     candidates.push(selectorForValue(value));
     const looksLikeIdToken = /^[A-Za-z_][\w.:-]*$/.test(value);
     if (!hasExplicitResourceId && looksLikeIdToken && !/^(~|id=|css=|\/|\()/.test(value) && !value.includes(":id/")) {
       candidates.push(`id=${value}`);
     }
+    if (!bundleContributedIdentity && !/^(~|id=|css=|\/|\()/.test(value)) {
+      candidates.push(identityTextXpath(value));
+    }
   };
   if (nonEmpty(target.primary))
     pushValueCandidates(target.primary);
@@ -2985,7 +3052,8 @@ function isWebViewStep(step) {
 function hasCrossPlatformIdentity(bundle) {
   if (!bundle)
     return false;
-  return Boolean(bundle.text?.trim() || bundle.contentDesc?.trim() || bundle.accessibilityId?.trim());
+  const durableText = isStateValueMobileClassName(bundle.className) ? void 0 : bundle.text;
+  return Boolean(durableText?.trim() || bundle.contentDesc?.trim() || bundle.accessibilityId?.trim());
 }
 function stepIsDivergentForPlatform(step, platform3) {
   return Array.isArray(step.crossPlatformDivergent) && step.crossPlatformDivergent.includes(platform3);
@@ -3067,7 +3135,8 @@ function summarizeMobileReadiness(steps, authoringPlatform) {
 function hasStableNativeIdentity(bundle) {
   if (!bundle)
     return false;
-  return Boolean(bundle.accessibilityId?.trim() || bundle.resourceId?.trim() || bundle.text?.trim() || bundle.contentDesc?.trim() || bundle.xpath?.trim() && XPATH_ATTRIBUTE_EQUALITY_RE.test(bundle.xpath) && !/(?:contains|starts-with)\s*\(/i.test(bundle.xpath));
+  const durableText = isStateValueMobileClassName(bundle.className) ? void 0 : bundle.text;
+  return Boolean(bundle.accessibilityId?.trim() || bundle.resourceId?.trim() || durableText?.trim() || bundle.contentDesc?.trim() || bundle.xpath?.trim() && XPATH_ATTRIBUTE_EQUALITY_RE.test(bundle.xpath) && !/(?:contains|starts-with)\s*\(/i.test(bundle.xpath));
 }
 function isPositionalXpath(xpath) {
   const value = xpath?.trim();
@@ -3147,6 +3216,7 @@ var MOBILE_PLATFORMS, LOCATOR_REQUIRING_ACTIONS, XPATH_ATTRIBUTE_EQUALITY_RE;
 var init_mobile_cross_platform = __esm({
   "../shared/dist/mobile-cross-platform.js"() {
     "use strict";
+    init_mobile_test_generation();
     MOBILE_PLATFORMS = ["IOS", "ANDROID"];
     LOCATOR_REQUIRING_ACTIONS = /* @__PURE__ */ new Set([
       "tap",
@@ -6149,6 +6219,7 @@ __export(dist_exports, {
   isEditableMobileClassName: () => isEditableMobileClassName,
   isEmailFromIdentity: () => isEmailFromIdentity,
   isEnvironmentalError: () => isEnvironmentalError,
+  isIdentityMobileXpath: () => isIdentityMobileXpath,
   isMobilePlatform: () => isMobilePlatform,
   isPricingPlan: () => isPricingPlan,
   isRunnableStep: () => isRunnableStep,
@@ -6156,6 +6227,7 @@ __export(dist_exports, {
   isSameRegistrableDomainHost: () => isSameRegistrableDomainHost,
   isSensitiveQueryKey: () => isSensitiveQueryKey,
   isSharedAuthInjectEnabled: () => isSharedAuthInjectEnabled,
+  isStateValueMobileClassName: () => isStateValueMobileClassName,
   isSttModelForProvider: () => isSttModelForProvider,
   isTestReadyForPlatform: () => isTestReadyForPlatform,
   isTrialExpired: () => isTrialExpired,
@@ -7063,6 +7135,7 @@ var require_mobile_observation = __commonJS({
     exports2.buildCollectedElementsForScreen = buildCollectedElementsForScreen;
     exports2.extractNativeMobileLandmarks = extractNativeMobileLandmarks;
     exports2.safeMobileElementLabel = safeMobileElementLabel;
+    var mobile_source_parser_js_1 = require_mobile_source_parser();
     var DEFAULT_MAX_ELEMENTS = 60;
     var MAX_LABEL_LENGTH = 80;
     var EVIDENCE_LABEL_LIMIT = 40;
@@ -7153,7 +7226,8 @@ var require_mobile_observation = __commonJS({
       const locators = [];
       if (stableId)
         locators.push({ strategy: "getByTestId", value: stableId, confidence: 0.95 });
-      const xpath = element.xpath?.trim();
+      const platform3 = element.role.startsWith("XCUIElementType") ? "IOS" : "ANDROID";
+      const xpath = (0, mobile_source_parser_js_1.buildLocatorBundle)(element, platform3).xpath?.trim();
       if (xpath)
         locators.push({ strategy: "css", value: xpath, confidence: 0.4 });
       const collected = {
@@ -78402,6 +78476,10 @@ var require_discover_ai_planner = __commonJS({
       if (context.appBrief) {
         sections.push(`## Application Brief
 ${context.appBrief.slice(0, 500)}`);
+      }
+      if (context.knowledgeContext && context.knowledgeContext.trim().length > 0) {
+        sections.push(`## Known Facts
+${context.knowledgeContext.slice(0, 4e3)}`);
       }
       sections.push(`## Base URL
 ${compressed.baseUrl}`);
@@ -92283,6 +92361,15 @@ var require_agentic_discovery_prompts = __commonJS({
         lines.push(input.appBrief.trim());
         lines.push("");
       }
+      if (input.knownFactsBlock && input.knownFactsBlock.trim()) {
+        lines.push("## Known facts about this feature (from project documentation)");
+        lines.push("");
+        lines.push("Advisory hints about routes/data/constraints \u2014 verify against the live");
+        lines.push("app; the browser is the source of truth for locators.");
+        lines.push("");
+        lines.push(input.knownFactsBlock.trim());
+        lines.push("");
+      }
       if (input.credentials && input.credentials.length > 0) {
         lines.push("## Test credentials (throwaway accounts)");
         lines.push("");
@@ -328950,6 +329037,15 @@ var require_agentic_survey_prompts = __commonJS({
         lines.push(input.appBrief.trim());
         lines.push("");
       }
+      if (input.knownFactsBlock && input.knownFactsBlock.trim().length > 0) {
+        lines.push("## Known facts about this app (from project documentation)");
+        lines.push("");
+        lines.push("Use these as hints for what features/routes/constraints exist. They are");
+        lines.push("advisory \u2014 verify against the live app; the browser is the source of truth.");
+        lines.push("");
+        lines.push(input.knownFactsBlock.trim());
+        lines.push("");
+      }
       if (input.credentials && input.credentials.length > 0) {
         lines.push("## Test credentials (throwaway accounts)");
         lines.push("");
@@ -329577,6 +329673,7 @@ var require_grok_survey_runner = __commonJS({
       const briefInput = {
         baseUrl: ctx.baseUrl,
         appBrief: ctx.appBrief,
+        knownFactsBlock: ctx.knowledgeContext,
         credentials: credentials.length > 0 ? credentials : void 0,
         existingFeatureNames: ctx.existingFeatureNames ?? [],
         focusAreas: ctx.focusAreas,
@@ -331272,6 +331369,7 @@ var require_grok_discovery_runner = __commonJS({
           featureObservations: ctx.featureContext?.flowIntel,
           notesForTestAuthor: ctx.featureContext?.priorInsight,
           appBrief: ctx.appBrief,
+          knownFactsBlock: ctx.knowledgeContext,
           credentials: credentials.length > 0 ? credentials : void 0,
           testVariableKeys: testVariableKeys.length > 0 ? testVariableKeys : void 0,
           existingTestNames: ctx.existingTestNames ?? [],
@@ -332209,6 +332307,7 @@ ${(0, inbox_tools_js_1.buildInboxAgentsGuidance)(inboxReg.email, inboxReg.passwo
           featureObservations: ctx.featureContext?.flowIntel,
           notesForTestAuthor: ctx.featureContext?.priorInsight,
           appBrief: ctx.appBrief,
+          knownFactsBlock: ctx.knowledgeContext,
           credentials: credentials.length > 0 ? credentials : void 0,
           testVariableKeys: testVariableKeys.length > 0 ? testVariableKeys : void 0,
           existingTestNames: ctx.existingTestNames ?? [],
@@ -333300,6 +333399,7 @@ ${preview}`);
       const briefInput = {
         baseUrl: ctx.baseUrl,
         appBrief: ctx.appBrief,
+        knownFactsBlock: ctx.knowledgeContext,
         credentials: credentials.length > 0 ? credentials : void 0,
         existingFeatureNames: ctx.existingFeatureNames ?? [],
         focusAreas: ctx.focusAreas,
@@ -334159,6 +334259,7 @@ var require_claude_discovery_runner = __commonJS({
           featureObservations: ctx.featureContext?.flowIntel,
           notesForTestAuthor: ctx.featureContext?.priorInsight,
           appBrief: ctx.appBrief,
+          knownFactsBlock: ctx.knowledgeContext,
           credentials: credentials.length > 0 ? credentials : void 0,
           testVariableKeys: testVariableKeys.length > 0 ? testVariableKeys : void 0,
           existingTestNames: ctx.existingTestNames ?? [],
@@ -336013,7 +336114,8 @@ Explore complete: ${exploreResult.pagesDiscovered} pages, ${exploreResult.elemen
           // scenarioTouchesSignupAuthSurface) still isolate non-auth scenarios. The
           // auth-feature scope IS applied at the DEEP call site where ctx.featureName is known.
           emailVerifyArmed: mode !== "survey" && plannerEmailVerifyArmed(ctx),
-          testBudget
+          testBudget,
+          knowledgeContext: ctx.knowledgeContext
         }, {
           modelOverride: ctx.planModel ?? ctx.generateModel,
           gateModelOverride: ctx.planGateModel,
@@ -336125,6 +336227,7 @@ Health: ${surveyHealth.totalIssues} issue(s) - ${surveyHealth.consoleErrors.leng
           interactionLog: exploreResult.interactionLog,
           modelOverride: ctx.generateModel,
           appBrief: ctx.appBrief,
+          knowledgeContext: ctx.knowledgeContext,
           onAICall,
           onProgress,
           mcpClient: mcpClient ?? void 0,
@@ -336604,7 +336707,8 @@ Plan (reused): ${resumeSavedScenarios.length} scenarios from the paused run.`);
             // configured inbox), so the planner never promises what generation can't do.
             // Scoped to AUTH features: a non-auth feature has no signup surface to test.
             emailVerifyArmed: plannerEmailVerifyArmed(ctx) && featureLooksLikeAuth(ctx.featureName, augmentedFeatureFocusAreas),
-            testBudget: featureTestBudget
+            testBudget: featureTestBudget,
+            knowledgeContext: ctx.knowledgeContext
           }, {
             modelOverride: ctx.planModel ?? ctx.generateModel,
             gateModelOverride: ctx.planGateModel,
@@ -336650,6 +336754,7 @@ Plan: ${planResult.scenarios.length} scenarios (budget: ${featureTestBudget})`);
           interactionLog: exploreResult.interactionLog,
           modelOverride: ctx.generateModel,
           appBrief: ctx.appBrief,
+          knowledgeContext: ctx.knowledgeContext,
           onAICall,
           mcpClient: mcpClient ?? void 0,
           // Pooled browser for parallel scenario generation (Fargate opt-in via
@@ -347863,6 +347968,12 @@ Write valid JSON only (no markdown fences inside files). Be exhaustive.`;
         "Use {{TEST_USER_EMAIL}}/{{TEST_USER_PASSWORD}} for credentials. Include",
         "assertVisible or assertText unless tagging @needs-review. When an incremental",
         "allow-list is present, extract ONLY from those files.",
+        "",
+        "Every tap/type/clear/waitForElement/assertVisible/assertText target MUST",
+        "carry an IDENTITY locator: ~accessibility-id, id=resource-id, visible text,",
+        "or an attribute-EQUALITY xpath (//android.widget.Button[@text='Submit']).",
+        "Positional/index-only xpaths (/hierarchy/\u2026/View[3]) are rejected \u2014 imported",
+        "steps have no recorded coordinates, so such a step can never replay.",
         "Write strictly valid JSON."
       ].join("\n");
     }
@@ -347880,6 +347991,32 @@ Write valid JSON only (no markdown fences inside files). Be exhaustive.`;
     function isPlainObject2(value) {
       return !!value && typeof value === "object" && !Array.isArray(value);
     }
+    var LOCATOR_REQUIRING_IMPORT_ACTIONS = /* @__PURE__ */ new Set([
+      "tap",
+      "type",
+      "clear",
+      "waitForElement",
+      "assertVisible",
+      "assertText"
+    ]);
+    function selectorValueHasIdentity(value) {
+      const trimmed = value.trim();
+      if (!trimmed)
+        return false;
+      if (trimmed.startsWith("/") || trimmed.startsWith("(//"))
+        return (0, shared_1.isIdentityMobileXpath)(trimmed);
+      return true;
+    }
+    function stepLocatorLacksIdentity(step) {
+      if (!LOCATOR_REQUIRING_IMPORT_ACTIONS.has(step.action))
+        return false;
+      const target = step.target;
+      if (!target)
+        return true;
+      if ((0, shared_1.mobileLocatorBundleHasIdentity)(target.locatorBundle))
+        return false;
+      return ![target.primary, ...target.fallbacks ?? []].some((value) => typeof value === "string" && selectorValueHasIdentity(value));
+    }
     function isValidStep(value) {
       if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
@@ -347931,6 +348068,13 @@ Write valid JSON only (no markdown fences inside files). Be exhaustive.`;
       if (!o.steps.every(isValidStep)) {
         return { ok: false, reason: "steps: invalid step shape" };
       }
+      const identityless = o.steps.find(stepLocatorLacksIdentity);
+      if (identityless) {
+        return {
+          ok: false,
+          reason: `steps: step ${identityless.order} (${identityless.action}) has no identity locator \u2014 a positional/index xpath cannot replay (imported steps have no recorded coordinates). Use ~accessibility-id, id=resource-id, visible text, or an attribute-equality xpath like //android.widget.Button[@text='Submit'].`
+        };
+      }
       const steps = o.steps.map((step, order) => ({
         ...step,
         order,
@@ -351224,7 +351368,7 @@ var require_package4 = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@validate.qa/runner",
-      version: "1.0.67",
+      version: "1.0.68",
       description: "validate local test runner - execute Playwright tests on your machine, connected to validate.qa cloud.",
       bin: {
         "validate-runner": "dist/cli.js"
@@ -354692,7 +354836,7 @@ function boundsForRun(step, platform3, isCrossPlatform) {
   if (platform3 && hasPlatformLocator(step.target, platform3)) return null;
   return boundsFromStep(step);
 }
-function locatorStrategyForValue(value) {
+function locatorStrategyForValue(value, platform3) {
   const trimmed = value?.trim();
   if (!trimmed) {
     return [];
@@ -354708,7 +354852,8 @@ function locatorStrategyForValue(value) {
   }
   return [
     { using: "accessibility id", value: trimmed },
-    { using: "id", value: trimmed }
+    { using: "id", value: trimmed },
+    ...textIdentityStrategies(trimmed, platform3)
   ];
 }
 function buildLocatorStrategies(target, platform3) {
@@ -354718,19 +354863,19 @@ function buildLocatorStrategies(target, platform3) {
   if (bundle) {
     if (bundle.accessibilityId) strategies.push({ using: "accessibility id", value: bundle.accessibilityId });
     if (bundle.resourceId) strategies.push({ using: "id", value: bundle.resourceId });
+    if (bundle.xpath && isIdentityXpath(bundle.xpath)) strategies.push({ using: "xpath", value: bundle.xpath });
     for (const value of [
-      isEditableMobileClassName(bundle.className) ? void 0 : bundle.text,
+      isEditableMobileClassName(bundle.className) || isStateValueMobileClassName(bundle.className) ? void 0 : bundle.text,
       bundle.contentDesc
     ]) {
       const trimmed = value?.trim();
-      if (trimmed) strategies.push({ using: "xpath", value: identityTextXpath2(trimmed) });
+      if (trimmed) strategies.push(...textIdentityStrategies(trimmed, platform3));
     }
-    if (bundle.xpath) strategies.push({ using: "xpath", value: bundle.xpath });
   }
   if (!(platform3 && hasPlatformLocator(target, platform3))) {
-    strategies.push(...locatorStrategyForValue(target.primary));
+    strategies.push(...locatorStrategyForValue(target.primary, platform3));
     for (const fallback of target.fallbacks ?? []) {
-      strategies.push(...locatorStrategyForValue(fallback));
+      strategies.push(...locatorStrategyForValue(fallback, platform3));
     }
   }
   return strategies.filter((strategy) => strategy.using !== "xpath" || isIdentityXpath(strategy.value)).filter(
@@ -354752,12 +354897,31 @@ function identityTextXpath2(value) {
   const lit = xpathLiteral3(value);
   return `//*[@text=${lit} or @content-desc=${lit} or @label=${lit} or @name=${lit} or @value=${lit}]`;
 }
+function iosPredicateLiteral(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function iosTextIdentityPredicate(value) {
+  const lit = iosPredicateLiteral(value);
+  return `label == ${lit} OR name == ${lit} OR value == ${lit}`;
+}
+function textIdentityStrategies(value, platform3) {
+  const strategies = [];
+  if (platform3 === "IOS") {
+    strategies.push({ using: "-ios predicate string", value: iosTextIdentityPredicate(value) });
+  }
+  strategies.push({ using: "xpath", value: identityTextXpath2(value) });
+  return strategies;
+}
+function isIdentityIosPredicate(value) {
+  return /(?:^|[\s(])(?:name|label|value)\s*==\s*"/.test(value) && !/\b(?:CONTAINS|BEGINSWITH|ENDSWITH|LIKE|MATCHES|IN)\b/i.test(value);
+}
 function isIdentityXpath(value) {
   return /@[A-Za-z_:][-A-Za-z0-9_:.]*\s*=/.test(value) && !/(?:contains|starts-with)\s*\(/i.test(value);
 }
 function isIdentityStrategy(strategy) {
   if (strategy.using === "accessibility id" || strategy.using === "id") return true;
   if (strategy.using === "xpath") return isIdentityXpath(strategy.value);
+  if (strategy.using === "-ios predicate string") return isIdentityIosPredicate(strategy.value);
   return false;
 }
 function buildIdentityLocatorStrategies(target, platform3) {
@@ -354767,15 +354931,18 @@ function buildIdentityLocatorStrategies(target, platform3) {
   if (bundle) {
     if (bundle.accessibilityId) strategies.push({ using: "accessibility id", value: bundle.accessibilityId });
     if (bundle.resourceId) strategies.push({ using: "id", value: bundle.resourceId });
-    for (const value of [bundle.text, bundle.contentDesc]) {
+    if (bundle.xpath && isIdentityXpath(bundle.xpath)) strategies.push({ using: "xpath", value: bundle.xpath });
+    for (const value of [
+      isStateValueMobileClassName(bundle.className) ? void 0 : bundle.text,
+      bundle.contentDesc
+    ]) {
       const trimmed = value?.trim();
-      if (trimmed) strategies.push({ using: "xpath", value: identityTextXpath2(trimmed) });
+      if (trimmed) strategies.push(...textIdentityStrategies(trimmed, platform3));
     }
-    if (bundle.xpath && isIdentityXpath(bundle.xpath)) strategies.push({ using: "xpath", value: bundle.xpath });
   }
   if (!(platform3 && hasPlatformLocator(target, platform3))) {
     for (const value of [target.primary, ...target.fallbacks ?? []]) {
-      for (const strategy of locatorStrategyForValue(value)) {
+      for (const strategy of locatorStrategyForValue(value, platform3)) {
         if (isIdentityStrategy(strategy)) strategies.push(strategy);
       }
     }
@@ -355770,8 +355937,7 @@ async function readElementAttribute(sessionId, elementId, name) {
 function harvestFallbackXpath(platform3, attrs) {
   if (platform3 === "IOS") {
     if (attrs.name) return `//*[@name=${xpathLiteral3(attrs.name)}]`;
-    const text = attrs.label ?? attrs.value;
-    if (text) return identityTextXpath2(text);
+    if (attrs.text) return identityTextXpath2(attrs.text);
     return "//*";
   }
   if (attrs.resourceId) return `//*[@resource-id=${xpathLiteral3(attrs.resourceId)}]`;
@@ -355781,14 +355947,15 @@ function harvestFallbackXpath(platform3, attrs) {
 }
 async function readNativeElementBundle(sessionId, elementId, platform3) {
   const className = await readElementAttribute(sessionId, elementId, platform3 === "IOS" ? "type" : "class") ?? "";
+  const volatileText = isEditableMobileClassName(className) || isStateValueMobileClassName(className);
   if (platform3 === "IOS") {
     const name = await readElementAttribute(sessionId, elementId, "name");
     const label = await readElementAttribute(sessionId, elementId, "label");
     const value = await readElementAttribute(sessionId, elementId, "value");
-    const text2 = label ?? value;
+    const text2 = label ?? (volatileText ? void 0 : value);
     if (!name && !text2) return null;
     const bundle2 = {
-      xpath: harvestFallbackXpath("IOS", { name, label, value }),
+      xpath: harvestFallbackXpath("IOS", { name, text: text2 }),
       className
     };
     if (name) bundle2.accessibilityId = name;
@@ -355797,7 +355964,8 @@ async function readNativeElementBundle(sessionId, elementId, platform3) {
   }
   const resourceId = await readElementAttribute(sessionId, elementId, "resource-id");
   const contentDesc = await readElementAttribute(sessionId, elementId, "content-desc") ?? await readElementAttribute(sessionId, elementId, "contentDescription");
-  const text = await readElementAttribute(sessionId, elementId, "text");
+  const rawText = await readElementAttribute(sessionId, elementId, "text");
+  const text = volatileText ? void 0 : rawText;
   if (!resourceId && !contentDesc && !text) return null;
   const bundle = {
     xpath: harvestFallbackXpath("ANDROID", { text, contentDesc, resourceId }),

package/dist/cli.mjs

@@ -983,7 +983,7 @@ var require_mobile_source_parser = __commonJS({
       const value = nonEmpty3(attrs.value);
       const label = name ?? labelAttr ?? value;
       const accessibilityId = name;
-      const text = value && value !== label ? value : labelAttr && labelAttr !== label ? labelAttr : void 0;
+      const text = labelAttr ?? (isStateValueRole(role) ? void 0 : value);
       const bounds = parseIOSBounds(attrs);
       const enabled = attrBoolDefaultTrue(attrs.enabled);
       const visible = attrBoolDefaultTrue(attrs.visible);
@@ -1130,6 +1130,42 @@ var require_mobile_source_parser = __commonJS({
         }
       }
     }
+    function annotateIdentityUniqueness(elements) {
+      const a11yCounts = /* @__PURE__ */ new Map();
+      const ridCounts = /* @__PURE__ */ new Map();
+      const textCounts = /* @__PURE__ */ new Map();
+      const bump = (map2, value) => {
+        const key = value?.trim();
+        if (!key)
+          return;
+        map2.set(key, (map2.get(key) ?? 0) + 1);
+      };
+      for (const element of elements) {
+        bump(a11yCounts, element.accessibilityId);
+        bump(ridCounts, element.resourceId);
+        const identityValues = new Set([element.text, element.accessibilityId].map((value) => value?.trim()).filter((value) => Boolean(value)));
+        for (const value of identityValues)
+          bump(textCounts, value);
+      }
+      const isUnique = (map2, value) => {
+        const key = value?.trim();
+        if (!key)
+          return void 0;
+        return (map2.get(key) ?? 0) <= 1;
+      };
+      for (const element of elements) {
+        const accessibilityId = isUnique(a11yCounts, element.accessibilityId);
+        const resourceId = isUnique(ridCounts, element.resourceId);
+        const text = isUnique(textCounts, element.text);
+        if (accessibilityId === void 0 && resourceId === void 0 && text === void 0)
+          continue;
+        element.identityUnique = {
+          ...accessibilityId !== void 0 ? { accessibilityId } : {},
+          ...resourceId !== void 0 ? { resourceId } : {},
+          ...text !== void 0 ? { text } : {}
+        };
+      }
+    }
     function flatten(root, platform3) {
       const out = [];
       const stack = [];
@@ -1175,6 +1211,7 @@ var require_mobile_source_parser = __commonJS({
         }
       }
       markRepeatedBottomBarNavigation(out);
+      annotateIdentityUniqueness(out);
       return out;
     }
     function fnv1a(input) {
@@ -1256,6 +1293,13 @@ var require_mobile_source_parser = __commonJS({
     function isEditableElement(el) {
       return EDITABLE_CLASS_RE.test(el.role.trim());
     }
+    var STATE_VALUE_CLASS_RE = /(XCUIElementTypeSwitch|XCUIElementTypeToggle|XCUIElementTypeSlider|XCUIElementTypeStepper|XCUIElementTypePageIndicator|XCUIElementTypeProgressIndicator|XCUIElementTypeSegmentedControl|XCUIElementTypePicker|XCUIElementTypePickerWheel|ToggleButton|SeekBar|ProgressBar|RatingBar|NumberPicker)$/;
+    function isStateValueRole(role) {
+      return STATE_VALUE_CLASS_RE.test(role.trim());
+    }
+    function isStateValueElement(el) {
+      return isStateValueRole(el.role);
+    }
     function xpathAttrLiteral(value) {
       if (!value.includes("'"))
         return `'${value}'`;
@@ -1266,17 +1310,18 @@ var require_mobile_source_parser = __commonJS({
     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;
+      const rid = platform3 === "ANDROID" ? nonBlank(el.resourceId) : void 0;
+      const text = isEditableElement(el) || isStateValueElement(el) ? void 0 : nonBlank(el.text);
+      const a11yXpath = a11y ? platform3 === "ANDROID" ? `//${cls}[@content-desc=${xpathAttrLiteral(a11y)}]` : `//${cls}[@name=${xpathAttrLiteral(a11y)}]` : void 0;
+      const ridXpath = rid ? `//${cls}[@resource-id=${xpathAttrLiteral(rid)}]` : void 0;
+      const textXpath = text ? platform3 === "ANDROID" ? `//${cls}[@text=${xpathAttrLiteral(text)}]` : `//${cls}[@label=${xpathAttrLiteral(text)}]` : void 0;
+      const candidates = [
+        { xpath: a11yXpath, unique: el.identityUnique?.accessibilityId },
+        { xpath: ridXpath, unique: el.identityUnique?.resourceId },
+        { xpath: textXpath, unique: el.identityUnique?.text }
+      ];
+      const uniqueFirst = candidates.find((c) => c.xpath && c.unique !== false);
+      return (uniqueFirst ?? candidates.find((c) => c.xpath))?.xpath;
     }
     function nonBlank(value) {
       if (typeof value !== "string")
@@ -1285,30 +1330,40 @@ var require_mobile_source_parser = __commonJS({
       return trimmed.length > 0 ? trimmed : void 0;
     }
     function buildLocatorBundle(el, platform3) {
+      const durableText = el.text && !isEditableElement(el) && !isStateValueElement(el) ? el.text : void 0;
       const bundle = {
         // 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)
+      const a11yUnique = el.identityUnique?.accessibilityId !== false;
+      const ridUnique = el.identityUnique?.resourceId !== false;
+      const textUnique = el.identityUnique?.text !== false;
+      const hasUniqueAlternativeToA11y = Boolean(el.resourceId && platform3 === "ANDROID" && ridUnique || durableText && textUnique);
+      const hasUniqueAlternativeToRid = Boolean(el.accessibilityId && a11yUnique || durableText && textUnique);
+      const includeA11y = Boolean(el.accessibilityId && (a11yUnique || !hasUniqueAlternativeToA11y));
+      const includeRid = Boolean(platform3 === "ANDROID" && el.resourceId && (ridUnique || !hasUniqueAlternativeToRid));
+      if (includeA11y && el.accessibilityId)
         bundle.accessibilityId = el.accessibilityId;
-      if (platform3 === "ANDROID" && el.resourceId)
+      if (includeRid && el.resourceId)
         bundle.resourceId = el.resourceId;
-      if (el.text && !isEditableElement(el))
-        bundle.text = el.text;
-      if (platform3 === "ANDROID" && el.accessibilityId)
+      if (durableText)
+        bundle.text = durableText;
+      if (includeA11y && platform3 === "ANDROID" && el.accessibilityId)
         bundle.contentDesc = el.accessibilityId;
       return bundle;
     }
     function preferredLocator(el) {
-      if (el.accessibilityId)
-        return el.accessibilityId;
-      if (el.resourceId)
-        return el.resourceId;
-      if (el.text && !isEditableElement(el))
-        return el.text;
-      return el.xpath;
+      const durableText = el.text && !isEditableElement(el) && !isStateValueElement(el) ? el.text : void 0;
+      const candidates = [
+        { value: el.accessibilityId, unique: el.identityUnique?.accessibilityId },
+        { value: el.resourceId, unique: el.identityUnique?.resourceId },
+        { value: durableText, unique: el.identityUnique?.text }
+      ];
+      const uniqueFirst = candidates.find((c) => c.value && c.unique !== false);
+      const chosen = (uniqueFirst ?? candidates.find((c) => c.value))?.value;
+      return chosen ?? el.xpath;
     }
     function buildScreenSignal(elements, root, platform3) {
       const signal = {
@@ -1971,6 +2026,11 @@ function isEditableMobileClassName(className) {
     return false;
   return /(EditText|AutoCompleteTextView|XCUIElementTypeTextField|XCUIElementTypeSecureTextField|XCUIElementTypeSearchField|XCUIElementTypeTextView)$/.test(className.trim());
 }
+function isStateValueMobileClassName(className) {
+  if (!className)
+    return false;
+  return /(XCUIElementTypeSwitch|XCUIElementTypeToggle|XCUIElementTypeSlider|XCUIElementTypeStepper|XCUIElementTypePageIndicator|XCUIElementTypeProgressIndicator|XCUIElementTypeSegmentedControl|XCUIElementTypePicker|XCUIElementTypePickerWheel|ToggleButton|SeekBar|ProgressBar|RatingBar|NumberPicker)$/.test(className.trim());
+}
 function mobileCredentialPlaceholder(key) {
   return `{{${key}}}`;
 }
@@ -2100,9 +2160,10 @@ function buildStepTarget(metadata, selector) {
     locatorBundle.resourceId,
     // For editable fields the text attribute IS the currently-typed value — a
     // self-invalidating locator that only matches while the recorded text is
-    // still in the field (and it can leak typed input into locators). Static
-    // elements keep their text fallback.
-    isEditableMobileClassName(locatorBundle.className) ? void 0 : locatorBundle.text,
+    // still in the field (and it can leak typed input into locators). State
+    // controls' text is their current state ("1"/"ON") and collides with every
+    // same-state sibling. Static elements keep their text fallback.
+    isEditableMobileClassName(locatorBundle.className) || isStateValueMobileClassName(locatorBundle.className) ? void 0 : locatorBundle.text,
     locatorBundle.contentDesc,
     locatorBundle.xpath,
     selector
@@ -2258,7 +2319,9 @@ function mobileLocatorBundleHasIdentity(bundle) {
     return false;
   if (nonEmpty(bundle.accessibilityId) || nonEmpty(bundle.resourceId))
     return true;
-  if (nonEmpty(bundle.text) || nonEmpty(bundle.contentDesc))
+  if (nonEmpty(bundle.text) && !isStateValueMobileClassName(bundle.className))
+    return true;
+  if (nonEmpty(bundle.contentDesc))
     return true;
   const xpath = nonEmpty(bundle.xpath);
   return !!xpath && isIdentityMobileXpath(xpath);
@@ -2279,23 +2342,27 @@ function selectorCandidatesForStep(step) {
       candidates.push(`~${bundle.accessibilityId}`);
     if (nonEmpty(bundle.resourceId))
       candidates.push(`id=${bundle.resourceId}`);
+    if (nonEmpty(bundle.xpath))
+      candidates.push(bundle.xpath);
     const isGateStep = step.action === "waitForElement" || step.action === "assertVisible" || step.action === "assertText";
-    const textIdentity = isGateStep || !isEditableMobileClassName(bundle.className) ? bundle.text : void 0;
+    const textIdentity = (isGateStep || !isEditableMobileClassName(bundle.className)) && !isStateValueMobileClassName(bundle.className) ? bundle.text : void 0;
     for (const value of [textIdentity, bundle.contentDesc]) {
       const trimmed = nonEmpty(value);
       if (trimmed)
         candidates.push(identityTextXpath(trimmed));
     }
-    if (nonEmpty(bundle.xpath))
-      candidates.push(bundle.xpath);
   }
   const hasExplicitResourceId = !!nonEmpty(bundle?.resourceId);
+  const bundleContributedIdentity = candidates.some((value) => !(value.startsWith("/") || value.startsWith("(//")) || isIdentityMobileXpath(value));
   const pushValueCandidates = (value) => {
     candidates.push(selectorForValue(value));
     const looksLikeIdToken = /^[A-Za-z_][\w.:-]*$/.test(value);
     if (!hasExplicitResourceId && looksLikeIdToken && !/^(~|id=|css=|\/|\()/.test(value) && !value.includes(":id/")) {
       candidates.push(`id=${value}`);
     }
+    if (!bundleContributedIdentity && !/^(~|id=|css=|\/|\()/.test(value)) {
+      candidates.push(identityTextXpath(value));
+    }
   };
   if (nonEmpty(target.primary))
     pushValueCandidates(target.primary);
@@ -2990,7 +3057,8 @@ function isWebViewStep(step) {
 function hasCrossPlatformIdentity(bundle) {
   if (!bundle)
     return false;
-  return Boolean(bundle.text?.trim() || bundle.contentDesc?.trim() || bundle.accessibilityId?.trim());
+  const durableText = isStateValueMobileClassName(bundle.className) ? void 0 : bundle.text;
+  return Boolean(durableText?.trim() || bundle.contentDesc?.trim() || bundle.accessibilityId?.trim());
 }
 function stepIsDivergentForPlatform(step, platform3) {
   return Array.isArray(step.crossPlatformDivergent) && step.crossPlatformDivergent.includes(platform3);
@@ -3072,7 +3140,8 @@ function summarizeMobileReadiness(steps, authoringPlatform) {
 function hasStableNativeIdentity(bundle) {
   if (!bundle)
     return false;
-  return Boolean(bundle.accessibilityId?.trim() || bundle.resourceId?.trim() || bundle.text?.trim() || bundle.contentDesc?.trim() || bundle.xpath?.trim() && XPATH_ATTRIBUTE_EQUALITY_RE.test(bundle.xpath) && !/(?:contains|starts-with)\s*\(/i.test(bundle.xpath));
+  const durableText = isStateValueMobileClassName(bundle.className) ? void 0 : bundle.text;
+  return Boolean(bundle.accessibilityId?.trim() || bundle.resourceId?.trim() || durableText?.trim() || bundle.contentDesc?.trim() || bundle.xpath?.trim() && XPATH_ATTRIBUTE_EQUALITY_RE.test(bundle.xpath) && !/(?:contains|starts-with)\s*\(/i.test(bundle.xpath));
 }
 function isPositionalXpath(xpath) {
   const value = xpath?.trim();
@@ -3152,6 +3221,7 @@ var MOBILE_PLATFORMS, LOCATOR_REQUIRING_ACTIONS, XPATH_ATTRIBUTE_EQUALITY_RE;
 var init_mobile_cross_platform = __esm({
   "../shared/dist/mobile-cross-platform.js"() {
     "use strict";
+    init_mobile_test_generation();
     MOBILE_PLATFORMS = ["IOS", "ANDROID"];
     LOCATOR_REQUIRING_ACTIONS = /* @__PURE__ */ new Set([
       "tap",
@@ -6154,6 +6224,7 @@ __export(dist_exports, {
   isEditableMobileClassName: () => isEditableMobileClassName,
   isEmailFromIdentity: () => isEmailFromIdentity,
   isEnvironmentalError: () => isEnvironmentalError,
+  isIdentityMobileXpath: () => isIdentityMobileXpath,
   isMobilePlatform: () => isMobilePlatform,
   isPricingPlan: () => isPricingPlan,
   isRunnableStep: () => isRunnableStep,
@@ -6161,6 +6232,7 @@ __export(dist_exports, {
   isSameRegistrableDomainHost: () => isSameRegistrableDomainHost,
   isSensitiveQueryKey: () => isSensitiveQueryKey,
   isSharedAuthInjectEnabled: () => isSharedAuthInjectEnabled,
+  isStateValueMobileClassName: () => isStateValueMobileClassName,
   isSttModelForProvider: () => isSttModelForProvider,
   isTestReadyForPlatform: () => isTestReadyForPlatform,
   isTrialExpired: () => isTrialExpired,
@@ -7068,6 +7140,7 @@ var require_mobile_observation = __commonJS({
     exports.buildCollectedElementsForScreen = buildCollectedElementsForScreen;
     exports.extractNativeMobileLandmarks = extractNativeMobileLandmarks;
     exports.safeMobileElementLabel = safeMobileElementLabel;
+    var mobile_source_parser_js_1 = require_mobile_source_parser();
     var DEFAULT_MAX_ELEMENTS = 60;
     var MAX_LABEL_LENGTH = 80;
     var EVIDENCE_LABEL_LIMIT = 40;
@@ -7158,7 +7231,8 @@ var require_mobile_observation = __commonJS({
       const locators = [];
       if (stableId)
         locators.push({ strategy: "getByTestId", value: stableId, confidence: 0.95 });
-      const xpath = element.xpath?.trim();
+      const platform3 = element.role.startsWith("XCUIElementType") ? "IOS" : "ANDROID";
+      const xpath = (0, mobile_source_parser_js_1.buildLocatorBundle)(element, platform3).xpath?.trim();
       if (xpath)
         locators.push({ strategy: "css", value: xpath, confidence: 0.4 });
       const collected = {
@@ -78407,6 +78481,10 @@ var require_discover_ai_planner = __commonJS({
       if (context.appBrief) {
         sections.push(`## Application Brief
 ${context.appBrief.slice(0, 500)}`);
+      }
+      if (context.knowledgeContext && context.knowledgeContext.trim().length > 0) {
+        sections.push(`## Known Facts
+${context.knowledgeContext.slice(0, 4e3)}`);
       }
       sections.push(`## Base URL
 ${compressed.baseUrl}`);
@@ -92288,6 +92366,15 @@ var require_agentic_discovery_prompts = __commonJS({
         lines.push(input.appBrief.trim());
         lines.push("");
       }
+      if (input.knownFactsBlock && input.knownFactsBlock.trim()) {
+        lines.push("## Known facts about this feature (from project documentation)");
+        lines.push("");
+        lines.push("Advisory hints about routes/data/constraints \u2014 verify against the live");
+        lines.push("app; the browser is the source of truth for locators.");
+        lines.push("");
+        lines.push(input.knownFactsBlock.trim());
+        lines.push("");
+      }
       if (input.credentials && input.credentials.length > 0) {
         lines.push("## Test credentials (throwaway accounts)");
         lines.push("");
@@ -328955,6 +329042,15 @@ var require_agentic_survey_prompts = __commonJS({
         lines.push(input.appBrief.trim());
         lines.push("");
       }
+      if (input.knownFactsBlock && input.knownFactsBlock.trim().length > 0) {
+        lines.push("## Known facts about this app (from project documentation)");
+        lines.push("");
+        lines.push("Use these as hints for what features/routes/constraints exist. They are");
+        lines.push("advisory \u2014 verify against the live app; the browser is the source of truth.");
+        lines.push("");
+        lines.push(input.knownFactsBlock.trim());
+        lines.push("");
+      }
       if (input.credentials && input.credentials.length > 0) {
         lines.push("## Test credentials (throwaway accounts)");
         lines.push("");
@@ -329582,6 +329678,7 @@ var require_grok_survey_runner = __commonJS({
       const briefInput = {
         baseUrl: ctx.baseUrl,
         appBrief: ctx.appBrief,
+        knownFactsBlock: ctx.knowledgeContext,
         credentials: credentials.length > 0 ? credentials : void 0,
         existingFeatureNames: ctx.existingFeatureNames ?? [],
         focusAreas: ctx.focusAreas,
@@ -331277,6 +331374,7 @@ var require_grok_discovery_runner = __commonJS({
           featureObservations: ctx.featureContext?.flowIntel,
           notesForTestAuthor: ctx.featureContext?.priorInsight,
           appBrief: ctx.appBrief,
+          knownFactsBlock: ctx.knowledgeContext,
           credentials: credentials.length > 0 ? credentials : void 0,
           testVariableKeys: testVariableKeys.length > 0 ? testVariableKeys : void 0,
           existingTestNames: ctx.existingTestNames ?? [],
@@ -332214,6 +332312,7 @@ ${(0, inbox_tools_js_1.buildInboxAgentsGuidance)(inboxReg.email, inboxReg.passwo
           featureObservations: ctx.featureContext?.flowIntel,
           notesForTestAuthor: ctx.featureContext?.priorInsight,
           appBrief: ctx.appBrief,
+          knownFactsBlock: ctx.knowledgeContext,
           credentials: credentials.length > 0 ? credentials : void 0,
           testVariableKeys: testVariableKeys.length > 0 ? testVariableKeys : void 0,
           existingTestNames: ctx.existingTestNames ?? [],
@@ -333305,6 +333404,7 @@ ${preview}`);
       const briefInput = {
         baseUrl: ctx.baseUrl,
         appBrief: ctx.appBrief,
+        knownFactsBlock: ctx.knowledgeContext,
         credentials: credentials.length > 0 ? credentials : void 0,
         existingFeatureNames: ctx.existingFeatureNames ?? [],
         focusAreas: ctx.focusAreas,
@@ -334164,6 +334264,7 @@ var require_claude_discovery_runner = __commonJS({
           featureObservations: ctx.featureContext?.flowIntel,
           notesForTestAuthor: ctx.featureContext?.priorInsight,
           appBrief: ctx.appBrief,
+          knownFactsBlock: ctx.knowledgeContext,
           credentials: credentials.length > 0 ? credentials : void 0,
           testVariableKeys: testVariableKeys.length > 0 ? testVariableKeys : void 0,
           existingTestNames: ctx.existingTestNames ?? [],
@@ -336018,7 +336119,8 @@ Explore complete: ${exploreResult.pagesDiscovered} pages, ${exploreResult.elemen
           // scenarioTouchesSignupAuthSurface) still isolate non-auth scenarios. The
           // auth-feature scope IS applied at the DEEP call site where ctx.featureName is known.
           emailVerifyArmed: mode !== "survey" && plannerEmailVerifyArmed(ctx),
-          testBudget
+          testBudget,
+          knowledgeContext: ctx.knowledgeContext
         }, {
           modelOverride: ctx.planModel ?? ctx.generateModel,
           gateModelOverride: ctx.planGateModel,
@@ -336130,6 +336232,7 @@ Health: ${surveyHealth.totalIssues} issue(s) - ${surveyHealth.consoleErrors.leng
           interactionLog: exploreResult.interactionLog,
           modelOverride: ctx.generateModel,
           appBrief: ctx.appBrief,
+          knowledgeContext: ctx.knowledgeContext,
           onAICall,
           onProgress,
           mcpClient: mcpClient ?? void 0,
@@ -336609,7 +336712,8 @@ Plan (reused): ${resumeSavedScenarios.length} scenarios from the paused run.`);
             // configured inbox), so the planner never promises what generation can't do.
             // Scoped to AUTH features: a non-auth feature has no signup surface to test.
             emailVerifyArmed: plannerEmailVerifyArmed(ctx) && featureLooksLikeAuth(ctx.featureName, augmentedFeatureFocusAreas),
-            testBudget: featureTestBudget
+            testBudget: featureTestBudget,
+            knowledgeContext: ctx.knowledgeContext
           }, {
             modelOverride: ctx.planModel ?? ctx.generateModel,
             gateModelOverride: ctx.planGateModel,
@@ -336655,6 +336759,7 @@ Plan: ${planResult.scenarios.length} scenarios (budget: ${featureTestBudget})`);
           interactionLog: exploreResult.interactionLog,
           modelOverride: ctx.generateModel,
           appBrief: ctx.appBrief,
+          knowledgeContext: ctx.knowledgeContext,
           onAICall,
           mcpClient: mcpClient ?? void 0,
           // Pooled browser for parallel scenario generation (Fargate opt-in via
@@ -347868,6 +347973,12 @@ Write valid JSON only (no markdown fences inside files). Be exhaustive.`;
         "Use {{TEST_USER_EMAIL}}/{{TEST_USER_PASSWORD}} for credentials. Include",
         "assertVisible or assertText unless tagging @needs-review. When an incremental",
         "allow-list is present, extract ONLY from those files.",
+        "",
+        "Every tap/type/clear/waitForElement/assertVisible/assertText target MUST",
+        "carry an IDENTITY locator: ~accessibility-id, id=resource-id, visible text,",
+        "or an attribute-EQUALITY xpath (//android.widget.Button[@text='Submit']).",
+        "Positional/index-only xpaths (/hierarchy/\u2026/View[3]) are rejected \u2014 imported",
+        "steps have no recorded coordinates, so such a step can never replay.",
         "Write strictly valid JSON."
       ].join("\n");
     }
@@ -347885,6 +347996,32 @@ Write valid JSON only (no markdown fences inside files). Be exhaustive.`;
     function isPlainObject2(value) {
       return !!value && typeof value === "object" && !Array.isArray(value);
     }
+    var LOCATOR_REQUIRING_IMPORT_ACTIONS = /* @__PURE__ */ new Set([
+      "tap",
+      "type",
+      "clear",
+      "waitForElement",
+      "assertVisible",
+      "assertText"
+    ]);
+    function selectorValueHasIdentity(value) {
+      const trimmed = value.trim();
+      if (!trimmed)
+        return false;
+      if (trimmed.startsWith("/") || trimmed.startsWith("(//"))
+        return (0, shared_1.isIdentityMobileXpath)(trimmed);
+      return true;
+    }
+    function stepLocatorLacksIdentity(step) {
+      if (!LOCATOR_REQUIRING_IMPORT_ACTIONS.has(step.action))
+        return false;
+      const target = step.target;
+      if (!target)
+        return true;
+      if ((0, shared_1.mobileLocatorBundleHasIdentity)(target.locatorBundle))
+        return false;
+      return ![target.primary, ...target.fallbacks ?? []].some((value) => typeof value === "string" && selectorValueHasIdentity(value));
+    }
     function isValidStep(value) {
       if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
@@ -347936,6 +348073,13 @@ Write valid JSON only (no markdown fences inside files). Be exhaustive.`;
       if (!o.steps.every(isValidStep)) {
         return { ok: false, reason: "steps: invalid step shape" };
       }
+      const identityless = o.steps.find(stepLocatorLacksIdentity);
+      if (identityless) {
+        return {
+          ok: false,
+          reason: `steps: step ${identityless.order} (${identityless.action}) has no identity locator \u2014 a positional/index xpath cannot replay (imported steps have no recorded coordinates). Use ~accessibility-id, id=resource-id, visible text, or an attribute-equality xpath like //android.widget.Button[@text='Submit'].`
+        };
+      }
       const steps = o.steps.map((step, order) => ({
         ...step,
         order,
@@ -351229,7 +351373,7 @@ var require_package4 = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@validate.qa/runner",
-      version: "1.0.67",
+      version: "1.0.68",
       description: "validate local test runner - execute Playwright tests on your machine, connected to validate.qa cloud.",
       bin: {
         "validate-runner": "dist/cli.js"
@@ -354700,7 +354844,7 @@ function boundsForRun(step, platform3, isCrossPlatform) {
   if (platform3 && hasPlatformLocator(step.target, platform3)) return null;
   return boundsFromStep(step);
 }
-function locatorStrategyForValue(value) {
+function locatorStrategyForValue(value, platform3) {
   const trimmed = value?.trim();
   if (!trimmed) {
     return [];
@@ -354716,7 +354860,8 @@ function locatorStrategyForValue(value) {
   }
   return [
     { using: "accessibility id", value: trimmed },
-    { using: "id", value: trimmed }
+    { using: "id", value: trimmed },
+    ...textIdentityStrategies(trimmed, platform3)
   ];
 }
 function buildLocatorStrategies(target, platform3) {
@@ -354726,19 +354871,19 @@ function buildLocatorStrategies(target, platform3) {
   if (bundle) {
     if (bundle.accessibilityId) strategies.push({ using: "accessibility id", value: bundle.accessibilityId });
     if (bundle.resourceId) strategies.push({ using: "id", value: bundle.resourceId });
+    if (bundle.xpath && isIdentityXpath(bundle.xpath)) strategies.push({ using: "xpath", value: bundle.xpath });
     for (const value of [
-      isEditableMobileClassName(bundle.className) ? void 0 : bundle.text,
+      isEditableMobileClassName(bundle.className) || isStateValueMobileClassName(bundle.className) ? void 0 : bundle.text,
       bundle.contentDesc
     ]) {
       const trimmed = value?.trim();
-      if (trimmed) strategies.push({ using: "xpath", value: identityTextXpath2(trimmed) });
+      if (trimmed) strategies.push(...textIdentityStrategies(trimmed, platform3));
     }
-    if (bundle.xpath) strategies.push({ using: "xpath", value: bundle.xpath });
   }
   if (!(platform3 && hasPlatformLocator(target, platform3))) {
-    strategies.push(...locatorStrategyForValue(target.primary));
+    strategies.push(...locatorStrategyForValue(target.primary, platform3));
     for (const fallback of target.fallbacks ?? []) {
-      strategies.push(...locatorStrategyForValue(fallback));
+      strategies.push(...locatorStrategyForValue(fallback, platform3));
     }
   }
   return strategies.filter((strategy) => strategy.using !== "xpath" || isIdentityXpath(strategy.value)).filter(
@@ -354760,12 +354905,31 @@ function identityTextXpath2(value) {
   const lit = xpathLiteral3(value);
   return `//*[@text=${lit} or @content-desc=${lit} or @label=${lit} or @name=${lit} or @value=${lit}]`;
 }
+function iosPredicateLiteral(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function iosTextIdentityPredicate(value) {
+  const lit = iosPredicateLiteral(value);
+  return `label == ${lit} OR name == ${lit} OR value == ${lit}`;
+}
+function textIdentityStrategies(value, platform3) {
+  const strategies = [];
+  if (platform3 === "IOS") {
+    strategies.push({ using: "-ios predicate string", value: iosTextIdentityPredicate(value) });
+  }
+  strategies.push({ using: "xpath", value: identityTextXpath2(value) });
+  return strategies;
+}
+function isIdentityIosPredicate(value) {
+  return /(?:^|[\s(])(?:name|label|value)\s*==\s*"/.test(value) && !/\b(?:CONTAINS|BEGINSWITH|ENDSWITH|LIKE|MATCHES|IN)\b/i.test(value);
+}
 function isIdentityXpath(value) {
   return /@[A-Za-z_:][-A-Za-z0-9_:.]*\s*=/.test(value) && !/(?:contains|starts-with)\s*\(/i.test(value);
 }
 function isIdentityStrategy(strategy) {
   if (strategy.using === "accessibility id" || strategy.using === "id") return true;
   if (strategy.using === "xpath") return isIdentityXpath(strategy.value);
+  if (strategy.using === "-ios predicate string") return isIdentityIosPredicate(strategy.value);
   return false;
 }
 function buildIdentityLocatorStrategies(target, platform3) {
@@ -354775,15 +354939,18 @@ function buildIdentityLocatorStrategies(target, platform3) {
   if (bundle) {
     if (bundle.accessibilityId) strategies.push({ using: "accessibility id", value: bundle.accessibilityId });
     if (bundle.resourceId) strategies.push({ using: "id", value: bundle.resourceId });
-    for (const value of [bundle.text, bundle.contentDesc]) {
+    if (bundle.xpath && isIdentityXpath(bundle.xpath)) strategies.push({ using: "xpath", value: bundle.xpath });
+    for (const value of [
+      isStateValueMobileClassName(bundle.className) ? void 0 : bundle.text,
+      bundle.contentDesc
+    ]) {
       const trimmed = value?.trim();
-      if (trimmed) strategies.push({ using: "xpath", value: identityTextXpath2(trimmed) });
+      if (trimmed) strategies.push(...textIdentityStrategies(trimmed, platform3));
     }
-    if (bundle.xpath && isIdentityXpath(bundle.xpath)) strategies.push({ using: "xpath", value: bundle.xpath });
   }
   if (!(platform3 && hasPlatformLocator(target, platform3))) {
     for (const value of [target.primary, ...target.fallbacks ?? []]) {
-      for (const strategy of locatorStrategyForValue(value)) {
+      for (const strategy of locatorStrategyForValue(value, platform3)) {
         if (isIdentityStrategy(strategy)) strategies.push(strategy);
       }
     }
@@ -355778,8 +355945,7 @@ async function readElementAttribute(sessionId, elementId, name) {
 function harvestFallbackXpath(platform3, attrs) {
   if (platform3 === "IOS") {
     if (attrs.name) return `//*[@name=${xpathLiteral3(attrs.name)}]`;
-    const text = attrs.label ?? attrs.value;
-    if (text) return identityTextXpath2(text);
+    if (attrs.text) return identityTextXpath2(attrs.text);
     return "//*";
   }
   if (attrs.resourceId) return `//*[@resource-id=${xpathLiteral3(attrs.resourceId)}]`;
@@ -355789,14 +355955,15 @@ function harvestFallbackXpath(platform3, attrs) {
 }
 async function readNativeElementBundle(sessionId, elementId, platform3) {
   const className = await readElementAttribute(sessionId, elementId, platform3 === "IOS" ? "type" : "class") ?? "";
+  const volatileText = isEditableMobileClassName(className) || isStateValueMobileClassName(className);
   if (platform3 === "IOS") {
     const name = await readElementAttribute(sessionId, elementId, "name");
     const label = await readElementAttribute(sessionId, elementId, "label");
     const value = await readElementAttribute(sessionId, elementId, "value");
-    const text2 = label ?? value;
+    const text2 = label ?? (volatileText ? void 0 : value);
     if (!name && !text2) return null;
     const bundle2 = {
-      xpath: harvestFallbackXpath("IOS", { name, label, value }),
+      xpath: harvestFallbackXpath("IOS", { name, text: text2 }),
       className
     };
     if (name) bundle2.accessibilityId = name;
@@ -355805,7 +355972,8 @@ async function readNativeElementBundle(sessionId, elementId, platform3) {
   }
   const resourceId = await readElementAttribute(sessionId, elementId, "resource-id");
   const contentDesc = await readElementAttribute(sessionId, elementId, "content-desc") ?? await readElementAttribute(sessionId, elementId, "contentDescription");
-  const text = await readElementAttribute(sessionId, elementId, "text");
+  const rawText = await readElementAttribute(sessionId, elementId, "text");
+  const text = volatileText ? void 0 : rawText;
   if (!resourceId && !contentDesc && !text) return null;
   const bundle = {
     xpath: harvestFallbackXpath("ANDROID", { text, contentDesc, resourceId }),

package/package.json

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