Speedrun

Speedrun

Runs end-to-end UI tests for Android, iOS and web apps from plain YAML files, driving the app from outside. For developers and QA teams who want quick test runs on a laptop and in CI.

Made by hubastard on GitHub. These notes are Mindket's, written from its README; the project's own files and license are in its repository.

About

What it is: Speedrun is a test runner for mobile apps and websites. You write each test as a short YAML file, and it taps, types, scrolls and checks the screen from outside your app. Nothing is added to the app itself, so it works on any build.

Who it suits: Mobile app developers and QA engineers who want UI tests that start quickly and fail less often. Teams that already write Maestro flows can reuse them.

Industry | Who uses it | How they use it | Example
Mobile app development | App developers | Write flows that tap through sign-in and other screens on Android and iOS | A developer checks after each change that the Sign in flow still ends on the Welcome screen
Quality assurance | QA engineers | Keep a suite of YAML flows and run it with JUnit or HTML reports | A tester runs a whole folder of flows and reads the HTML report
Web product teams | Front-end developers | Run the same kind of flow in Chrome or Firefox against a page | A developer runs a login flow in headless mode before a release
Test automation | Teams on Maestro | Switch the command name and keep existing flow files | A team replaces maestro test with speedrun test on its flows folder

Teams that only write unit tests, or that test desktop apps, can skip it.

Where to use it:

• Android emulators and devices
• iOS simulators
• Chrome and Firefox, for web flows
• CI runners, with reports and sharding across devices
• A terminal, where each step shows live with its time
• An AI coding agent, through a session that stays connected to the device between commands

Use case | Who | What they get back
Check a sign-in flow | App developers | A result for each step, plus what was on screen and saved logs when one fails
Run a suite in CI | QA and release teams | JUnit and HTML reports, with flows sharded across devices
Move off Maestro | Teams with existing flows | The same flow files, config.yaml, tags and reports after a one-word change

How to set it up: You need a way to install it and a device to test on.

• Homebrew, on macOS with Apple silicon or on Linux x86_64
• An Android emulator or phone that is switched on, or an iOS simulator that has finished booting
• For web flows, Chrome or Firefox, which Speedrun drives itself

1. Install Speedrun with Homebrew.
2. Write a flow, which is a short YAML file that names your app and lists the steps.
3. Run it with the test command on your emulator, device or simulator.

brew install hubastard/tap/speedrun

How to use it: Write a flow file, then run it. Each step appears in the terminal as it runs, and a failed step shows what was on screen and where the screenshot and logs went.

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

speedrun test login.yaml -e PASSWORD=secret
speedrun test -p ios login.yaml -e PASSWORD=secret
speedrun test flows/ --format junit --output report.xml

Tool | What it does
launchApp | Opens the app, and starts clean when clearState is set to true
tapOn | Taps the element that shows the given text
inputText | Types the given text into the field
assertVisible | Checks that the given text is on screen
speedrun test | Runs one flow file or a whole folder, on Android by default or on iOS with the -p ios option
speedrun fast-boot | Boots an emulator or simulator with the apps and services your tests never need switched off

A web flow points at its page through a url key, in the place where an app flow has appId. Run it with the headless option for Chrome, or add the Firefox device option.

Example: You write the five-step flow above. It opens the app, taps Sign in, types an email address, taps Continue and checks that Welcome is on screen. You run it with speedrun test and your file name. If the check fails, the terminal shows what was on screen and where the screenshot is.

For newcomers and experts: Speedrun uses your app the way a person would. It taps buttons, types text and reads the screen, then tells you which step broke. A first small thing to try is the five-step flow above against an app on an emulator.

Underneath, it works through the platform's accessibility layer, so release builds work and no SDK goes into your app. Each step starts when the screen stops changing instead of after a fixed sleep, and screens that never settle, such as spinners, do not hold it up. Its Android and iOS agents ship inside the one file, and it controls Chrome and Firefox directly, so there is no JVM or WebDriver to install. The trade-off is that Maestro's AI commands are not supported.

Write the test as a YAML flow file
Speedrun drives the app from outside
Each step waits for the screen to settle
A failure saves a screenshot and logs
Reports come out as JUnit or HTML

Good to know:

• Platforms: Android, iOS and the web, tested on native and React Native apps.
• Not supported: Maestro's AI commands such as assertWithAI, and startRecording on the web.
• Speed: opening a screen with a tap takes about 0.3 seconds, and a run starts in 1 to 3 seconds.
• On a CI runner, fast-boot switches off background apps and services that compete with your tests for CPU.
• License: Apache 2.0.

Title: Time for the same user journey on Android
Speedrun: 20 s
Appium: 59 s
maestro-runner: 66 s
Maestro: 127 s

On GitHub, 7 November 2026

• Stars: 100
• Forks: 3
• Open issues and pull requests: 1
• Language: Odin
• License: Apache-2.0
• Topics: ai-agents, android, android-emulator, black-box-testing, cli, e2e-testing, end-to-end-testing, fast, ios, ios-simulator, maestro, mcp

Links

• Code: https://github.com/hubastard/speedrun
• Releases: https://github.com/hubastard/speedrun/releases
• Issues: https://github.com/hubastard/speedrun/issues
• Star history: https://www.star-history.com/#hubastard/speedrun&Date

Get the code

git clone https://github.com/hubastard/speedrun.git

Then follow the setup in its README. Nothing in this kit runs by itself.