@delacour/warden-e2e 0.12.1 → 0.14.0

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
@@ -114,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;

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

@@ -123,5 +123,7 @@ export type AttemptBinding = {
 export declare function attemptSession(session: Session, binding: () => AttemptBinding): Session;
 /** The process-wide session (`globalThis[Symbol.for("./session")]`), created on first call. */
 export declare function getSession(opts?: SessionOptions): Session;
+/** The process-wide session if one exists; never creates one (so a caller outside a test opens no device). */
+export declare function peekSession(): Session | undefined;
 /** Closes and forgets the process-wide session, if any. */
 export declare function resetSession(): Promise<void>;