Start

Install

What Troupe needs, how to add it to a project, how troupe install prepares each platform, and how troupe doctor checks the environment.

Requirements

The platform pages have the details: iOS Simulator, Android Emulator and Mac Catalyst.

Add the package

bun add -d --exact @alivelabs/troupe

This one package is the test framework and the troupe command. It brings the runtime, the client and the report viewer as dependencies. The platform packages are optional dependencies, loaded only on a host that can run them.

Bun runs your config and specs as TypeScript directly; there is no build step. Type checking is separate: the package ships its declarations for your own tsc.

troupe init adds an "e2e": "troupe test" script to package.json, so bun run e2e runs the suite. See the quick start for troupe init.

Prepare a platform

troupe install prepares a platform once per machine, outside any test:

bunx troupe install ios
bunx troupe install android
bunx troupe install catalyst

With no argument it prepares every platform your troupe.config.ts uses, or, without a config, every platform this host can run. It does four things in order:

1. Records the toolchain. Where there is no ~/.troupe/host.json, it writes one that names your Xcode: the one in DEVELOPER_DIR, else /Applications/Xcode.app/Contents/Developer. For Android it records the SDK it finds in ANDROID_HOME, ANDROID_SDK_ROOT or ~/Library/Android/sdk. The runtime reads these recorded paths from then on, not your shell's environment.
2. Runs the environment checks for the platform. A failed check prints its fix and the command exits 3.
3. Builds what the platform needs ahead. For iOS that is the XCUITest runner and a booted simulator template that devices are cloned from. Android and Mac Catalyst have nothing to build.
4. Proves the device path. It starts one device with the device type and OS version of your config's first project for that platform (or the platform's default), waits until it is ready, and releases it warm. It then prints <platform>: a device was ready in <n> s.

The first run can take minutes, because it builds the runner and boots a simulator for the first time.

If your Xcode is not in /Applications/Xcode.app, set DEVELOPER_DIR for the first troupe install, or set platforms.ios-simulator.developerDir in ~/.troupe/host.json afterwards.

Check the environment

troupe doctor runs the same read-only checks without changing anything:

bunx troupe doctor

It checks the platforms your config uses; --all checks every platform, and so does a directory with no config. Each line is a status (pass, warn, fail or skip), the check's id, the platform in brackets and a message. A failed check is followed by a fix: line with one command or one instruction. The command exits 1 when a check fails; --json prints the result as JSON.

troupe test runs the checks of the platforms in the run before it starts a device. When one fails, no test runs and the command exits 3 with every fix printed.

Where Troupe keeps its files

Troupe keeps its state under ~/.troupe, or the directory TROUPE_HOME names:

Your project gains test-results/ (traces and attachments), troupe-report/ (the HTML report) and, with the blob reporter, blob-report/. troupe init adds all three to .gitignore.

Next

• Quick start
• How Troupe works
• The CLI
• The runtime daemon