docs: pandoc-based site and v0.1.0 groundwork (#5)

* chore(prose): remove em-dashes from config files * chore(prose): remove em-dashes from android sdk config * docs(spec-api): remove em-dash from README * fix(doctor): reword sidecar-jar error without em-dash * test(sidecar): reword assertion message without em-dash * docs: add CLAUDE.md with project conventions * build: add docs target for pandoc site * docs(site): add pandoc template and stylesheet * docs(site): add pandoc build script * docs(site): add landing pages * docs(manual): add getting-started * docs(manual): add writing-specs * docs(manual): add runs * docs(manual): add cli reference * docs(dev): add design principles * docs(dev): add architecture * ci: deploy docs site to github pages * docs: rewrite README as entry point to docs site
2026-10-02 11:07:10 +00:00 · 2026-04-18 14:00:57 +07:00
1 parent a74d9fbeae
commit e62319e916
@@ -0,0 +1,193 @@
+---
+title: Writing specs
+---
+
+# Writing specs
+
+A spec has three parts: extractors, properties, and actions.
+
+```ts
+import { extract, always, actions, weighted, Tap, taps, swipes } from "@uatu/spec";
+
+// 1. Extractors pull values from each observed state.
+const loggedIn = extract((s) => !!s.ax.find("id:home-tab-bar"));
+const cartCount = extract<number>((s) => (s.snapshots.cart_count as number) ?? 0);
+
+// 2. Properties are LTL formulas evaluated every step.
+export const properties = {
+  cartNeverNegative: always(() => cartCount.current >= 0),
+};
+
+// 3. Actions are a weighted tree of what uatu is allowed to do.
+export const actions = weighted(
+  [10, taps],
+  [2, swipes],
+);
+```
+
+The Go runner calls into the JS runtime each step. Extractors re-read the current state. Properties re-evaluate with their residual formulas. The action generator returns a tree, and one leaf is sampled by weight and dispatched.
+
+## The `State` object
+
+What extractors see:
+
+```ts
+interface State {
+  ax: AccessibilityTree;               // view hierarchy
+  snapshots: Record<string, unknown>;  // values registered by the in-app SDK
+  screen: { id: string; hash: string };
+  lastAction: Action | null;
+  logs: LogEntry[];                    // since previous state
+  exceptions: Exception[];
+  time: number;                        // ms since run start
+}
+```
+
+`ax.find("text:Click me")`, `ax.find("id:login-form")`, `ax.findAll("role:todo-row")` are the common accessors. Prefer stable testID-style identifiers over positional selectors, for the same reason you would in Espresso or XCUITest.
+
+`snapshots` is populated by the in-app SDK via `Uatu.extract("name") { value }`. Use it when the UI does not expose a value you need, such as business-logic state or hidden fields.
+
+## Pattern: preconditions (login, onboarding)
+
+uatu has no setup phase and no fixtures. Preconditions are action generators with two properties:
+
+1. High weight, so they fire whenever applicable.
+2. Gated on a state extractor, so they return an empty tree when not applicable and self-disable once the precondition is met.
+
+```ts
+const onLoginScreen = extract((s) => !!s.ax.find("id:login-form"));
+
+const doLogin = actions(() => {
+  if (!onLoginScreen.current) return [];
+  const emailField = state.ax.find("id:email-field");
+  const signInButton = state.ax.find("id:sign-in-button");
+  if (!emailField || !signInButton) return [];
+  return [
+    InputText({ into: emailField, text: "[email protected]" }),
+    Tap({ on: signInButton }),
+  ];
+});
+```
+
+Stack these for onboarding, consent dialogs, cold-start flows:
+
+```ts
+const dismissOnboarding = actions(() => {
+  const skip = state.ax.find("text:Skip");
+  return skip ? [Tap({ on: skip })] : [];
+});
+
+export const actions = weighted(
+  [100, dismissOnboarding],  // clear the path first
+  [50,  doLogin],            // log in when the login screen appears
+  [10,  taps],               // exploration
+  [2,   swipes],
+);
+```
+
+Lifecycle of a run:
+
+```
+Step 1:   fresh install, onboarding visible
+          eligible: dismissOnboarding (weight 100)
+          picks: Tap "Skip"
+
+Step 2-3: login screen visible
+          eligible: doLogin (weight 50)
+          picks: InputText / Tap to sign in
+
+Step 4+:  home screen, onboarding and login generators return []
+          eligible: taps, swipes
+          picks: autonomous exploration
+```
+
+Session state (tokens, keychain, prefs) persists through the rest of the run. If the app logs the user out mid-run, `doLogin` re-fires automatically. No retry logic, no special-casing.
+
+## Pattern: conditional properties
+
+Use gating extractors the same way inside properties. Express "only check X when Y holds":
+
+```ts
+const loggedIn = extract((s) => !!s.ax.find("id:home-tab-bar"));
+
+export const properties = {
+  cartPersistsWhenLoggedIn: always(() => {
+    if (!loggedIn.current) return true;
+    return state.snapshots.cart_count !== undefined;
+  }),
+};
+```
+
+When `implies` ships in v0.1.0, this becomes:
+
+```ts
+cartPersistsWhenLoggedIn: always(() =>
+  implies(loggedIn.current, () => cartCount.current !== undefined)
+),
+```
+
+## Pattern: eventually (once the operator lands)
+
+`always` asserts something holds at every step. `eventually` asserts it holds at some step, usually with a time bound:
+
+```ts
+// v0.1.0+
+loginSucceedsWithin30s: eventually(
+  () => loggedIn.current
+).within(30, "seconds"),
+```
+
+Useful for liveness checks: the loading spinner eventually goes away, the deep link eventually lands on `/home`.
+
+## Pattern: snapshot-backed properties
+
+When the UI does not expose a value but the app knows it, use the SDK's extractor registry:
+
+```kotlin
+// in the app (Android)
+Uatu.extract("cart_count") { store.cart.size }
+```
+
+```ts
+// in the spec
+const cartCount = extract<number>((s) => (s.snapshots.cart_count as number) ?? 0);
+
+export const properties = {
+  cartMonotonicAfterAdd: always(() => {
+    const previous = cartCount.previous;
+    return previous === undefined || cartCount.current >= previous;
+  }),
+};
+```
+
+This pattern lets you write properties against business logic that no UI element exposes.
+
+## Pattern: weighted exploration sub-trees
+
+Nest `weighted` to group related actions and tune their collective rate:
+
+```ts
+export const actions = weighted(
+  [100, dismissOnboarding],
+  [50,  doLogin],
+  [10,  taps],
+  [2,   swipes],
+  [1, weighted(
+    [3, openLink("todos://home")],
+    [1, openLink("todos://settings")],
+    [1, openLink("todos://item/42/edit")],
+  )],
+);
+```
+
+Weights are relative within a tree, so nested trees get their own local budget. This is how you keep low-frequency but high-value actions (deep links, background/foreground, rotate) from drowning out normal tapping.
+
+## Anti-patterns
+
+**Positional taps.** `Tap({ on: { x: 100, y: 200 } })` works for a demo but breaks on any layout change. Always prefer an `ax.find("id:...")` reference.
+
+**Sleep or wait-for-time.** `Wait(3000)` inside an action generator is a smell. If you need to wait for a condition, use an extractor and gate the next action on it.
+
+**Retry logic inside generators.** Generators should be pure: given the same state they produce the same actions. Retry is the runner's responsibility.
+
+**Unbounded `eventually`.** Without a `.within(...)`, `eventually` never fails within a finite run. It just stays residual. Almost always you want a bound.