@delacour/warden-e2e 0.13.0 → 0.14.0

package/types/e2e/src/driver/settle.d.ts

@@ -33,6 +33,14 @@ export declare function settleDetailOf(outcome: SettleOutcome): SettleDetail;
 export declare const DEFAULT_SETTLE_QUIET_MS = 250;
 /** How long a settle waits for quiet before it gives up. */
 export declare const DEFAULT_SETTLE_TIMEOUT_MS = 3000;
+/**
+ * The shortest window a snapshot-hash settle fallback waits (iOS, and `device.settle` on a driver without one). A navigation push exposes both screens at their final
+ * frames for 300-460 ms before the old one leaves the tree, so two equal reads 250 ms apart can settle on that mixed
+ * tree. The helper's own snapshot fallback (`FrameStability.minQuietMs`) uses the same floor.
+ */
+export declare const HASH_FALLBACK_MIN_QUIET_MS = 500;
+/** The quiet window a hash fallback uses for a caller's `quietMs`. */
+export declare function hashFallbackQuietMs(quietMs: number): number;
 /**
  * Snapshot-hash settle: poll a UI fingerprint until it stays unchanged for `quietMs`
  * (two consecutive equal hashes and ≥ quietMs since the last change), or give up at `timeoutMs`.

package/types/e2e/src/errors.d.ts

@@ -1,5 +1,7 @@
 import type { ErrorResult } from "../../types/src/result";
-export type E2eErrorCode = "LOCATOR_NOT_FOUND" | "LOCATOR_AMBIGUOUS" | "INVALID_LOCATOR" | "ACTION_FAILED" | "TIMEOUT" | "NOT_ACTIONABLE" | "INVALID_ARGUMENT" | "SESSION" | "DRIVER" | "ASSERTION" | "PERF_BUDGET" | "RUN_FAILED";
+export type E2eErrorCode = "LOCATOR_NOT_FOUND" | "LOCATOR_AMBIGUOUS" | "INVALID_LOCATOR" | "ACTION_FAILED" | "TIMEOUT" | "NOT_ACTIONABLE" | "INVALID_ARGUMENT" | "SESSION" | "DRIVER" | "ASSERTION" | "PERF_BUDGET" | "RUN_FAILED"
+/** a read that fell back from its first reader (or came back an empty root) could not confirm the locator either way */
+ | "READ_DEGRADED";
 /** Plain shape of a spec error: what `e2eErr()` accepts and what a `Result` carries. */
 export type E2eErrorShape = {
     code: E2eErrorCode;

package/types/e2e/src/expect/matchers.d.ts

@@ -81,6 +81,11 @@ export declare class LocatorAssertions {
     toHaveCount(expected: number, options?: AssertionOptions): Promise<void>;
     private assert;
     private poll;
+    /**
+     * What one look says about `spec`: a judgement (from the accessibility tree, or from the React tree for a degraded
+     * read it answered), or `unsettled` when the read was degraded and nothing could say whether the locator is there.
+     */
+    private judgeLook;
     /** The screen is rendered here, from the last snapshot read, because only a failure needs the text. */
     private failure;
 }

package/types/e2e/src/runner/bridge-evidence.d.ts

@@ -0,0 +1,12 @@
+import type { TestResult } from "./results";
+import type { TraceEvent } from "./trace";
+export type BridgeEvidence = NonNullable<TestResult["bridge"]>;
+/**
+ * Collects an attempt's iOS bridge fallbacks from its spans for `results.jsonl` (`bridge`): reads answered by `ax`
+ * in place of `axbridge`, and failed reads that carried a stall report. A read the bridge answered by pid (frontmost
+ * unresolved) is not one.
+ */
+export declare function bridgeEvidence(): {
+    observe(event: TraceEvent): void;
+    summary(): BridgeEvidence | undefined;
+};

package/types/e2e/src/runner/results.d.ts

@@ -26,6 +26,35 @@ export declare const testResultSchema: z.ZodObject<{
         dir: z.ZodString;
         files: z.ZodArray<z.ZodString>;
     }, z.core.$strip>>;
+    bridge: z.ZodOptional<z.ZodObject<{
+        fallbacks: z.ZodNumber;
+        first: z.ZodObject<{
+            reason: z.ZodOptional<z.ZodString>;
+            code: z.ZodOptional<z.ZodString>;
+            stage: z.ZodOptional<z.ZodString>;
+            readMs: z.ZodOptional<z.ZodNumber>;
+            deadlineMs: z.ZodOptional<z.ZodNumber>;
+            guestAgeMs: z.ZodOptional<z.ZodNumber>;
+            cold: z.ZodOptional<z.ZodBoolean>;
+            cooldownRemainingMs: z.ZodOptional<z.ZodNumber>;
+            probes: z.ZodOptional<z.ZodNumber>;
+            recycles: z.ZodOptional<z.ZodNumber>;
+            recyclesExhausted: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>;
+        last: z.ZodObject<{
+            reason: z.ZodOptional<z.ZodString>;
+            code: z.ZodOptional<z.ZodString>;
+            stage: z.ZodOptional<z.ZodString>;
+            readMs: z.ZodOptional<z.ZodNumber>;
+            deadlineMs: z.ZodOptional<z.ZodNumber>;
+            guestAgeMs: z.ZodOptional<z.ZodNumber>;
+            cold: z.ZodOptional<z.ZodBoolean>;
+            cooldownRemainingMs: z.ZodOptional<z.ZodNumber>;
+            probes: z.ZodOptional<z.ZodNumber>;
+            recycles: z.ZodOptional<z.ZodNumber>;
+            recyclesExhausted: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
     device: z.ZodObject<{
         udid: z.ZodString;
         platform: z.ZodEnum<{

package/types/e2e/src/screen/context.d.ts

@@ -4,7 +4,7 @@ import { E2eError } from "../errors";
 import type { SpanOptions, SpanRunner } from "../runner/span";
 import { type NodeIndex } from "./nodes";
 import { type Clock, type PollResult, type PollStep } from "./poll";
-import { type ReactMatch } from "./react-locator";
+import { type ReactLookup, type ReactMatch } from "./react-locator";
 import type { TextMatch } from "./text";
 /**
  * What `screen` and `Locator` need from the test session. `Session` satisfies it as is; the optional members are
@@ -78,8 +78,6 @@ export declare class Runtime {
     private reactCache;
     /** the index of each snapshot, so a snapshot that several reads share is indexed once */
     private readonly indexed;
-    /** the time before which a degraded look is not retried on its first reader, after that reader failed to answer */
-    private firstReaderRetryAt;
     constructor(host: ScreenHost);
     get clock(): Clock;
     actionTimeout(): number;
@@ -97,14 +95,6 @@ export declare class Runtime {
      * `systemAlerts` on, an alert the screen shows is answered and the screen looked at again.
      */
     tryObserve(options?: ObserveOptions): Promise<Observation>;
-    /**
-     * A snapshot the driver answered from a fallback reader (`Snapshot.fellBackFrom`, iOS `ax` after `axbridge` stalled)
-     * can lack what the first reader has: React Native testIDs on static text. Such a look is read once more on the
-     * first reader, and that read replaces it when it answers. When it does not (the guest is still silent) the
-     * fallback snapshot stands and the first reader is left alone for `FIRST_READER_RETRY_MS`, so a dead guest costs a
-     * poll one deadline, not one per attempt. Every locator and matcher looks through here, so none needs its own rule.
-     */
-    private restoreDegraded;
     /** What came before `look`, given the cache's answer from just before it was taken. */
     private earlierThan;
     /** Whether `snapshot` showed an alert that has now been answered. A screen without one costs no extra read. */
@@ -124,6 +114,13 @@ export declare class Runtime {
      * Empty without devtools. Reads are throttled: inside the window the previous answer for the same query is reused.
      */
     reactMatches(testId: TextMatch, observed: Observed): Promise<ReactMatch[]>;
+    /** Whether the host has devtools to ask the React tree through. */
+    hasReactTree(): boolean;
+    /**
+     * `reactMatches`, keeping "the React tree could not be read" (`answered: false`, also without devtools) apart from
+     * "it has no such component", for a degraded read that must not take the first for the second.
+     */
+    reactLookup(testId: TextMatch, observed: Observed): Promise<ReactLookup>;
     /**
      * The interactive part of the tree as text, for failure messages. It indexes the snapshot again and renders up to
      * `EXCERPT_LINES` lines, so call it only once an error is certain; keep the snapshot, not this text, while polling.

package/types/e2e/src/screen/degraded-read.d.ts

@@ -0,0 +1,23 @@
+import type { Snapshot, SnapshotBackend } from "../driver/driver.types";
+import { E2eError } from "../errors";
+/**
+ * Why a snapshot cannot say a node is absent: it was answered by a fallback reader (`Snapshot.fellBackFrom`, iOS `ax`
+ * after `axbridge` stalled, which drops React Native testIDs on static text), or it is one childless root with no
+ * area (the reader could not see into the app). A match found on such a snapshot is real; a missing one is unknown.
+ */
+export type DegradedRead = {
+    kind: "fallback";
+    from: SnapshotBackend;
+    backend: SnapshotBackend;
+} | {
+    kind: "emptyRoot";
+    backend: SnapshotBackend;
+};
+/** What makes `snapshot` inconclusive about absence; undefined for a whole read. */
+export declare function degradedRead(snapshot: Snapshot): DegradedRead | undefined;
+/** One phrase naming what was degraded, with the fallback and read backend. */
+export declare function describeDegraded(read: DegradedRead): string;
+/** Why the React tree did not settle it. */
+export type ReactNote = "unanswered" | "no-devtools" | "not-testid";
+/** `READ_DEGRADED`: the bridge is degraded and `locator` could be confirmed neither present nor absent in `waitedMs`. */
+export declare function degradedFailure(locator: string, read: DegradedRead, waitedMs: number, react: ReactNote, screen?: string): E2eError;

package/types/e2e/src/screen/locator.d.ts

@@ -1,10 +1,13 @@
 import type { KeyName, Modifier, Point, Rect } from "../driver/driver.types";
+import { E2eError } from "../errors";
 import { type Momentum, type SwipeDirection } from "./actions";
 import type { Observed, Runtime } from "./context";
+import { type DegradedRead, type ReactNote } from "./degraded-read";
 import { type FillVia } from "./field";
 import type { NodeEntry } from "./nodes";
 import { type RoleOptions, type TestIdOptions, type TextQueryOptions } from "./queries";
 import { type LocatorExpression } from "./query";
+import { type ReactMatch } from "./react-locator";
 import type { QueryRole } from "./roles";
 import { type TextMatch } from "./text";
 export type ActionOptions = {
@@ -69,6 +72,21 @@ export type WaitState = "attached" | "detached" | "visible" | "hidden";
 export type WaitForOptions = ActionOptions & {
     state?: WaitState;
 };
+/**
+ * What one look says about a locator. `nodes`: the accessibility tree's answer (none included, when the read was whole
+ * or the React tree confirmed the absence). `react`: the read was degraded and the React tree has the component(s).
+ * `unknown`: the read was degraded (`screen/degraded-read.ts`) and nothing could confirm the locator either way.
+ */
+export type Resolved = {
+    kind: "nodes";
+    entries: NodeEntry[];
+} | {
+    kind: "react";
+    matches: ReactMatch[];
+} | {
+    kind: "unknown";
+    read: DegradedRead;
+};
 declare const LOCATOR_BRAND: unique symbol;
 /** Whether `value` is a `Locator` (also across duplicated copies of this module, e.g. the bundled entry and the preload). */
 export declare function isLocator(value: unknown): value is Locator;
@@ -102,7 +120,28 @@ export declare class Locator {
         entries: NodeEntry[];
         observed: Observed;
     }>;
+    /**
+     * What `observed` says about this locator. A whole read, or one with matches, is the accessibility tree's answer. A
+     * degraded read with no match is asked of the React tree (plain `getByTestId` with devtools): it answers presence or
+     * absence; otherwise the look is `unknown`, and no caller may take it as "absent". A component whose rect is an
+     * accessibility node's (the fallback reader kept the node, dropped the testID) resolves to that node, so text,
+     * visibility and actions read it like any match; one with no such node stays a React-only match.
+     */
+    resolveIn(observed: Observed): Promise<Resolved>;
+    /** Why the React tree did not settle a degraded look, for the `READ_DEGRADED` message. */
+    reactNote(): ReactNote;
+    /** `READ_DEGRADED` for this locator after `waitedMs`, with the screen of the last degraded look. */
+    degradedFailure(read: DegradedRead, waitedMs: number, snapshot: Observed["snapshot"] | undefined): E2eError;
+    /**
+     * One look that settles this locator. A whole read answers at once (never waits); a degraded one that cannot say
+     * whether the locator is there is looked at again until one can, within the action timeout, then `READ_DEGRADED`.
+     */
+    private conclusive;
+    /** The conclusive answer of `observed`, or undefined while it is `unknown`. */
+    private settled;
     private matches;
+    /** The one React match a read of a component the accessibility tree lacks stands for; several are ambiguous. */
+    private reactOnly;
     private single;
     /** Components of the React tree that this locator names, when it is a plain `getByTestId` and the app has devtools. */
     private reactCandidates;
@@ -113,6 +152,8 @@ export declare class Locator {
     all(): Promise<Locator[]>;
     text(): Promise<string>;
     allTexts(): Promise<string[]>;
+    /** The text the React tree reported for a component of a degraded read that no accessibility node stands for. */
+    private reactText;
     value(): Promise<string>;
     isVisible(): Promise<boolean>;
     /**
@@ -124,7 +165,11 @@ export declare class Locator {
      */
     read(): Promise<LocatorReading>;
     /** Whether this locator's one match is visible in `observed`; no match is not visible, several matches throw. */
-    visibleIn(observed: Observed): boolean;
+    /**
+     * Whether `observed` shows this locator, without waiting: a degraded read is resolved like `resolveIn` (the React
+     * tree's node or rect), and one nothing could settle counts as not shown yet.
+     */
+    shownIn(observed: Observed): Promise<boolean>;
     isHidden(): Promise<boolean>;
     isEnabled(): Promise<boolean>;
     isChecked(): Promise<boolean>;

package/types/e2e/src/screen/react-locator.d.ts

@@ -11,17 +11,32 @@ export type ReactMatch = {
     testId: string;
     /** the component's name (`View`, `Button`, ...) */
     name: string;
+    /** the strings rendered inside it, when the React tree reported any */
+    text?: string;
 };
 export type ReactView = {
     platform: Platform;
     screen: ScreenInfo;
 };
+/** What the React tree said: `answered: false` when it could not be read (no devtools, a failed or timed-out read). */
+export type ReactLookup = {
+    answered: true;
+    matches: ReactMatch[];
+} | {
+    answered: false;
+};
 /**
  * Components of the running app whose `testID` matches, with rects in the driver's pixels. This is the fallback for
  * `getByTestId` when the platform hides the view from accessibility (React Native only exposes `testID` to
- * accessibility on some views). Any devtools failure means "nothing found", so callers keep their own not-found
- * error. Android measures in dp but the driver taps in px: `view.screen.scale` converts.
+ * accessibility on some views), and the second opinion on a degraded read. A devtools failure is `answered: false`,
+ * kept apart from an empty answer so a caller can tell "absent" from "cannot tell". Android measures in dp but the
+ * driver taps in px: `view.screen.scale` converts.
  */
+export declare function lookUpTestIdViaReact(facet: Pick<DevtoolsFacet, "tree">, testId: TextMatch, view: ReactView, options?: {
+    screenName?: string;
+    timeoutMs?: number;
+}): Promise<ReactLookup>;
+/** `lookUpTestIdViaReact` where any failure means "nothing found", so callers keep their own not-found error. */
 export declare function locateByTestIdViaReact(facet: Pick<DevtoolsFacet, "tree">, testId: TextMatch, view: ReactView, options?: {
     screenName?: string;
     timeoutMs?: number;

package/types/e2e/src/screen/react-merge.d.ts

@@ -0,0 +1,10 @@
+import type { NodeEntry, NodeIndex } from "./nodes";
+import type { ReactMatch } from "./react-locator";
+/**
+ * The accessibility node a React component stands for on a degraded read: a fallback reader (iOS host `ax`) keeps the
+ * node but drops its testID, so the component's rect is what ties the two. Never a node that carries another testID,
+ * never an area-less rect. Several nodes with the rect: the one whose own text is the component's, else the deepest.
+ */
+export declare function nodeOfReactMatch(match: ReactMatch, index: NodeIndex): NodeEntry | undefined;
+/** The node of every match, each a different node; undefined when one of them has none (the React tree answers alone). */
+export declare function mergeReactMatches(matches: readonly ReactMatch[], index: NodeIndex): NodeEntry[] | undefined;