pj/sanderling
1
0 Fork 0
mirror of https://github.com/priyanshujain/sanderling.git synced 2026-10-02 11:07:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor: rename project uatu -> sanderling (#24)

Browse Source 
* refactor: rename Go module path uatu -> sanderling

Module path github.com/priyanshujain/uatu -> github.com/priyanshujain/sanderling,
including all imports and the proto go_package option. Generated .pb.go files
rewritten in-place; safe to regenerate with protoc later.

* chore(proto): regenerate driverpb after module path rename

The previous sed-based module rename corrupted the embedded descriptor
byte lengths. buf generate rewrites them cleanly.

* refactor: rename CLI binary uatu -> sanderling

Updates Makefile target + UATU_BIN var, .goreleaser project/build IDs,
.gitignore comment, and all user-facing strings in the CLI help text,
error messages, and tests. Binary is now bin/sanderling.

* refactor(sdk): rename Kotlin package dev.uatu.sdk -> dev.sanderling.sdk

Moves sdk/android/src/{main,test}/kotlin/dev/uatu -> dev/sanderling and
rewrites package declarations, imports, and the Gradle namespace. Class
names (Uatu, UatuRuntime) are renamed in a follow-up commit.

* refactor(sidecar): rename Kotlin package dev.uatu.sidecar -> dev.sanderling.sidecar

Moves sidecar/src/{main,test}/kotlin/dev/uatu -> dev/sanderling and
rewrites package declarations, imports, and the application mainClass.

* refactor: rename Uatu API surface -> Sanderling

- Kotlin: Uatu -> Sanderling, UatuRuntime -> SanderlingRuntime (+ files).
- JS host binding: globalThis.__uatu__ -> __sanderling__ (Go verifier,
  spec-api, tests).
- TS interface: UatuRuntime -> SanderlingRuntime; internal tags
  __uatuFormula / __uatuActionGenerator -> __sanderling* variants.
- Go trace: UatuVersion field + uatu_version JSON tag renamed.
- Socket naming: uatu-agent / uatu-agent-reader -> sanderling-agent*.
- Sample app, docs, inline-JS test strings updated to match.

* refactor(examples): rename examples/folio/uatu -> examples/folio/sanderling

Renames the example spec directory; updates justfile paths + gitignore
entries accordingly. Package.json name/description and @uatu/spec
dependency are renamed in the npm + docs commits.

* chore(build): rename gradle property + rootProject.name uatu -> sanderling

- Renames the uatu.version gradle property and all its -P references in
  Makefile, build.gradle.kts files, and .github/workflows/release.yml.
- settings.gradle.kts rootProject.name = "sanderling".
- Renames .env.local.example header + release-cli workflow job name.

* refactor(proto): rename proto package uatu.driver.v1 -> sanderling.driver.v1

Updates the proto package and java_package, regenerates driver.pb.go +
driver_grpc.pb.go, rewrites Kotlin imports and the gRPC ServiceName
assertion in driver_test.go.

* refactor: rename npm package @uatu/spec -> @sanderling/spec

Renames package name in pkg/spec-api/package.json + lockfile, all
consumer imports (examples/folio spec, testdata, verifier tests), the
esbuild alias in cmd/sanderling/test_run.go, and related doc references.

* docs: rename uatu -> sanderling in README, docs, and URLs

