@specific.dev/spectest 0.18.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./src/index.ts",

package/src/mobile.ts

@@ -68,11 +68,17 @@ interface LocatorDesc {
   regex?: { source: string; flags: string };
   name?: string;
   nameExact?: boolean;
+  /** Narrowing applied after resolution (`.first()`/`.last()`/`.nth(i)`) —
+   *  the explicit escape hatch from strict mode. */
+  nth?: number | "first" | "last";
 }
 
 /** A lazy reference to a single element, resolved (with auto-wait) at the
  *  moment an action runs. Mirrors the select-then-act idiom shared by
- *  Playwright, Detox, and RN Testing Library. */
+ *  Playwright, Detox, and RN Testing Library — including Playwright's
+ *  STRICT mode: a locator matching multiple elements throws an
+ *  element-listing error rather than acting on one of them. Narrow with
+ *  `exact: true`, a testID, or {@link first}/{@link nth}. */
 export interface MobileLocator {
   /** Wait for the element to be visible (default 5s, `timeoutMs` overrides),
    *  then touch-tap its center. `durationMs` overrides the touch dwell. */
@@ -94,13 +100,23 @@ export interface MobileLocator {
   /** The element's text content, wrapped. Waits (default 5s) for the
    *  element to become visible; throws if it never does. */
   textContent(): Promise<Wrapped<string | null>>;
+  /** Narrow to the first resolved element — the explicit opt-out from
+   *  strict mode when multiple matches are intentional. */
+  first(): MobileLocator;
+  /** Narrow to the last resolved element. */
+  last(): MobileLocator;
+  /** Narrow to the i-th resolved element (0-based). */
+  nth(index: number): MobileLocator;
 }
 
-/** Map a locator descriptor onto a playwright Locator. The trailing
- *  `.filter({ visible: true }).first()` preserves the pre-Playwright
- *  selection rule: the first VISIBLE match wins, and a hidden duplicate
- *  (e.g. an offscreen menu item with the same label) neither gets picked
- *  nor trips playwright's strict-mode multi-match error. */
+/** Map a locator descriptor onto a playwright Locator — STRICT, exactly
+ *  like stock Playwright: a locator that resolves to multiple elements
+ *  throws an element-listing "strict mode violation" at action time
+ *  instead of silently picking one. (An earlier `.filter({visible})
+ *  .first()` auto-pick deterministically tapped the WRONG element when
+ *  case-insensitive substring matching made two leaves qualify —
+ *  `getByText("Men")` also matches "Wo**men**". Loud beats lucky.)
+ *  Disambiguate with `exact: true`, a testID, or `.first()`/`.nth(i)`. */
 function pwLocator(page: Page, desc: LocatorDesc): Locator {
   let base: Locator;
   switch (desc.kind) {
@@ -126,18 +142,25 @@ function pwLocator(page: Page, desc: LocatorDesc): Locator {
       );
       break;
   }
-  return base.filter({ visible: true }).first();
+  if (desc.nth === "first") return base.first();
+  if (desc.nth === "last") return base.last();
+  if (typeof desc.nth === "number") return base.nth(desc.nth);
+  return base;
 }
 
 /** Short human label for a descriptor, used in event descriptions. */
 function descLabel(desc: LocatorDesc): string {
+  let base: string;
   if (desc.kind === "text") {
-    return desc.regex ? `text /${desc.regex.source}/` : `text ${JSON.stringify(desc.value)}`;
+    base = desc.regex ? `text /${desc.regex.source}/` : `text ${JSON.stringify(desc.value)}`;
+  } else if (desc.kind === "role") {
+    base = desc.name ? `role ${desc.value} ${JSON.stringify(desc.name)}` : `role ${desc.value}`;
+  } else {
+    base = `${desc.kind} ${JSON.stringify(desc.value)}`;
   }
-  if (desc.kind === "role") {
-    return desc.name ? `role ${desc.value} ${JSON.stringify(desc.name)}` : `role ${desc.value}`;
-  }
-  return `${desc.kind} ${JSON.stringify(desc.value)}`;
+  if (desc.nth === "first" || desc.nth === "last") return `${base} .${desc.nth}()`;
+  if (typeof desc.nth === "number") return `${base} .nth(${desc.nth})`;
+  return base;
 }
 
 /** Default wait for a locator action's target to become visible. Override
@@ -223,6 +246,15 @@ function makeLocator(backend: MobileBackend, desc: LocatorDesc): MobileLocator {
         pwLocator(page, desc).textContent({ timeout: DEFAULT_ACTION_TIMEOUT_MS }),
       ) as Promise<Wrapped<string | null>>;
     },
+    first() {
+      return makeLocator(backend, { ...desc, nth: "first" });
+    },
+    last() {
+      return makeLocator(backend, { ...desc, nth: "last" });
+    },
+    nth(index: number) {
+      return makeLocator(backend, { ...desc, nth: index });
+    },
   };
 }