Test Bridge

The test bridge is exposed as window.__sootsimTest in the browser. All test drivers (Detox, Maestro, Playwright) use this API to query the Peach node tree.

Worker-backed reads are asynchronous. Always await bridge results, including find, query, layout, and tree methods:

const node = await window.__sootsimTest.findByTestId('title')
const count = await window.__sootsimTest.getNodeCount()

The signatures below show the resolved values. Depending on the runtime surface, a method can return that value directly or a promise of it.

Find methods

findByText(text: string): SootSimNodeInfo | null
findById(id: string): SootSimNodeInfo | null
findByTestId(testId: string): SootSimNodeInfo | null
findByLabel(label: string): SootSimNodeInfo | null
findByRole(role: string): SootSimNodeInfo | null
findAllByRole(role: string): SootSimNodeInfo[]
findByA11yState(state: object): SootSimNodeInfo | null

Query

queryAll(filter: {
  type?: string
  hasText?: string
  hasId?: string
  hasRole?: string
  hasLabel?: string
  hasHint?: string
  hasState?: object
}): SootSimNodeInfo[]

Inspect

getStyle(id: string): object
getLayout(id: string): { x, y, width, height }
getAbsolutePosition(id: string): { x, y }
isVisible(id: string): boolean
getNodeCount(): number

Debug

dumpTree(maxDepth?: number): string
dumpAccessibilityTree(maxDepth?: number): string
waitForTree(): Promise<void>  // polls until root has children
waitForScreenTransitions(opts?: {
  timeoutMs?: number
  settleMs?: number
  startWindowMs?: number
}): Promise<{
  started: boolean
  settled: boolean
  timedOut: boolean
  activeCount: number
  peakActiveCount: number
  waitedMs: number
}>

Runtime introspection and profiling

Beyond querying the tree, __sootsimTest is a full runtime debugger: the same surface the CLI’s debug and describe commands drive. The categories:

+
Animation tracing: listAnimations, getAnimation, enableAnimationTrace / disableAnimationTrace, getAnimationTrace. Answer “did this animation actually run, or snap?” frame by frame.
+
Perf / diagnostics: getCullStats, getImageLoaderStats, getIncrementalYogaVerifier (checks the layout dirty-tracking against a full recompute), getWorkletSlotStats, workerDebugState.
+
Network interception: getRequests, getFailedRequests, getRequestCounts, clearRequests.
+
Input / text introspection: getFocusedNode, getFocusKeyboardSnapshot, getTextInputDisplayText, getTextSelection, getLoupeState, getEditMenuState.
+
Inspect tooling: inspectAt, inspectHoverAt, inspectSetStyleOverride.
+
Scroll / navigation state: getScrollState, getScrollSnapshots, getNavigationSnapshot, isNavigationIdle.
+
Direct dispatch: activatePressByText / activatePressById, openDeepLink, scrollTo.

Most debugging is easier through the CLI (peach debug, peach describe) than by calling these directly, since the CLI wraps this bridge with settling and formatting.

SootSimNodeInfo

{
  nodeId: number
  type: string
  id: string | null
  testID: string | null
  text: string | null
  style: Record<string, unknown>
  layout: {
    x: number
    y: number
    width: number
    height: number
  }
  absolutePosition: {
    x: number
    y: number
  }
  childCount: number
  pressed: boolean
  pressable: boolean
  accessible: boolean
  accessibilityLabel: string | null
  accessibilityRole: string | null
  accessibilityHint: string | null
  accessibilityState: object | null
  accessibilityValue: object | null
}

Agent Skills

Detox Driver

Test Bridge

#Find methods

#Query

#Inspect

#Debug