mirror of
https://github.com/priyanshujain/sanderling.git
synced 2026-10-02 11:07:10 +00:00
refactor: rename project uatu -> sanderling (#24)
* 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:
111 files changed
+514
-514
No files matched your search
+7
-7
@@ -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).
|
||||
@@ -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>/`:
|
||||
|
||||
|
||||
@@ -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
|
||||
```
|
||||
+4
-4
@@ -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).
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user