Test Buddy (tb)

Fast, event-driven UI tests for Android, iOS and the web. tb runs Maestro-compatible YAML flows (your existing Maestro flows run unchanged), drives several devices in one test, and is built for AI agents to use straight from a shell.

Install

Download. One binary with the Android and iOS agents built in, no Go needed. Get the archive for your system from the latest release (macOS, Windows and Linux; checksums.txt has their SHA-256 sums).

macOS (Apple silicon; on an Intel Mac use tb_darwin_amd64):

curl -fsSL https://github.com/Elforama/testbuddy/releases/latest/download/tb_darwin_arm64.tar.gz | tar -xz
sudo mkdir -p /usr/local/bin && sudo mv tb_darwin_arm64/tb /usr/local/bin/
tb version

The binary is not signed by Apple. Fetched with curl as above it runs as is. If you download the archive in a browser instead, macOS refuses to open tb ("Apple could not verify..."); clear the download's quarantine flag once:

xattr -d com.apple.quarantine /usr/local/bin/tb

Windows 10 or later, in PowerShell (on an Arm PC use tb_windows_arm64):

Invoke-WebRequest https://github.com/Elforama/testbuddy/releases/latest/download/tb_windows_amd64.zip -OutFile tb.zip
Expand-Archive tb.zip -DestinationPath "$env:LOCALAPPDATA\Programs" -Force
$dir = "$env:LOCALAPPDATA\Programs\tb_windows_amd64"
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$dir", "User")

Open a new terminal, then tb version. If you downloaded the zip in a browser and Windows blocks tb.exe, run Unblock-File "$dir\tb.exe". On Windows, tb runs Android and web flows; iOS needs macOS and Xcode.

Linux: the same as macOS with tb_linux_amd64 or tb_linux_arm64.

Go. With Go 1.27+:

go install github.com/elforama/testbuddy/cmd/tb@latest
tb version

@latest is the newest release; @main builds the newest commit. tb lands in $(go env GOPATH)/bin, so put that on your PATH. Keep the module path lowercase (github.com/Elforama/... fails). To build from a clone instead, see Build from source.

Claude Code plugin. The tb CLI plus a tb skill for Claude. The bundled tb runs on Apple silicon Macs only; elsewhere, install the CLI from a download or with go install above.

claude plugin marketplace add Elforama/testbuddy
claude plugin install test-buddy@test-buddy

Or from inside Claude Code: /plugin marketplace add Elforama/testbuddy, then /plugin install test-buddy@test-buddy.

Devices. Start an Android emulator (or plug in a phone with USB debugging), boot an iOS simulator, or have Google Chrome installed for web flows.

Quick start

tb devices                          # what tb can drive: emulators, simulators, Chrome
tb test login.yaml                  # run one flow
tb test flows/ -p android           # every flow in a folder, on Android only
tb test flows/ -p web --headless    # web (url:) flows in headless Chrome
tb check flows/                     # check flow syntax, no device needed
tb check --lint flows/              # also list fragile steps (coordinates, indexes, ...)

A flow is Maestro YAML (existing Maestro flows run unchanged):

appId: com.android.settings
---
- launchApp
- tapOn: "Network & internet"
- assertVisible: "Internet"

Drive a device by hand, or let an agent do it:

tb look                             # the screen, one line per element, with @refs and layout
tb do 'tapOn: @5' 'inputText: hi'   # run commands; see what changed

Why

• Maestro-compatible. Maestro's YAML format: every command, selector, condition, runFlow, repeat, retry, JavaScript (${}, runScript, output, http), env rules, config.yaml, tags, JUnit/HTML reports and the same command-line options. Maestro flows run unchanged, including maestro.copiedText / maestro.platform in scripts, MAESTRO_* variables and .maestro flow folders (tb's own names, tb.copiedText, TB_FILENAME and .tb, work too). Web flows (url:) run in Chrome, with CSS selectors and same- and cross-origin iframes.
• Fast. The same journey takes tb 10.7 s on Android and 15.4 s on iOS, against Maestro's 4–6 minutes (Speed).
• No polling. The on-device agents (and an in-page script on the web) push "the UI changed" and "the UI settled" events. tb waits on those; a screen is only read again after the device says it changed. Screens that never stop moving (spinners, tickers, stopwatches) still settle: an element that keeps changing is marked restless and stops holding the screen up. (Details and the few timers that remain: docs/architecture.md.)
• Many devices. Spread a suite over devices with a work queue, or write one flow that drives an iPhone and an Android phone together (docs/multi-device.md).
• Agent first. A CLI, not an MCP server you must set up (MCP is there if you want it). Screens are a few hundred tokens, every command answers with what changed, and the commands that worked save as a flow.

Speed

Platform	tb	WebdriverIO	Maestro
Android (emulator, Android 16)	10.7 s (10.3–11.1)	18.7 s (17.0–25.4)	371.9 s (one run)
iOS (iPhone 17 simulator)	15.4 s (15.4–15.5)	44.6 s (43.6–48.1)	281.4 s (277.5–286.1)
Web (headless Chrome)	7.6 s (7.6–7.8)	4.8 s (4.7–5.2)	274.6 s (264.6–308.1)

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