From 105b4c03b818335ea9f2eb7956a0ff9d213eeeef Mon Sep 17 00:00:00 2001 From: PJ Date: Sat, 6 Jun 2026 23:18:00 +0530 Subject: [PATCH] docs(manual): rewrite getting started as guided first run --- docs/manual/getting-started.md | 104 ++++++++++++++++++++------------- 1 file changed, 62 insertions(+), 42 deletions(-) diff --git a/docs/manual/getting-started.md b/docs/manual/getting-started.md index b0fe8e4..2e28d70 100644 --- a/docs/manual/getting-started.md +++ b/docs/manual/getting-started.md @@ -4,55 +4,77 @@ title: Getting started # Getting started -Install the CLI, run a spec. +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. -## Prerequisites - -**Android / iOS:** - -- An Android emulator with API level 30 or newer (or a connected device). -- `adb` on your PATH. - -**Web:** - -- Chrome installed. sanderling drives it via CDP; no other setup required. - -Run `sanderling doctor` to check the host environment. +If you have not read the [introduction](./introduction/), start there. It explains what sanderling does and how it works. ## Install -### CLI +Install the CLI: ```sh curl -fsSL https://raw.githubusercontent.com/priyanshujain/sanderling/master/install.sh | bash ``` -### Spec package ([npm](https://www.npmjs.com/package/@sanderling/spec)) +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: ```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: + +- **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. + +Web is the easiest place to start. If you have Chrome, you can run a test right now. + ## Your first run -The repo ships two sample apps. `examples/folio` is a Kotlin Multiplatform personal-ledger app that covers Android, iOS, and web (wasmJs) from one shared codebase. `examples/folio-web` is a smaller React + Vite app that covers only the web path. Both carry a TypeScript spec under `sanderling/spec.ts`. Install `just`, then pick a target below. +Clone the repo and pick an example app. Both are small personal-ledger apps: log in, create accounts, add transactions. + +- `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. + +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. + +### Web + +The quickest path. From `examples/folio-web`: + +```sh +just test +``` + +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. + +For the Kotlin Multiplatform web build instead, run `just web` from `examples/folio`. ### Android -From `examples/folio`: +From `examples/folio`, with an emulator booted or a device connected: ```sh -just install # build and install the folio APK on a booted emulator or device +just install # build and install the folio APK just test # run the spec ``` -With no device connected and multiple AVDs, pick one: +If no device is connected and you have several AVDs, pick one: ```sh AVD=Pixel_7 just test ``` -Persistent settings can live in a `.env` alongside the justfile (`AVD=Pixel_7`, `DURATION=5m`, and so on). +Settings you use every time can live in a `.env` file next to the justfile (`AVD=Pixel_7`, `DURATION=5m`, and so on). ### iOS @@ -65,33 +87,31 @@ 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`. -### Web - -From either example. For the KMP wasmJs build, use `examples/folio`: - -```sh -just web # serve the wasmJs app on a webpack dev server -``` - -For the React + Vite build, use `examples/folio-web`: - -```sh -just test # starts the Vite dev server, then sanderling drives Chrome via CDP -``` - -No emulator or SDK setup needed for either web path. - -### Trace output +## What you get When the run ends, the trace lands in `sanderling/runs//`: ``` runs/2026-04-18T12-34-56/ -├── trace.jsonl -├── screenshots/ -└── meta.json +├── trace.jsonl one JSON line per step +├── screenshots/ one screenshot per step +└── meta.json seed, duration, run metadata ``` -Browse it with `sanderling replay` (see [replay](./replay/)), or read `trace.jsonl` step by step. +The trace is written as the run goes, so a run you interrupt is still complete up to the point you stopped it. -Next: [writing specs](./writing-specs/). +## Look at the run + +```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/).