- README + docs/{manual,development}/*: narrative + GitHub + Pages URLs.
- POM + npm package.json repo/homepage/bugs URLs.
- .gitignore + embed_stub + Makefile-comment references updated to
  'make sanderling'.
- Minor narrative comments in cmd/sanderling/test_run.go and
  internal/inspect/server.go.

* refactor: rename remaining internal uatu strings -> sanderling

- SANDERLING_TEST_PHONE/OTP env vars (cmd + bundler tests).
- sanderling-sidecar runtime tmp dir + extracted JAR filename.
- Inspect web UI: @sanderling/inspect-web package, title, theme
  localStorage key, RunList empty-state copy, uatu_version TS field.
- Sample app storage key sanderling.ledger.v1.
- Test data: sanderling_test AVD name + com.example.sanderling_test.
- Release docs tarball name template.
This commit is contained in:
pj authored and GitHub committed 2026-04-21 11:57:49 +07:00
1 parent 13bb2feb82
commit 8ccf95c1cf
111 files changed
+514 -514
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/_template/page.html
Vendored
+4 -4
View File
@@ -3,14 +3,14 @@
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>$if(title)$$title$ · $endif$uatu</title>
<title>$if(title)$$title$ · $endif$sanderling</title>
<link rel="stylesheet" href="__ROOT___assets/style.css">
<style>$highlighting-css$</style>
</head>
<body>
<div class="layout">
<aside class="sidebar">
<a class="brand" href="__ROOT__index.html">uatu</a>
<a class="brand" href="__ROOT__index.html">sanderling</a>
<nav>
<h3>Manual</h3>
<ul>
@@ -31,8 +31,8 @@
$body$
</article>
<footer>
<a href="https://github.com/priyanshujain/uatu">github.com/priyanshujain/uatu</a>
· <a href="https://github.com/priyanshujain/uatu/issues/4">v0.1.0 roadmap</a>
<a href="https://github.com/priyanshujain/sanderling">github.com/priyanshujain/sanderling</a>
· <a href="https://github.com/priyanshujain/sanderling/issues/4">v0.1.0 roadmap</a>
</footer>
</main>
</div>
docs/development/architecture.md
+3 -3
View File
@@ -8,7 +8,7 @@ Three processes, two transports.
```mermaid
flowchart TB
subgraph Go["uatu (Go)"]
subgraph Go["sanderling (Go)"]
Bundler[Bundler<br/>esbuild] --> Verifier[Verifier<br/>goja + LTL]
Verifier <--> Runner[Runner]
Runner --> Trace[Trace writer<br/>JSONL + PNG]
@@ -21,7 +21,7 @@ flowchart TB
subgraph Device["Emulator"]
subgraph App["Android app (debug)"]
SDK[uatu-sdk<br/>pause / hierarchy<br/>logs / coverage]
SDK[sanderling-sdk<br/>pause / hierarchy<br/>logs / coverage]
end
end
@@ -33,7 +33,7 @@ flowchart TB
## Processes
**uatu (Go).** The top-level binary. Bundles the spec with esbuild, evaluates it in goja, runs the main loop, dispatches actions through the driver, writes the trace.
**sanderling (Go).** The top-level binary. Bundles the spec with esbuild, evaluates it in goja, runs the main loop, dispatches actions through the driver, writes the trace.
**Maestro sidecar (JVM).** A Kotlin process that wraps `maestro-client` and exposes a gRPC surface matching the `driver.Driver` interface. Handles UI input, screenshots, the system accessibility tree, and OS-level alerts.
docs/development/design-principles.md
+1 -1
View File
@@ -33,7 +33,7 @@ A 30-minute run is about 10,000 steps. Every step has at least one hierarchy dum
A seeded PRNG drives action selection. Spec evaluation is pure given state and snapshots. The bundle hash and seed are recorded in `meta.json`.
uatu does not attempt byte-exact replay. Animation timing, keyboard popup timing, and system daemons are non-deterministic on mobile, and the cost of trying to suppress that is not worth the payoff. Same seed produces a similar trajectory, which is usually enough to reproduce the bug.
sanderling does not attempt byte-exact replay. Animation timing, keyboard popup timing, and system daemons are non-deterministic on mobile, and the cost of trying to suppress that is not worth the payoff. Same seed produces a similar trajectory, which is usually enough to reproduce the bug.
## 6. Fail honest
docs/development/index.md
+1 -1
View File
@@ -6,7 +6,7 @@ title: Development
- [Design principles](./design-principles.html)
- [Architecture](./architecture.html)
- v0.1.0 scope: [issue #4](https://github.com/priyanshujain/uatu/issues/4)
- v0.1.0 scope: [issue #4](https://github.com/priyanshujain/sanderling/issues/4)
## Building the docs site locally
docs/index.md
+3 -3
View File
@@ -1,12 +1,12 @@
---
title: uatu
title: sanderling
---
# uatu
# sanderling
Autonomous property-based testing for mobile apps. Specs in TypeScript. Core in Go. Drives the app under test through Maestro and an in-app SDK.
Alpha: Android emulator only. Scope of v0.1.0 is tracked in [issue #4](https://github.com/priyanshujain/uatu/issues/4).
Alpha: Android emulator only. Scope of v0.1.0 is tracked in [issue #4](https://github.com/priyanshujain/sanderling/issues/4).
## Manual
docs/manual/cli.md
+7 -7
View File
@@ -5,10 +5,10 @@ title: CLI reference
# CLI reference
```
uatu <command> [flags]
sanderling <command> [flags]
```
## `uatu test`
## `sanderling test`
Run a spec against an app for a fixed duration.
@@ -23,7 +23,7 @@ Run a spec against an app for a fixed duration.
| `--seed` | `0` | PRNG seed. `0` uses a random seed and records it in `meta.json`. |
| `--output` | `./runs` | Output directory for traces. |
## `uatu inspect [run-or-runs-dir]`
## `sanderling inspect [run-or-runs-dir]`
Serve a local web UI for browsing traces. The positional argument is optional and may point at either a runs directory (the parent of many runs) or a single run directory (auto-detected by the presence of `meta.json`). Defaults to `./runs`.
@@ -35,11 +35,11 @@ Serve a local web UI for browsing traces. The positional argument is optional an
See [the inspect UI page](inspect.md) for the panel reference and keyboard shortcuts.
## `uatu doctor`
## `sanderling doctor`
Check the host environment for a working uatu setup: Go toolchain, JDK, Maestro availability, emulator reachability, SDK linkage hints.
Check the host environment for a working sanderling setup: Go toolchain, JDK, Maestro availability, emulator reachability, SDK linkage hints.
## `uatu version`
## `sanderling version`
Print the CLI version.
@@ -49,4 +49,4 @@ Print the CLI version.
- `--max-steps` hard cap on step count.
- `--exit-on-violation` stop the run on the first property violation.
Tracked in [issue #4](https://github.com/priyanshujain/uatu/issues/4).
Tracked in [issue #4](https://github.com/priyanshujain/sanderling/issues/4).
docs/manual/getting-started.md
+9 -9
View File
@@ -9,10 +9,10 @@ Install the CLI, link the SDK into your debug build, run a spec.
## Prerequisites
- An Android emulator with API level 30 or newer.
- The app under test built as a debug variant with the uatu Android SDK linked in.
- The app under test built as a debug variant with the sanderling Android SDK linked in.
- `adb` on your PATH.
Run `uatu doctor` to check the host environment.
Run `sanderling doctor` to check the host environment.
## Install
@@ -21,15 +21,15 @@ Run `uatu doctor` to check the host environment.
macOS arm64:
```sh
curl -L https://github.com/priyanshujain/uatu/releases/latest/download/uatu_<version>_darwin_arm64.tar.gz | tar xz
./uatu version
curl -L https://github.com/priyanshujain/sanderling/releases/latest/download/sanderling_<version>_darwin_arm64.tar.gz | tar xz
./sanderling version
```
Linux amd64:
```sh
curl -L https://github.com/priyanshujain/uatu/releases/latest/download/uatu_<version>_linux_amd64.tar.gz | tar xz
./uatu version
curl -L https://github.com/priyanshujain/sanderling/releases/latest/download/sanderling_<version>_linux_amd64.tar.gz | tar xz
./sanderling version
```
Pre-built for `darwin/arm64`, `darwin/amd64`, `linux/amd64`, `linux/arm64`.
@@ -37,7 +37,7 @@ Pre-built for `darwin/arm64`, `darwin/amd64`, `linux/amd64`, `linux/arm64`.
### Spec package (npm)
```sh
npm install --save-dev @uatu/spec
npm install --save-dev @sanderling/spec
```
### Android SDK (Maven Central)
@@ -55,14 +55,14 @@ The repo ships a working sample at `examples/folio`. From that directory:
```sh
npm install
(cd android && ./gradlew installDebug)
uatu test \
sanderling test \
--spec spec.ts \
--bundle-id app.folio \
--platform android \
--duration 2m
```
Pass `--avd <name>` only when no device is connected and you have multiple AVDs; otherwise uatu uses the connected device or boots the single AVD it finds.
Pass `--avd <name>` only when no device is connected and you have multiple AVDs; otherwise sanderling uses the connected device or boots the single AVD it finds.
When the run ends, the trace lands in `runs/<timestamp>/`:
docs/manual/inspect.md
+6 -6
View File
@@ -1,13 +1,13 @@
---
title: uatu inspect
title: sanderling inspect
---
# uatu inspect
# sanderling inspect
`uatu inspect` is a local web UI for exploring runs produced by `uatu test`. It reads `runs/<id>/meta.json` and `runs/<id>/trace.jsonl` and renders each step with its action, screenshot, snapshots, residual formulas, and exceptions.
`sanderling inspect` is a local web UI for exploring runs produced by `sanderling test`. It reads `runs/<id>/meta.json` and `runs/<id>/trace.jsonl` and renders each step with its action, screenshot, snapshots, residual formulas, and exceptions.
```
uatu inspect [run-or-runs-dir] [--port N] [--no-open] [--dev]
sanderling inspect [run-or-runs-dir] [--port N] [--no-open] [--dev]
```
The positional argument can be either a runs directory or a single run directory (auto-detected by the presence of `meta.json`). When omitted, it defaults to `./runs`.
@@ -51,11 +51,11 @@ Two-process loop:
```
make web-dev # bun + vite, http://127.0.0.1:5173
make inspect-dev # uatu inspect --dev, proxies non-API to 5173
make inspect-dev # sanderling inspect --dev, proxies non-API to 5173
```
For a single binary with embedded assets:
```
make uatu # builds web/dist, copies to internal/inspect/dist, then go build
make sanderling # builds web/dist, copies to internal/inspect/dist, then go build
```
docs/manual/runs.md
+4 -4
View File
@@ -4,14 +4,14 @@ title: Runs
# What is a run?
One `uatu test` invocation. Fresh install, spec-driven exploration, then the trace lands in `runs/<timestamp>/`. Typically minutes to hours, not seconds.
One `sanderling test` invocation. Fresh install, spec-driven exploration, then the trace lands in `runs/<timestamp>/`. Typically minutes to hours, not seconds.
A run is not analogous to a unit test. A closer framing is: boot a fuzzer for an hour and see what breaks. Violations are recorded in the trace and exploration continues, so one run can surface many bugs.
## Lifecycle
```
uatu test --spec spec.ts --bundle-id com.example.app --duration 30m
sanderling test --spec spec.ts --bundle-id com.example.app --duration 30m
│
├── uninstall and reinstall the app (clean slate, every run)
├── boot the sidecar, connect the agent socket
@@ -28,7 +28,7 @@ uatu test --spec spec.ts --bundle-id com.example.app --duration 30m
## Why runs are long and linear
uatu does not restart the app every N steps. Each restart throws away two things.
sanderling does not restart the app every N steps. Each restart throws away two things.
**Novelty and coverage signal.** The exploration strategy weights actions by whether they reach previously unseen state. Restarting resets that history.
@@ -62,4 +62,4 @@ A run ends when either of these happens.
The trace is written incrementally, so an interrupted run is still fully inspectable.
Additional termination conditions (`--max-steps`, `--exit-on-violation`, hard crash handling) land in [v0.1.0](https://github.com/priyanshujain/uatu/issues/4).
Additional termination conditions (`--max-steps`, `--exit-on-violation`, hard crash handling) land in [v0.1.0](https://github.com/priyanshujain/sanderling/issues/4).
docs/manual/writing-specs.md
+5 -5
View File
@@ -7,7 +7,7 @@ title: Writing specs
A spec has three parts: extractors, properties, and actions.
```ts
import { extract, always, actions, weighted, Tap, taps, swipes } from "@uatu/spec";
import { extract, always, actions, weighted, Tap, taps, swipes } from "@sanderling/spec";
// 1. Extractors pull values from each observed state.
const loggedIn = extract((s) => !!s.ax.find("id:home-tab-bar"));
@@ -18,7 +18,7 @@ export const properties = {
cartNeverNegative: always(() => cartCount.current >= 0),
};
// 3. Actions are a weighted tree of what uatu is allowed to do.
// 3. Actions are a weighted tree of what sanderling is allowed to do.
export const actions = weighted(
[10, taps],
[2, swipes],
@@ -45,11 +45,11 @@ interface State {
`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.
`snapshots` is populated by the in-app SDK via `Sanderling.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:
sanderling 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.
@@ -145,7 +145,7 @@ When the UI does not expose a value but the app knows it, use the SDK's extracto
```kotlin
// in the app (Android)
Uatu.extract("cart_count") { store.cart.size }
Sanderling.extract("cart_count") { store.cart.size }
```
```ts