react-native-tapline 1.5.0 → 1.6.1

package/TaplineNative.podspec

@@ -5,7 +5,9 @@ Pod::Spec.new do |s|
   s.license = { :type => 'MIT' }
   s.author = 'Tapline'
   s.homepage = 'https://github.com/tapline/tapline'
-  s.platforms = { :ios => '16.4' }
+  # 15.1 is the floor of Expo SDK 55 and React Native 0.83. CocoaPods skips a pod that needs a newer iOS than the
+  # app, silently, so a higher number here left SDK 55 apps without the module (found by the native CI job).
+  s.platforms = { :ios => '15.1' }
   s.source = { :git => '' }
   s.static_framework = true
   s.dependency 'ExpoModulesCore'

package/dist/actions.d.ts

@@ -22,6 +22,8 @@ export interface SettleOutcome {
 export declare function settle(): Promise<number>;
 /** Like `settle`, and says when the wait ended at the cap: spread it into an action's result. */
 export declare function settleOutcome(): Promise<SettleOutcome>;
+/** An action is starting: only requests begun from now on count as its own. */
+export declare function beginAction(): void;
 type ParsedTarget = {
     kind: 'ref';
     ref: string;
@@ -60,8 +62,12 @@ export declare function labelOf(info: {
 }): string;
 /** What the caller means to do; a point target then picks only an element that does it. */
 type ActionHint = 'press' | 'longPress' | 'toggle' | 'scroll' | 'type';
-/** Resolve a protocol target to exactly one element, or throw not_found / ambiguous. */
-export declare function resolveTarget(raw: unknown, hint?: ActionHint, glassOnly?: boolean): Promise<Resolved>;
+/**
+ * Resolve a protocol target to exactly one element, or throw not_found / ambiguous. A target that isn't there while the screen
+ * is loading (a request in flight, a spinner) is waited for up to the settle cap before `not_found` is answered (AGENT-TOOLS
+ * 1.13 §18.7); the answer after the wait is made from the screen as it is then, so its closest matches are unchanged.
+ */
+export declare function resolveTarget(raw: unknown, hint?: ActionHint, glassOnly?: boolean, loadingWait?: boolean): Promise<Resolved>;
 /** The nearest listed element at or above a host fiber, for naming what covers a target. */
 export declare function describeHit(snapshot: Snapshot, hit: Fiber, actor?: Entry): string;
 /** `back`: what the back button or gesture does, on the focused screen; with a sheet open, closes the sheet. */
@@ -74,6 +80,7 @@ export declare function back(rawParams: unknown): Promise<{
 export type PressSecond = {
     done: true;
     afterMs: number;
+    threw?: string;
 } | {
     done: false;
     reason: string;
@@ -98,7 +105,20 @@ export type PressResult = {
     };
     /** With `again`: the second tap of a double tap. */
     second?: PressSecond;
+    /** Whose handler took the touch, and its message if it threw (AGENT-TOOLS 1.13 §3). Absent on a dry run. */
+    handler?: HandlerFacts;
+    /** Requests that began during the action. Absent on a dry run. */
+    startedRequests?: number;
 } & SettleOutcome;
+/** An own handler (`threw`: its message), or an ancestor's (`element`: that ancestor) that took the touch. */
+export type HandlerFacts = {
+    kind: 'own';
+    threw?: string;
+} | {
+    kind: 'parent';
+    element: TaplineElement;
+    threw?: string;
+};
 export declare function press(params: unknown): Promise<PressResult>;
 export declare function longPress(params: unknown): Promise<PressResult>;
 /** What the SDK asks of the keyboard and the focused input; replaceable so tests need no native side. */

package/dist/actions.js

@@ -5,6 +5,7 @@ exports.configureActions = configureActions;
 exports.onActed = onActed;
 exports.settle = settle;
 exports.settleOutcome = settleOutcome;
+exports.beginAction = beginAction;
 exports.parseTarget = parseTarget;
 exports.labelOf = labelOf;
 exports.resolveTarget = resolveTarget;
@@ -28,6 +29,9 @@ exports.screenshot = screenshot;
 exports.swipe = swipe;
 const react_native_1 = require("react-native");
 const keyboard_1 = require("./keyboard");
+const guard_1 = require("./guard");
+const network_1 = require("./network");
+const loading_1 = require("./loading");
 const native_1 = require("./native");
 const inspect_1 = require("./inspect");
 const source_1 = require("./source");
@@ -39,6 +43,7 @@ const alerts_1 = require("./alerts");
 const fiber_1 = require("./fiber");
 const logs_1 = require("./logs");
 const register_1 = require("./register");
+const idle_1 = require("./idle");
 const settle_1 = require("./settle");
 const types_1 = require("./types");
 var inspect_2 = require("./inspect");
@@ -130,14 +135,90 @@ async function sheetProbe() {
     }
     return null;
 }
+/**
+ * Where `startedRequests()` stood when the action began (or when the last settle ended): a request begun after
+ * it is one the action started (F1).
+ */
+let requestMark = 0;
+/** An action is starting: only requests begun from now on count as its own. */
+function beginAction() {
+    requestMark = (0, network_1.startedRequests)();
+}
+const FRAME_MS = 16;
+/** Whether an open or closing sheet hides the app's motion from the SDK. */
+function sheetPresent() {
+    return (0, inspect_1.openModalHosts)().length > 0 || (0, inspect_1.closingModalHosts)().length > 0;
+}
+/** The elements whose positions say the screen has stopped: the acting ones and the outermost. */
+function watchedFibers() {
+    try {
+        const entries = (0, inspect_1.takeSnapshot)().entries;
+        const picked = new Map();
+        for (const entry of [...entries.filter((e) => e.info.actions.length > 0).slice(0, 6), ...entries.slice(0, 6)]) {
+            picked.set(entry.node.index, entry.node.fiber);
+        }
+        return [...picked.values()];
+    }
+    catch {
+        return [];
+    }
+}
+function sameFrame(a, b) {
+    if (a === null || b === null)
+        return a === b;
+    return Math.abs(a.x - b.x) <= 1 && Math.abs(a.y - b.y) <= 1 && Math.abs(a.width - b.width) <= 1 && Math.abs(a.height - b.height) <= 1;
+}
+/**
+ * A native push, a Lottie or a gesture-handler sheet moves without a commit or an Animated call, so after the
+ * idle hold the visible positions are read twice, a frame apart. Says which element moved, and whether React
+ * committed in between.
+ */
+async function positionsMoved() {
+    const before = (0, register_1.commitRevision)();
+    const fibers = watchedFibers();
+    const read = () => Promise.all(fibers.map((fiber) => (0, inspect_1.measureFiber)(fiber).catch(() => null)));
+    const first = await read();
+    await new Promise((resolve) => setTimeout(resolve, FRAME_MS));
+    const second = await read();
+    const at = first.findIndex((frame, i) => !sameFrame(frame, second[i] ?? null));
+    return { moving: at >= 0 ? (fibers[at] ?? null) : null, committed: (0, register_1.commitRevision)() !== before };
+}
 async function settleNow() {
     const started = Date.now();
     let capped = false;
     const onCap = () => {
         capped = true;
     };
+    // Know-don't-watch (off unless `knowIdle`): answer when every signal the SDK can see is idle and still.
+    // An open sheet is out of its sight, so that keeps today's window and position poll.
+    let knowSpentMs = 0;
+    if ((0, idle_1.isKnowIdle)() && settings.capMs > 0 && !sheetPresent()) {
+        const known = await (0, idle_1.waitUntilIdle)({ frames: 2, capMs: settings.capMs, requestMark });
+        let moving = null;
+        let steady = !known.usedFallback && !known.capped;
+        if (steady && !sheetPresent()) {
+            const check = await positionsMoved();
+            moving = check.moving;
+            steady = moving === null && !check.committed;
+        }
+        if (!known.usedFallback && !sheetPresent() && (steady || known.capped)) {
+            requestMark = (0, network_1.startedRequests)();
+            const settledMs = Math.max(0, Math.min(settings.capMs, Date.now() - started));
+            return known.capped ? { settledMs, settleCapMs: settings.capMs } : { settledMs };
+        }
+        if (known.capped)
+            onCap();
+        knowSpentMs = Math.max(0, Date.now() - started);
+        // Something moved without a commit: today's poll waits for it to stop.
+        const left = settings.capMs - knowSpentMs;
+        if (moving && left > 0) {
+            await (0, settle_1.waitUntilSteady)(() => (0, inspect_1.measureFiber)(moving), { pollMs: SHEET_POLL_MS, capMs: left, now: Date.now, onCap });
+            knowSpentMs = Math.max(0, Date.now() - started);
+        }
+    }
     await (0, settle_1.waitUntilStill)({
         ...settings,
+        capMs: settings.capMs - knowSpentMs,
         onCommit: (listener) => (0, register_1.onCommit)(() => listener()),
         now: Date.now,
         onCap,
@@ -172,6 +253,7 @@ async function settleNow() {
         }
     }
     const settledMs = Math.max(0, Math.min(settings.capMs, Date.now() - started));
+    requestMark = (0, network_1.startedRequests)();
     return capped && settings.capMs > 0 ? { settledMs, settleCapMs: settings.capMs } : { settledMs };
 }
 function badParams(message) {
@@ -207,6 +289,22 @@ function callHandler(name, handler, args) {
         });
     }
 }
+/**
+ * Calls a press handler as `callHandler` does, but a throw is not an error of the action: a person's tap
+ * on a button whose handler throws still happened. The message goes to the logs and to the answer's facts
+ * (AGENT-TOOLS 1.13 §3). Returns the message, or undefined when the handler didn't throw.
+ */
+function callHandlerCaught(name, handler, args) {
+    try {
+        callHandler(name, handler, args);
+    }
+    catch (error) {
+        const message = error instanceof types_1.TaplineError ? error.message.replace(/^[^:]*threw: /, '') : String(error);
+        console.error(`[tapline] ${name} threw: ${message}`);
+        return message.slice(0, 500);
+    }
+    return undefined;
+}
 function parseTarget(raw) {
     if (!(0, types_1.isRecord)(raw))
         throw badParams('target must be an object such as {"testID":"login"}');
@@ -490,8 +588,38 @@ function inFrontLayer(matches) {
     const inAlert = matches.filter((entry) => inStandInAlert(entry.node.fiber));
     return inAlert.length > 0 ? inAlert : matches;
 }
-/** Resolve a protocol target to exactly one element, or throw not_found / ambiguous. */
-async function resolveTarget(raw, hint, glassOnly = false) {
+/**
+ * Resolve a protocol target to exactly one element, or throw not_found / ambiguous. A target that isn't there while the screen
+ * is loading (a request in flight, a spinner) is waited for up to the settle cap before `not_found` is answered (AGENT-TOOLS
+ * 1.13 §18.7); the answer after the wait is made from the screen as it is then, so its closest matches are unchanged.
+ */
+async function resolveTarget(raw, hint, glassOnly = false, loadingWait = true) {
+    try {
+        return await resolveNow(raw, hint, glassOnly);
+    }
+    catch (error) {
+        if (!(error instanceof types_1.TaplineError) || error.code !== 'not_found' || !loadingWait || !isNamedTarget(raw) || settings.capMs <= 0)
+            throw error;
+        await (0, loading_1.waitWhileLoading)({
+            requestMark,
+            capMs: settings.capMs,
+            // Anything but `not_found` (ambiguous, covered) means the target has come.
+            isThere: () => resolveNow(raw, hint, glassOnly).then(() => true, (again) => !(again instanceof types_1.TaplineError && again.code === 'not_found')),
+        });
+        return resolveNow(raw, hint, glassOnly);
+    }
+}
+/** A target by id, label or text: the kinds a screen can still be loading. A ref or a point is never waited for. */
+function isNamedTarget(raw) {
+    try {
+        const kind = parseTarget(raw).kind;
+        return kind === 'testID' || kind === 'label' || kind === 'text';
+    }
+    catch {
+        return false;
+    }
+}
+async function resolveNow(raw, hint, glassOnly = false) {
     const target = parseTarget(raw);
     const snapshot = (0, inspect_1.takeSnapshot)();
     if (target.kind === 'ref') {
@@ -735,7 +863,8 @@ async function assertReachable(snapshot, actor, frame) {
     const name = describe(actor);
     if (right <= left || bottom <= top) {
         throw notActionable('off_screen', `${name} is off screen (at ${Math.round(frame.x)},${Math.round(frame.y)}; the screen is ${width}x${height}). ` +
-            `Scroll to it first ${SCROLL_TO_TARGET_HINT}, or pass force: true to call its handler anyway.`);
+            'It lies in a part of the screen that nothing scrolls (behind a fixed bar, or outside every list); look at the screen, then target something else or report it. ' +
+            'Pass force: true to call its handler anyway.');
     }
     const bar = (0, inspect_1.nativeTabBar)(snapshot);
     const navBar = (0, inspect_1.nativeNavBar)(snapshot);
@@ -944,21 +1073,28 @@ function focusInput(entry, frame) {
             callHandler(key, handler, [pressEvent(entry.node.fiber, frame)]);
     }
 }
+/** The guard a `move` hands to the touch it makes, never part of a plain call. */
+function recipientGuardOf(params) {
+    return params.recipientGuard === undefined ? undefined : (0, guard_1.parseRecipientGuard)(params.recipientGuard);
+}
 async function pressLike(kind, rawParams) {
     const params = paramsOf(rawParams);
     const afterMs = kind === 'press' ? againAfter(params.again) : undefined;
-    const { snapshot, entry } = await resolveTarget(params.target, kind, params.noScroll === true);
+    const guard = recipientGuardOf(params);
+    const { snapshot, entry } = await resolveTarget(params.target, kind, params.noScroll === true, params.dryRun !== true);
     if (entry.tab) {
         if (kind === 'longPress')
             throw notActionable('no_action', `${describe(entry)} has no long-press action`);
         if (params.dryRun === true)
             return { element: (0, inspect_1.toElement)(entry, null), dryRun: true, settledMs: 0 };
+        (0, guard_1.assertRecipient)(guard, entry);
         selectTab(snapshot, entry.tab);
         return { element: (0, inspect_1.toElement)(entry, null), ...keyboardNote(closeKeyboardFor(entry)), ...(await settleOutcome()) };
     }
     if (entry.navBack) {
         if (params.dryRun === true)
             return { element: (0, inspect_1.toElement)(entry, null), dryRun: true, settledMs: 0 };
+        (0, guard_1.assertRecipient)(guard, entry);
         const { route: _route, ...outcome } = await back({});
         return { element: (0, inspect_1.toElement)(entry, null), ...outcome };
     }
@@ -983,6 +1119,8 @@ async function pressLike(kind, rawParams) {
         return { actor: found, handler: own, focusing: isInput };
     };
     let planned = plan(snapshot, entry);
+    // The element the agent named; a scroll may find it again.
+    let touched = entry;
     // Off screen, in the tree: scroll it into view first (AGENT-TOOLS 1.12 §16.2). The policy ran before this call.
     let reach = {};
     let current = snapshot;
@@ -993,11 +1131,12 @@ async function pressLike(kind, rawParams) {
         if (reach.scrolled) {
             const again = await reresolve(planned.actor, kind, params.target);
             current = again.snapshot;
+            touched = again.entry;
             planned = plan(again.snapshot, again.entry);
             await assertRefoundOnScreen(current, planned.actor, reach);
         }
     }
-    const { actor, handler, focusing } = planned;
+    const { actor, handler } = planned;
     const { element, frame } = await elementFor(actor);
     if (reach.scrolls)
         return { element, dryRun: true, scrolls: true, ...(reach.point ? { point: reach.point } : {}), settledMs: 0 };
@@ -1005,25 +1144,40 @@ async function pressLike(kind, rawParams) {
     // A dry run (AGENT-TOOLS 1.8 §11.4): every check ran; nothing is touched.
     if (params.dryRun === true)
         return { element, dryRun: true, ...pointOf(frame), ...forced, settledMs: 0 };
+    // The policy checked this very element: refuse when the one that takes the touch is another now (§18.4).
+    (0, guard_1.assertRecipient)(guard, actor);
     const closedKeyboard = closeKeyboardFor(actor);
+    const requestsBefore = (0, network_1.startedRequests)();
+    let threw;
+    // An input with no onPress of its own was only focused: no handler ran, so none is reported.
+    let handled = handler !== null;
     if (handler)
-        callHandler(handlerName, handler, [pressEvent(actor.node.fiber, frame)]);
+        threw = callHandlerCaught(handlerName, handler, [pressEvent(actor.node.fiber, frame)]);
     else {
         // A finger focuses the input and also fires the input's own onPress (not an ancestor's: the
         // input takes the touch).
         focusInput(actor, frame);
         const own = appHandler(actor, 'onPress');
-        if (own)
-            callHandler('onPress', own, [pressEvent(actor.node.fiber, frame)]);
+        if (own) {
+            handled = true;
+            threw = callHandlerCaught('onPress', own, [pressEvent(actor.node.fiber, frame)]);
+        }
     }
+    // Whose handler it was: the touched element's own, or an ancestor's that took the touch (§3).
+    const facts = !handled ? undefined : (0, fiber_1.sameFiber)(actor.node.fiber, touched.node.fiber)
+        ? { kind: 'own', ...(threw !== undefined ? { threw } : {}) }
+        : { kind: 'parent', element, ...(threw !== undefined ? { threw } : {}) };
     const second = afterMs === undefined ? undefined : await pressAgain(actor, params, afterMs);
+    const settled = await settleOutcome();
     return {
+        ...(facts !== undefined ? { handler: facts } : {}),
+        startedRequests: Math.max(0, (0, network_1.startedRequests)() - requestsBefore),
         element,
         ...(reach.scrolled ? { scrolled: true } : {}),
         ...keyboardNote(closedKeyboard),
         ...forced,
         ...(second !== undefined ? { second } : {}),
-        ...(await settleOutcome()),
+        ...settled,
     };
 }
 /** `again`: a second tap this many milliseconds after the first (a stress double tap, AGENT-TOOLS 1.12 §17.4). */
@@ -1060,8 +1214,9 @@ async function pressAgain(first, params, afterMs) {
         if (params.force !== true)
             await assertReachable(again.snapshot, found, frame);
         const at = Date.now() - started;
-        callHandler('onPress', handler, [pressEvent(found.node.fiber, frame)]);
-        return { done: true, afterMs: at };
+        // A handler that throws on the second tap was reached: that is the app's failure, not a tap that didn't land.
+        const threw = callHandlerCaught('onPress', handler, [pressEvent(found.node.fiber, frame)]);
+        return threw === undefined ? { done: true, afterMs: at } : { done: true, afterMs: at, threw };
     }
     catch (error) {
         const reason = error instanceof types_1.TaplineError
@@ -1195,9 +1350,9 @@ async function moveFocusAboveKeyboard(entry) {
 function keyboardNote(closed) {
     return closed ? { closedKeyboard: true } : {};
 }
-async function resolveInput(snapshot, rawTarget, glassOnly = false) {
+async function resolveInput(snapshot, rawTarget, glassOnly = false, loadingWait = true) {
     if (rawTarget !== undefined && rawTarget !== null) {
-        const { snapshot: snap, entry } = await resolveTarget(rawTarget, 'type', glassOnly);
+        const { snapshot: snap, entry } = await resolveTarget(rawTarget, 'type', glassOnly, loadingWait);
         const input = findActionable(snap, entry, 'type', true);
         if (!input)
             throw notActionable('no_action', `${describe(entry)} is not an input`);
@@ -1230,6 +1385,12 @@ function setNativeText(entry, text) {
         }
     }
 }
+function assertFieldKind(entry, kind) {
+    const isSecure = (0, inspect_1.isSecureInput)(entry.node);
+    if (kind !== undefined && (kind === 'secure') !== isSecure) {
+        throw new types_1.TaplineError('bad_params', `${describe(entry)} is ${isSecure ? 'a secure field' : 'not a secure field'}, not a ${kind} field`, undefined, undefined, { secure: isSecure });
+    }
+}
 async function typeText(rawParams) {
     const params = paramsOf(rawParams);
     const submit = params.submit === true;
@@ -1244,7 +1405,13 @@ async function typeText(rawParams) {
         throw badParams('text is required (or pass submit: true)');
     // Deleting from the end edits what is there, so it never replaces the whole text.
     const replace = params.replace !== false && !deleting;
-    let { snapshot, entry } = await resolveInput(null, params.target, params.noScroll === true);
+    const kind = params.kind;
+    if (kind !== undefined && kind !== 'secure' && kind !== 'plain')
+        throw badParams('kind is "secure" or "plain"');
+    let { snapshot, entry } = await resolveInput(null, params.target, params.noScroll === true, params.dryRun !== true);
+    // A test account's value goes only into the kind of field it is for (AGENT-TOOLS 1.13 §18.6). The refusal
+    // comes before anything is typed or scrolled, and says only whether the field is secure, never its text.
+    assertFieldKind(entry, kind);
     if (entry.info.disabled)
         throw notActionable('disabled', `${describe(entry)} is not editable; ${ENABLE_FIRST}.`);
     // Off screen, in the tree: scroll it into view first (AGENT-TOOLS 1.12 §16.2; the policy ran before this
@@ -1267,6 +1434,8 @@ async function typeText(rawParams) {
                 again = await resolveInput(null, refind);
             }
             assertSameTarget(entry, again.entry);
+            // A recycled row may hold another kind of field under the same names.
+            assertFieldKind(again.entry, kind);
             snapshot = again.snapshot;
             entry = again.entry;
             if (entry.info.disabled)
@@ -1785,7 +1954,7 @@ async function scroll(rawParams) {
     let entry;
     let frame = null;
     if (params.target !== undefined && params.target !== null) {
-        const resolved = await resolveTarget(params.target, 'scroll');
+        const resolved = await resolveTarget(params.target, 'scroll', undefined, params.dryRun !== true);
         const scroller = findActionable(resolved.snapshot, resolved.entry, 'scroll', true);
         if (!scroller)
             throw notActionable('no_action', `${describe(resolved.entry)} is not inside a scroll view`);
@@ -1963,7 +2132,7 @@ async function toggle(rawParams) {
     const params = paramsOf(rawParams);
     if (params.value !== undefined && typeof params.value !== 'boolean')
         throw badParams('value must be a boolean');
-    const first = await resolveTarget(params.target, 'toggle', params.noScroll === true);
+    const first = await resolveTarget(params.target, 'toggle', params.noScroll === true, params.dryRun !== true);
     const plan = (snap, picked) => {
         const found = findActionable(snap, picked, 'toggle', true);
         if (!found)
@@ -2006,6 +2175,7 @@ async function toggle(rawParams) {
         const { element } = await elementFor(control);
         return { element, value: params.value, unchanged: true, ...(reach.scrolled ? { scrolled: true } : {}), settledMs: 0 };
     }
+    (0, guard_1.assertRecipient)(recipientGuardOf(params), control);
     const closedKeyboard = closeKeyboardFor(control);
     callHandler('onValueChange', handler, [next]);
     const outcome = await settleOutcome();