Skip to content
Back to search

speedrun

Fastest cross-platform E2E Automation for Mobile & Web

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hubastard--speedrun/badge.svg)](/listings/hubastard--speedrun)

HTML

<a href="/listings/hubastard--speedrun"><img src="/api/listings/hubastard--speedrun/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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

Other ways to install, updating, and building from source: [Install](docs/install.md).

2. **Write a flow** ([how](docs/flows.md)), 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

A website's flow names its page with `url:` instead of `appId:`, and runs in Chrome, or in Firefox with `--device firefox`: `speedrun test --headless web-login.yaml` ([Web](docs/web.md)).

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 282 lines · 1 finding marked
  1. <h1 align="center">Speedrun</h1>
  2. <p align="center">
  3. <b>The fastest end-to-end test runner for mobile apps and the web.</b><br>
  4. Black-box UI tests for Android, iOS and the web, written in plain YAML.
  5. </p>
  6. <p align="center">
  7. <a href="https://github.com/hubastard/speedrun/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/hubastard/speedrun?style=flat-square&labelColor=000000&color=2ea44f"></a>
  8. <img alt="Android, iOS and web" src="https://img.shields.io/badge/platforms-Android%20%7C%20iOS%20%7C%20Web-000000?style=flat-square">
  9. <a href="LICENSE"><img alt="Apache 2.0 license" src="https://img.shields.io/badge/license-Apache%202.0-000000?style=flat-square"></a>
  10. </p>
  11. <p align="center">
  12. <img alt="The same test run by Maestro in 35.0 s and by Speedrun in 4.5 s" src="docs/assets/maestro-vs-speedrun-android-settings.gif" width="600"><br>
  13. <sub>The same 15-step test of Android's Settings app (<a href="https://github.com/hubastard/speedrun-bench/blob/main/settings/bench_scenario_android.yaml">flow</a>) on one emulator, in real time.</sub>
  14. </p>
  15. ---
  16. Speedrun tests your app the way a user uses it: it taps, types, scrolls and checks what is on
  17. screen, from outside the app, with nothing added to it. A test is a short YAML file:
  18. ```yaml
  19. appId: com.example.app
  20. ---
  21. - launchApp
  22. - tapOn: "Sign in"
  23. - inputText: "user@example.com"
  24. - tapOn: "Continue"
  25. - assertVisible: "Welcome"
  26. ```
  27. ## Why Speedrun?
  28. - **Fast.** A tap that opens a screen takes about 0.3 s, and a run starts in 1–3 s. The same
  29. user journey takes 20 s with Speedrun on Android, 59 s with Appium, 66 s with
  30. maestro-runner and 127 s with Maestro. In the browser, Cypress's own demo app's tests take
  31. 4.2 s with Speedrun, 5.9 s with Playwright and 11.3 s with Cypress, and Speedrun leads in
  32. Firefox too ([benchmark](#benchmark)).
  33. - **Waits for the app, not the clock.** Each step starts the moment the app has finished
  34. changing: no sleeps, no comparing screenshots. Screens that never stop moving (spinners,
  35. tickers, carousels) don't hold it up.
  36. - **Fewer flaky failures.** It doesn't tap a popup that is still sliding in or a button behind
  37. a loading overlay, and it scrolls an element out from under a sticky footer or the keyboard
  38. before tapping it, so the same flow passes on a small phone.
  39. - **Black-box.** Any build of your app, release builds included, through the platform's
  40. accessibility layer. Tested on native and React Native apps.
  41. - **One file.** The Android and iOS agents are built in, and it drives Chrome and Firefox
  42. itself: no JVM, no WebDriver or drivers to install, no SDK in your app.
  43. - **Ready for CI.** JUnit and HTML reports, sharding across devices, tags, and a debug folder
  44. with screenshots and logs for every failure. It answers the "isn't responding" dialogs a
  45. freshly booted emulator puts up, reconnects to its agent if the agent crashes, and boots iOS
  46. simulators without the background services that slow a runner's first minutes
  47. ([Running on CI](#running-on-ci)).
  48. ## Quick start
  49. 1. **Install** with Homebrew (macOS on Apple silicon, Linux x86_64):
  50. ```sh
  51. brew install hubastard/tap/speedrun
  52. ```
  53. Or with the install script:
  54. ```sh
  55. curl -fsSL https://raw.githubusercontent.com/hubastard/speedrun/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 68 on GitHub
  56. ```
  57. Other ways to install, updating, and building from source: [Install](docs/install.md).
  58. 2. **Write a flow** ([how](docs/flows.md)), or use the ones you have:
  59. ```yaml
  60. # login.yaml
  61. appId: com.example.app
  62. ---
  63. - launchApp:
  64. clearState: true
  65. - tapOn: "Email"
  66. - inputText: "user@example.com"
  67. - tapOn: "Password"
  68. - inputText: ${PASSWORD}
  69. - tapOn: "Sign in"
  70. - assertVisible: "Welcome"
  71. ```
  72. 3. **Run it** on a running Android emulator or device, or a booted iOS simulator:
  73. ```sh
  74. speedrun test login.yaml -e PASSWORD=secret # Android
  75. speedrun test -p ios login.yaml -e PASSWORD=secret # iOS simulator
  76. speedrun test flows/ --format junit --output report.xml # a whole suite, for CI
  77. ```
  78. A website's flow names its page with `url:` instead of `appId:`, and runs in Chrome, or in
  79. Firefox with `--device firefox`: `speedrun test --headless web-login.yaml` ([Web](docs/web.md)).
  80. In a terminal you see each step live, with its time. When a step fails, Speedrun shows what
  81. was on screen, and where it saved the screenshot and logs.
  82. ## Already using Maestro?
  83. Speedrun reads the [Maestro](https://maestro.dev) flow format: your flow files, `config.yaml`,
  84. tags, environment variables and scripts run as they are, and `speedrun test` takes the same
  85. options as `maestro test` and writes the same reports. Switching is a one-word change:
  86. ```sh
  87. maestro test flows/ # before
  88. speedrun test flows/ # after
  89. ```
  90. Everything runs as written, web flows included, except Maestro's AI commands (`assertWithAI`
  91. and the like) and `startRecording` on the web. The details, and the few differences you may
  92. notice:
  93. [Maestro compatibility](docs/maestro-compatibility.md).
  94. ## Running on CI
  95. ```sh
  96. speedrun fast-boot --device "$AVD" --headless # Android: boots the emulator without the apps tests do not use
  97. speedrun fast-boot --device "$UDID" # iOS: boots the simulator without the services tests do not use
  98. speedrun test flows/ --format junit --output report.xml --debug-output debug --flatten-debug-output
  99. ```
  100. On a CI runner's first boot, an Android emulator's preinstalled apps (the Google app, Gmail,
  101. YouTube, Photos and more) and an iOS simulator's background services (Siri, Spotlight's
  102. indexing, iCloud syncing and more) take the CPU your tests need for minutes. `speedrun fast-boot`
  103. turns them off and boots the device: use it in place of `emulator -avd` or `xcrun simctl
  104. boot`. A new emulator then spent half as much CPU in the minute after its boot, and about a
  105. sixth as much in the next. Speedrun's own iOS CI job went from about 10 minutes to about 6,
  106. with one more flow than before.
  107. Reports, sharding, what to keep from a failed run, and booting the simulator while your app
  108. builds: [Running on CI](docs/ci.md).
  109. ## Explore an app with an AI agent
  110. A session keeps Speedrun connected to the device between commands, so an AI coding agent can
  111. drive the app a step at a time, read the screen in a few lines, and save the steps that worked
  112. as a flow for CI:
  113. ```sh
  114. speedrun session start --app com.example.app
  115. speedrun look # @5 Field #email, @7 Button "Sign in" ...
  116. speedrun do 'tapOn: @5' 'inputText: "user@example.com"' 'tapOn: @7'
  117. speedrun session save flows/sign-in.yaml
  118. ```
  119. Each answer says how each command went and what changed on screen: an agent pays a few
  120. hundred tokens per step, not a whole accessibility tree. `speedrun mcp` serves the same as
  121. [MCP](https://modelcontextprotocol.io) tools; with [Claude Code](https://claude.com/claude-code):
  122. ```sh
  123. claude mcp add speedrun -- ~/.speedrun/speedrun mcp
  124. ```
  125. Other MCP clients, and every command: [Sessions](docs/sessions.md).
  126. ## Benchmark
  127. Speedrun is developed against [Speedrun Bench](https://github.com/hubastard/speedrun-bench/tree/main/app), a React Native app built to trip up
  128. UI test tools: screens that never stop moving, a button that turns on late, a loading overlay
  129. over a keypad, popups that arrive late, the keyboard over the checkout button, native alerts
  130. and permission prompts. Its <!-- results:app-flows -->21<!-- /results:app-flows --> flows are Speedrun's regression suite on Android and iOS, and a
  131. journey through the app runs on GitHub Actions' emulator and simulator after every push.
  132. <p align="center">
  133. <img alt="Speedrun testing six animated screens of Speedrun Bench on the iOS simulator in 16 seconds" src="docs/assets/speedrun-bench-animations-ios.gif" width="320"><br>
  134. <sub>Six of those screens on the iOS simulator, in real time, with animations at their normal speed: Speedrun taps each screen's button three times while it moves, then checks the count. No sleeps.</sub>
  135. </p>
  136. One user journey on it (sign in with a code, fill a cart, set a PIN under a loading overlay,
  137. scroll a long list), written for each tool the way its tests are usually written. The median
  138. of three runs after a warm-up, start-up included ([bench/journey](https://github.com/hubastard/speedrun-bench/tree/main/journey)):
  139. <!-- results:journey -->
  140. | Tool | Android emulator | iOS simulator |
  141. |---|---:|---:|
  142. | **Speedrun** | **20.9 s**, 3/3 passed | **25.5 s**, 3/3 passed |
  143. | Appium 3.9 | 59.4 s, 3/3 passed | 94.1 s, 3/3 passed |
  144. | [maestro-runner](https://github.com/devicelab-dev/maestro-runner) 1.1.29 | 65.9 s, 2/3 passed | 49.6 s, 3/3 passed |
  145. | [Argent](https://github.com/software-mansion/argent) 0.31 (`argent e2e`) | 81.5 s, 3/3 passed | 72.2 s, 3/3 passed |
  146. | XCUITest | | 81.2 s, 3/3 passed |
  147. | Maestro 2.11 | 126.5 s, 2/3 passed | 113.1 s, 2/3 passed |
  148. <!-- /results:journey -->
  149. - **Against Maestro, from the same flow files:** <!-- results:app-sentence -->Speedrun passes 21 of 21 of the app's flows on Android and 19 of 19 on iOS, Maestro 16 of 19 on Android and 8 of 19 on iOS. On the flows both pass, Speedrun is 8.1x faster on Android and 3.0x on iOS<!-- /results:app-sentence --> ([bench/app](https://github.com/hubastard/speedrun-bench/blob/main/app/README.md)); on the system
  150. Settings app ([bench/settings](https://github.com/hubastard/speedrun-bench/tree/main/settings)), 10.7x and 2.9x.
  151. - **For AI agents**, trying out a feature through each tool's MCP server: Speedrun took 4.5 s
  152. on Android and 7.8 s on iOS, [agent-device](https://github.com/callstackincubator/agent-device)
  153. 8.2 s and 12.5 s, [Argent](https://github.com/software-mansion/argent) 13.0 s and 11.8 s,
  154. and Speedrun's answers cost the agent the fewest tokens ([bench/agents](https://github.com/hubastard/speedrun-bench/tree/main/agents)).
  155. **On the web**, the same tests written for each tool, the median of three runs after a warm-up,
  156. start-up included ([bench/web](https://github.com/hubastard/speedrun-bench/tree/main/web)): Playwright's TodoMVC demo, and seven tests from
  157. the suite of Cypress's [Real World App](https://github.com/cypress-io/cypress-realworld-app),
  158. a payments app in React and Material UI:
  159. <!-- results:web -->
  160. | Tool | TodoMVC | Real World App, 7 tests |
  161. |---|---:|---:|
  162. | **Speedrun** | **0.66 s**, passed | **4.2 s**, 7/7 passed |
  163. | Playwright 1.64 | 1.30 s, passed | 5.9 s, 7/7 passed |
  164. | Cypress 16.1 | 3.66 s, passed | 11.3 s, 7/7 passed |
  165. | Maestro 2.11 | failed | 3/6 passed in 30 min, then stopped |
  166. <!-- /results:web -->
  167. Every tool ran a headless Chromium browser (Cypress its default, Electron), at the same window
  168. size, one test at a time, with its default settings. Playwright's `fill` puts a field's text in
  169. at once, while Speedrun types it a key at a time.
  170. **In Firefox too**, on a GitHub Actions Linux runner (slower than the Mac: compare within a
  171. row), every tool in its own Firefox build: <!-- results:web-firefox -->TodoMVC took 3.0 s with Speedrun, 3.9 s with Playwright and 9.0 s with Cypress, and the Real World App 11.5 s, 15.2 s and 21.8 s<!-- /results:web-firefox -->
  172. ([the Linux results](https://github.com/hubastard/speedrun-bench/tree/main/web#on-linux-in-chrome-and-firefox), Chrome's included).
  173. Measured on an Apple M1 Pro with an Android 17 emulator and an iPhone 17 Pro simulator (iOS
  174. 26.2), in <!-- results:measured-when -->October and November 2026<!-- /results:measured-when -->, each tool as it ships. On iOS that means
  175. Speedrun runs the app's animations 10x faster, as it does by default, and the other tools at
  176. normal speed; with the agent tools all at normal speed, on iOS Speedrun took 11.3 s,
  177. agent-device 12.5 s and Argent 11.8 s. Speedrun's iOS suite and journey runs also had the
  178. simulator's Reduce Motion on (`--animations off`; the journey took 26.6 s without it).
  179. ## How it works
  180. Speedrun runs a small agent on the device. It reads the screen in milliseconds, without
  181. screenshots, and tells exactly when the app has settled, so each step starts the moment the
  182. app is ready instead of after a fixed wait. In the browser, a script in the page does the same,
  183. from what the page reports: its changes, requests in flight, timers and animations.
  184. ## Requirements
  185. - **macOS** on Apple silicon, for Android, iOS and web, or **Linux** x86_64, for Android and
  186. web (CI runners included). The install script picks the right package.
  187. - **Android:** the platform tools (`adb` on your PATH) and a running emulator, or a device
  188. with USB debugging on.
  189. - **Web:** Chrome or Firefox. Speedrun uses the one installed, or downloads it on the first
  190. run ([Chrome](docs/web.md#chrome), [Firefox](docs/web.md#firefox)); macOS or Linux.
  191. - **iOS:** Xcode and a booted simulator (on CI, boot it with
  192. [`speedrun fast-boot`](docs/ci.md#ios-boot-the-simulator-with-speedrun-fast-boot)). Real iOS devices
  193. are not supported yet. A release's iOS agent is built with one Xcode (its release notes name
  194. it); with a much different Xcode, [build from source](docs/install.md#building-from-source).
  195. - `curl`, for flow scripts that make HTTP requests.
  196. ## Documentation
  197. - [Install](docs/install.md): Homebrew, the install script, updates, building from source.
  198. - [Writing flows](docs/flows.md): a flow's steps, finding elements, every command, for
  199. someone new to the format.
  200. - [Command line](docs/cli.md): options, environment variables, exit status.
  201. - [Running on CI](docs/ci.md): reports, sharding, failure artifacts, `speedrun fast-boot` for
  202. iOS simulators.
  203. - [Web](docs/web.md): testing websites in Chrome and Firefox, with the same flows.
  204. - [Sessions](docs/sessions.md): drive an app a command at a time, from an AI agent or a
  205. terminal, and save the steps as a flow.
  206. - [Maestro compatibility](docs/maestro-compatibility.md): what is supported, and the
  207. differences you may notice.
  208. - [Troubleshooting](docs/troubleshooting.md).
  209. - Benchmarks: [the app and its flows](https://github.com/hubastard/speedrun-bench/blob/main/app/README.md), [the journey against other
  210. tools](https://github.com/hubastard/speedrun-bench/tree/main/journey), [agent tools](https://github.com/hubastard/speedrun-bench/tree/main/agents), [the web](https://github.com/hubastard/speedrun-bench/tree/main/web);
  211. [every benchmark's latest results](https://github.com/hubastard/speedrun-bench/tree/main/results),
  212. and [CI's, push by push](https://github.com/hubastard/speedrun/tree/bench-history).
  213. ## Status
  214. Speedrun is young and changes fast. If a flow that passes with Maestro fails with Speedrun,
  215. please open an issue with the flow and its folder in the debug output (`logs/debug.log` there
  216. traces the run), or the output of `SPEEDRUN_DEBUG=1 speedrun test …`.
  217. ## Sponsors
  218. Speedrun is free and open source. If you or your team rely on it, you can
  219. [sponsor its development](https://github.com/sponsors/hubastard): it pays for the time spent
  220. on fixes, issue triage and new features, and for the hardware every release is tested on.
  221. ## License
  222. Speedrun is licensed under the [Apache License 2.0](LICENSE). It includes
  223. [QuickJS-ng](https://github.com/quickjs-ng/quickjs) (MIT),
  224. [Datafaker](https://github.com/datafaker-net/datafaker)'s English word lists (Apache-2.0) and
  225. [stb_image](https://github.com/nothings/stb) (public domain or MIT): see [NOTICE](NOTICE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.