mirror of
https://github.com/priyanshujain/sanderling.git
synced 2026-10-02 19:17:10 +00:00
docs(manual): make getting started target the reader's own app, not Folio
This commit is contained in:
pj committed
1 parent
44ba5f6d66
commit
5b1c339da8
1 file changed
+22
-89
@@ -4,129 +4,62 @@ title: Getting started
|
||||
|
||||
# Getting started
|
||||
|
||||
This page installs sanderling and runs a first test against folio, the example app that ships with the repo. By the end you will have a trace of a real run open in your browser.
|
||||
|
||||
If you have not read the [introduction](../introduction/), start there. It explains what sanderling does and how it works.
|
||||
Install sanderling, write a spec for your app, run it, and open the trace.
|
||||
|
||||
## Install
|
||||
|
||||
Install the CLI:
|
||||
The CLI:
|
||||
|
||||
```sh
|
||||
curl -fsSL https://raw.githubusercontent.com/priyanshujain/sanderling/master/install.sh | bash
|
||||
```
|
||||
|
||||
Specs import from the `@sanderling/spec` package on [npm](https://www.npmjs.com/package/@sanderling/spec). Install it in the project where your spec lives:
|
||||
The spec package, in your project:
|
||||
|
||||
```sh
|
||||
npm install --save-dev @sanderling/spec
|
||||
```
|
||||
|
||||
The example apps already depend on it, so for this page the CLI is enough.
|
||||
|
||||
## Check your environment
|
||||
|
||||
```sh
|
||||
sanderling doctor
|
||||
```
|
||||
|
||||
`doctor` checks each platform and tells you what is missing. What each platform needs:
|
||||
`doctor` reports what the target platform needs and what is missing:
|
||||
|
||||
- **Web**: Chrome. Nothing else.
|
||||
- **Android**: `adb` on your PATH, and an emulator (API level 30 or newer) or a connected device.
|
||||
- **iOS**: Xcode 16 or newer, with a simulator.
|
||||
- **Android**: `adb` on your PATH, and an emulator (API 30 or newer) or a connected device.
|
||||
- **iOS**: Xcode 16 or newer, with a simulator. For a connected iPhone, run `sanderling doctor --platform ios-device`.
|
||||
- **Web**: Chrome.
|
||||
|
||||
Web is the easiest place to start. If you have Chrome, you can run a test right now.
|
||||
## Write a spec
|
||||
|
||||
## Your first run
|
||||
A spec exports two things: `properties` that must always hold, and `actionsRoot`, the actions sanderling may take. The smallest spec that does something useful imports both from the defaults:
|
||||
|
||||
Clone the repo and pick an example app. Both are small personal-ledger apps: log in, create accounts, add transactions.
|
||||
```ts
|
||||
import { defaultActions } from "@sanderling/spec/defaults";
|
||||
import { noUncaughtExceptions } from "@sanderling/spec/defaults/properties";
|
||||
|
||||
- `examples/folio` is a Kotlin Multiplatform app. One codebase builds for Android, iOS, and web.
|
||||
- `examples/folio-web` is a React + Vite app. Web only.
|
||||
export const properties = { noUncaughtExceptions };
|
||||
export const actionsRoot = defaultActions;
|
||||
```
|
||||
|
||||
Both carry a spec at `sanderling/spec.ts`. The examples use [`just`](https://github.com/casey/just) as a command runner, so install it first.
|
||||
This taps, types, scrolls, and swipes at random, and fails the moment your app throws an uncaught exception. From here you add extractors to read your screens, properties that state what your app guarantees, and actions that drive its real flows. The [case study](../case-study/) walks a complete spec, and the [spec language reference](../spec-language/) lists every primitive.
|
||||
|
||||
### Web
|
||||
## Run it
|
||||
|
||||
The quickest path. From `examples/folio-web`:
|
||||
Point sanderling at your app:
|
||||
|
||||
```sh
|
||||
just test
|
||||
sanderling test --spec spec.ts --bundle-id com.example.app --platform android
|
||||
```
|
||||
|
||||
This starts the Vite dev server, then runs `sanderling test`. sanderling launches Chrome and starts exploring: logging in, creating accounts, adding transactions, and tapping things at random. Let it run, or stop it early with Ctrl+C.
|
||||
Use `--platform ios` or `--platform web` for the other targets. By default a run lasts five minutes and starts from a fresh install; `--clear-data=false` resumes prior state, and `--duration 30m` runs longer. The [CLI reference](../cli/) lists every flag.
|
||||
|
||||
For the Kotlin Multiplatform web build instead, run `just web` from `examples/folio`.
|
||||
|
||||
### Android
|
||||
|
||||
From `examples/folio`, with an emulator booted or a device connected:
|
||||
|
||||
```sh
|
||||
just install # build and install the folio APK
|
||||
just test # run the spec
|
||||
```
|
||||
|
||||
If no device is connected and you have several AVDs, pick one:
|
||||
|
||||
```sh
|
||||
AVD=Pixel_7 just test
|
||||
```
|
||||
|
||||
Settings you use every time can live in a `.env` file next to the justfile (`AVD=Pixel_7`, `DURATION=5m`, and so on).
|
||||
|
||||
### iOS
|
||||
|
||||
From `examples/folio` (requires Xcode 16+ and `xcodegen`):
|
||||
|
||||
```sh
|
||||
just test-ios # default simulator: iPhone 17 Pro
|
||||
IOS_DEVICE="iPhone 15" just test-ios # pick a different simulator
|
||||
```
|
||||
|
||||
`just test-ios` boots the simulator if needed, builds and installs the app, then runs `sanderling test --platform ios`.
|
||||
|
||||
#### Physical device
|
||||
|
||||
A connected iPhone is driven over a usbmux tunnel by a runner the driver builds and signs at run time. The tunnel talks to macOS's own `usbmuxd`, so nothing extra is installed beyond Xcode. It needs App Store Connect signing credentials in the environment (a gitignored `.env` is loaded by `just`):
|
||||
|
||||
```sh
|
||||
SANDERLING_IOS_TEAM=<10-char team id>
|
||||
ASC_API_KEY_ID=<key id>
|
||||
ASC_API_ISSUER_ID=<issuer id>
|
||||
ASC_API_KEY_PATH=<absolute path to AuthKey_*.p8>
|
||||
|
||||
IOS_DEVICE="iPhone" just test-ios-device # name, UDID, or CoreDevice id
|
||||
```
|
||||
|
||||
Run `sanderling doctor --platform ios-device` to check `devicectl`, the `usbmuxd` socket, a connected and paired device, and the signing credentials before a run.
|
||||
|
||||
## What you get
|
||||
|
||||
When the run ends, the trace lands in `sanderling/runs/<timestamp>/`:
|
||||
|
||||
```
|
||||
runs/2026-04-18T12-34-56/
|
||||
├── trace.jsonl one JSON line per step
|
||||
├── screenshots/ one screenshot per step
|
||||
└── meta.json seed, duration, run metadata
|
||||
```
|
||||
|
||||
The trace is written as the run goes, so a run you interrupt is still complete up to the point you stopped it.
|
||||
|
||||
## Look at the run
|
||||
## See what it found
|
||||
|
||||
```sh
|
||||
sanderling replay
|
||||
```
|
||||
|
||||
This opens a web UI for the trace. Step through the run with `j` and `k`. Each step shows the screenshot, the action taken, the state of every property, and the full UI hierarchy. If a property broke, press `.` to jump to the violation and see exactly what the screen showed when it happened.
|
||||
|
||||
The folio spec gives extra weight to rapid double taps, because a form that submits twice on a double tap is a classic bug. folio's transaction form has exactly that flaw. When the explorer hits it, the balance moves by twice the typed amount, the `submitMovesBalanceByTypedAmount` property fires, and the timeline shows the violation.
|
||||
|
||||
See [replay](../replay/) for the full panel and shortcut reference.
|
||||
|
||||
## Next
|
||||
|
||||
You have run sanderling against an app with a finished spec. The next page builds that spec from scratch, one concept at a time: [writing specs](../writing-specs/).
|
||||
This opens the trace in a local web UI. Step through with `j` and `k`; press `.` to jump to a property violation and see the screenshot, the action, and the failed formula at that step. The [replay page](../replay/) covers the panels and shortcuts.
|
||||
Reference in new issue
Block a user