speedrun

Speedrun tests your app the way a user uses it: it taps, types, scrolls and checks what is on screen, from outside the app, with nothing added to it. A test is a short YAML file:

appId: com.example.app
---
- launchApp
- tapOn: "Sign in"
- inputText: "user@example.com"
- tapOn: "Continue"
- assertVisible: "Welcome"

Why Speedrun?

• Fast. A tap that opens a screen takes about 0.3 s, and a run starts in 1–3 s. The same user journey takes 20 s with Speedrun on Android, 59 s with Appium, 66 s with maestro-runner and 127 s with Maestro (benchmark).
• Waits for the app, not the clock. Each step starts the moment the app has finished changing: no sleeps, no comparing screenshots. Screens that never stop moving (spinners, tickers, carousels) don't hold it up.
• Fewer flaky failures. It doesn't tap a popup that is still sliding in or a button behind a loading overlay, and it scrolls an element out from under a sticky footer or the keyboard before tapping it, so the same flow passes on a small phone.
• Black-box. Any build of your app, release builds included, through the platform's accessibility layer. Tested on native and React Native apps.
• One file. The Android and iOS agents are built in: no JVM, no drivers to install, no SDK in your app.
• Ready for CI. JUnit and HTML reports, sharding across devices, tags, and a debug folder with screenshots and logs for every failure. It answers the "isn't responding" dialogs a freshly booted emulator puts up, and reconnects to its agent if the agent crashes.

Quick start

1. Install with Homebrew (macOS on Apple silicon, Linux x86_64):

   brew install hubastard/tap/speedrun
   

   Or with the install script:

   curl -fsSL https://raw.githubusercontent.com/hubastard/speedrun/main/install.sh | bash
   

   • The script installs into ~/.speedrun and adds it to your PATH. For another folder or a specific release, put SPEEDRUN_DIR=/usr/local/bin or SPEEDRUN_VERSION=v0.2.0 in front of bash.
   • Speedrun is one file, with its Android and iOS agents built in. You can also download it from the releases and put it anywhere on your PATH.
   • Speedrun tells you when a new release is out. Update with brew upgrade speedrun, or speedrun update if you used the script.
   • To build it yourself, see Building from source.

2. Write a flow (how), or use the ones you have:

   # login.yaml
   appId: com.example.app
   ---
   - launchApp:
       clearState: true
   - tapOn: "Email"
   - inputText: "user@example.com"
   - tapOn: "Password"
   - inputText: ${PASSWORD}
   - tapOn: "Sign in"
   - assertVisible: "Welcome"
   

3. Run it on a running Android emulator or device, or a booted iOS simulator:

   speedrun test login.yaml -e PASSWORD=secret                  # Android
   speedrun test -p ios login.yaml -e PASSWORD=secret           # iOS simulator
   speedrun test flows/ --format junit --output report.xml      # a whole suite, for CI
   

In a terminal you see each step live, with its time. When a step fails, Speedrun shows what was on screen, and where it saved the screenshot and logs.

Already using Maestro?

Speedrun reads the Maestro flow format: your flow files, config.yaml, tags, environment variables and scripts run as they are, and speedrun test takes the same options as maestro test and writes the same reports. Switching is a one-word change:

maestro test flows/     # before
speedrun test flows/    # after

Everything runs as written except Maestro's AI commands (assertWithAI and the like). The details, and the few differences you may notice: Maestro compatibility.

Explore an app with an AI agent

A session keeps Speedrun connected to the device between commands, so an AI coding agent can drive the app a step at a time, read the screen in a few lines, and save the steps that worked as a flow for CI:

speedrun session start --app com.example.app
speedrun look                          # @5 Field #email, @7 Button "Sign in" ...
speedrun do 'tapOn: @5' 'inputText: "user@example.com"' 'tapOn: @7'
speedrun session save flows/sign-in.yaml

Each answer says how each command went and what changed on screen, in a few lines: an agent pays a few hundred tokens per step, not a whole accessibility tree. See Sessions, and the comparison with other agent tools.

As an MCP server

speedrun mcp serves the same as Model Context Protocol tools (session_start, look, run, save_flow...), for agents that take tools from MCP servers. With Claude Code, after installing Speedrun:

claude mcp add speedrun -- ~/.speedrun/speedrun mcp              # this project
claude mcp add --scope user speedrun -- ~/.speedrun/speedrun mcp # every project

Other MCP clients (Claude Desktop, Cursor, ...) take a server in their JSON configuration:

{
  "mcpServers": {
    "speedrun": { "command": "/Users/you/.speedrun/speedrun", "args": ["mcp"] }
  }
}

Use the binary's full path: an MCP client may not start servers with your shell's PATH. Then start an emulator or simulator and ask the agent to test something like:

Start a speedrun session for com.example.app, sign in as user@example.com, and save the flow to flows/sign-in.yaml

Built against an app made to be hard to test

Speedrun is developed against Speedrun Bench, a React Native app built to trip up UI test tools: screens that never stop moving (looping Lottie and Reanimated animations, tickers, marquees, shimmering skeletons, carousels that page on their own), a button that turns on late, a banner that shifts the layout, a loading overlay over a keypad, popups that arrive late or one after another, the keyboard over the checkout button, lists that load more as you scroll, native alerts and permission prompts. Its 19 flows cover every command and selector, and are Speedrun's regression suite on Android and iOS; a journey through the app also runs on GitHub Actions' emulator and simulator after every push.

Waiting for a still screen would never end on such an app. Speedrun waits until what it acts on has settled and leaves endless animations out of that check; it also waits for a disabled button to turn on, a loading overlay to go and a popup to finish sliding in before it taps.

Benchmark

Speedrun Bench's 19 flows, run by Speedrun and Maestro from the same files:

Maestro's time for a flow it fails stops at the failure. Estimating the whole suite as if it had finished those flows, Speedrun is about 8.0x faster on Android and 4.8x on iOS. On native screens, the system Settings app (bench/settings), Speedrun is 10.7x faster on Android and 2.9x on iOS.

Measured on an Apple M1 Pro (16 GB), with an Android 17 emulator and an iPhone 17 Pro simulator (iOS 26.2): Speedrun's current code on 2026-10-29, the other tools on 2026-10-27 (they have not changed since). Speedrun's iOS numbers are with SPEEDRUN_REDUCE_MOTION=1 (the simulator's Reduce Motion on during the run; without it this suite took 585 s instead of 573 s) and, as Speedrun always runs iOS apps, their animations 10x faster (UIKit's animation speed setting). Per-flow results, why Maestro failed, and how to rerun it all: bench/app.

Against other black-box tools

One user journey on Speedrun Bench (sign in with a code, search the shop and fill a cart, set a PIN under a loading overlay, scroll a long list), written for each tool the way its tests are usually written: bench/journey. Each tool ran it three times after a warm-up; the time is the median of its passing runs, its start-up included.