Getting started

Install sanderling, write a spec for your app, run it, and open the trace.

Install

The CLI:

curl -fsSL https://raw.githubusercontent.com/priyanshujain/sanderling/master/install.sh | bash

The spec package, in your project:

npm install --save-dev @sanderling/spec

Check your environment

sanderling doctor

doctor reports what the target platform needs and what is missing:

  • 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.

Write a spec

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:

import { defaultActions } from "@sanderling/spec/defaults";
import { noUncaughtExceptions } from "@sanderling/spec/defaults/properties";

export const properties = { noUncaughtExceptions };
export const actionsRoot = defaultActions;

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 walks a complete spec, and the spec language reference lists every primitive.

Run it

Point sanderling at your app:

sanderling test --spec spec.ts --bundle-id com.example.app --platform android

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 lists every flag.

See what it found

sanderling replay

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 covers the panels and shortcuts.