Spec language reference

Lookup reference for everything importable from @sanderling/spec. For a worked example, read the case study first.

Module structure

A spec is a TypeScript module evaluated by the Go runner each step. It exports properties and actionsRoot, plus an optional setup:

import { ... } from "@sanderling/spec";

export const properties = { ... };
export const actionsRoot = weighted(...);
export const setup = login;   // optional

setup is an ActionGenerator the runner consults before actionsRoot each step. While it returns actions, they run; when it returns an empty list, the runner falls through to actionsRoot. Use it for preconditions like login and onboarding. If the app later regresses across the precondition (a logout mid-run), setup re-engages on its own.

State

Every extractor callback receives a State:

interface State {
  ax: AccessibilityTree;
  snapshots: Record<string, unknown>;
  lastAction: Action | null;
  logs: readonly LogEntry[];
  exceptions: readonly ExceptionRecord[];
  time: number;   // ms since run start
}

Selectors

Selectors are passed to ax.find(), ax.findAll(), and element-scoped .find() / .findAll().

String selectors

Boolean attributes ("true" / "false") use exact match rather than substring.

Object selectors

Pass an object to apply multiple attribute filters with AND semantics:

s.ax.find({ accessibilityText: "LoginScreen" })
s.ax.find({ testTag: "AccountCard", clickable: true })

Every key-value pair must match. Substring and boolean rules apply per attribute.

Known attribute names are typed; you get autocomplete on testTag, text, content-desc, the boolean states (clickable, enabled, focused, checked, selected), and the cross-platform aliases (identifier, accessibilityIdentifier, accessibilityText, accessibilityLabel, label, resource-id, class, elementType, package, placeholderValue, hintText). Boolean state attributes accept a native true / false. Other attribute keys still type-check as a string-valued fallback so raw driver attributes remain reachable.

Path selectors

An array of object selectors matches a path: each segment is matched within the subtree of the previous match. Arrays work on the tree root and on element-scoped .find/.findAll.

s.ax.find([{ testTag: "LoginScreen" }, { testTag: "LoginEmail" }])
s.ax.findAll([{ testTag: "HomeScreen" }, { testTag: "AccountCard" }])

String selectors chain the same way with >, but only on the tree root (ax.find, ax.findAll):

s.ax.find("id:HomeScreen > descPrefix:account_card:")
s.ax.find("id:LedgerScreen > desc:ledger_balance_display")

Cross-platform aliases

These key aliases are resolved automatically so selectors work across platforms without changes:

AccessibilityElement fields

Fields available on every element returned by find / findAll:

Platform notes

Android

• id maps to the Android resource-id (e.g., com.example:id/button). The id:<value> selector matches by suffix after :id/, so id:button matches com.example:id/button.
• desc maps to content-desc.
• class is the Java view class name (e.g., android.widget.TextView).
• attrs contains raw UIAutomator attributes: package, scrollable, checkable, etc.

iOS

• id maps to the accessibilityIdentifier set via .accessibilityIdentifier in SwiftUI/UIKit.
• desc maps to accessibilityText, which the iOS sidecar builds by merging accessibilityLabel and the element's value (e.g., "Close, icon description"). The desc:<value> selector handles this by also matching when the description starts with <value>, .
• class is the XCUITest element type (e.g., XCUIElementTypeButton).
• attrs contains raw XCUITest attributes: title, placeholderValue, hasFocus, etc.

Web (Chrome)

• id maps to the HTML id attribute.
• desc is derived from aria-label, alt, or title.
• class is the lowercase HTML tag name (e.g., button, input).
• attrs contains all HTML attributes available to CDP.

KMP (Kotlin Multiplatform)

KMP apps are tested identically to native apps. An Android KMP build uses the Android driver; an iOS KMP build uses the iOS driver. There is no separate KMP driver. The accessibility tree structure reflects the target platform, so the same selector portability rules apply.

Extractors

const loggedIn = extract((s) => !!s.ax.find("id:home-tab-bar"));
const route = extract("route", (s) => ...);   // named form

loggedIn.current    // T - value from the current step
loggedIn.previous   // T | undefined - value from the previous step, undefined on first step

Extractors are evaluated before properties and action generators. Use .previous to detect transitions between steps. Named extractors appear by name in the replay UI and trace.

LTL operators

Formula combinators - available on every Formula:

Actions

Constructors

Tap({ on: element | string })
DoubleTap({ on: element | string })
LongPress({ on: element | string })
InputText({ into: element | string, text: string })
Swipe({ from: element | Point, to: element | Point, durationMillis?: number })
Scroll({ direction: "up" | "down" | "left" | "right", in?: element | string })
PressKey({ key: Key })
Wait({ durationMillis: number })

Key values: "back", "home", "enter", "tab", "up", "down", "left", "right".

On web, "back" maps to Backspace and "home" is not supported. All other keys work on all platforms.

Built-in generators

actions(generator)

Wraps a callback that returns Action[]. The callback runs each step the generator is eligible.

const doLogin = actions(() => {
  if (loggedIn.current) return [];
  const submit = loginSubmit.current;
  return submit ? [Tap({ on: submit })] : [];
});

weighted(...entries)

Assembles a weighted tree. Each entry is [weight, generator]. Weights are relative within the tree.

export const actionsRoot = weighted(
  [50, doLogin],
  [10, taps],
  [2,  swipes],
);

whenRoute(routeExtractor, routes, body)

Builds a generator that runs body only when the extractor's current value is in routes (a string or array of strings). Returns an empty list otherwise.

const addTxn = whenRoute(route, ["home", "ledger", "add-transaction"], () => {
  ...
  return [Tap({ on: btn })];
});

Samplers

Every sampler has .generate(). Draws are seeded by the run's PRNG, so a run replays identically from its seed.

const names = from(["Checking", "Savings", "Travel"]);
const amounts = integers().between(1, 500);
// inside an actions() callback:
InputText({ into: nameField, text: names.generate() })
InputText({ into: amountField, text: String(amounts.generate()) })

Defaults

import { defaultActions, doubleTaps } from "@sanderling/spec/defaults";
import { noUncaughtExceptions, noLogcatErrors } from "@sanderling/spec/defaults/properties";

defaultActions is a ready-made weighted tree of the built-in generators: taps and typing at weight 100, scrolls 50, swipes 25, double taps 10. Use it as a baseline pool or as one entry in your own tree.