Trailblaze: Map Your App for AI

Trailblaze (https://github.com/block/trailblaze) is Block's open-source CLI for driving real apps with AI on Android, iOS, and web. No more clicking through your own app to check a change. AI is slow, expensive, and non-deterministic — fine for exploration, painful in CI. So save what the agent did as a trail: a YAML record, replayable forever with no LLM calls. Map your app with waypoints and agents take the fast path next time. For teams who want AI-driven flows without rewriting what works. Explore once, replay forever.

Transcript

1. Trailblaze Map Your App for AI 🥾 🗺 Droidcon USA 2026 Sam Edwards · Block
2. 10 Years Ago Droidcon NYC 2016 — “A Screenshot is Worth 1,000 Words”
3. A Screenshot is Worth 1,000 Tokens? • Screenshots • View Hierarchy • Logcat • User Actions • Analytics • Networking • Code
4. Context 🧠
5. Trailblaze Captures Context An AI-driven UI testing framework. Open source, Apache-2.0 · github.com/block/trailblaze Used at Square & Cash App — real apps, real devices, every day, in CI. brew install block/tap/trailblaze Open sourced on this stage last year — a lot has happened since.
6. Trailblaze Reports Surface Context https://block.github.io/trailblaze
7. Trailblaze Reports • Natural Language Steps • Tool Invocations • Screenshots • View Hierarchy • Logcat
8. You Own The Pipeline • Standalone report — servable from any CDN • Viewable in CI · downloadable as a zip • Same artifact structure on every platform • Analyzable by you… or by an agent • No SaaS backend required
9. Journeys for Android Studio https://developer.android.com/studio/gemini/journeys
10. LLMs are Expensive 💸
11. Trailblaze Differentiators • Natural language + recorded tools • Custom tools per app, available to the LLM • Full fidelity, native drivers/artifacts per platform • Consistent experience across platforms
12. Same User Journey, 7 Device Types Android phone Android tablet iPhone iPad Square Terminal Square Handheld One journey · seven targets · hundreds of trails today. Square Register
13. Trail Files Create a contact · Google Contacts · iOS + Android 1 · Just words 2 · + one recording 3 · + both any platform, day one iOS earns it first now it's fully pinned - step: Enter the name - step: Enter the name - step: Enter the name - step: Enter a phone - step: Save recording: recording: ios: ios: - inputText: Ada Lovelace - inputText: Ada Lovelace android: - inputText: Ada Lovelace
14. trail.yaml = The User Journey trailhead: # the deterministic start — defined in a minute step: Enter the name recording: ios: - tapOnElementBySelector: { textRegex: First name } - inputText: Casey android: - inputText: Casey trail: - step: Add the mobile number 555-0134 recording: ios: - tapOnElementBySelector: { textRegex: add phone } - inputText: "5550134" android: - tapOnElementBySelector: { inputType: 3 } - inputText: "5550134" - verify: The contact card shows the mobile number 555-0134 The words exist exactly once — the two recordings from the flaw slide, now nested under one step.
15. Blaze once, trail forever. LLMs are expensive and recordings are faster
16. It's not easy A reliable trail takes many cycles
17. The Trail Lifecycle blaze 🤖 🥾 user journey (natural language) accept trail + recordings refine replay · zero LLM git archive CI run app changed: self-heal 🤖 📦 last run
18. Triage 1. @bot triage the trailblaze test failure in build 1234 2. Go look at the Trailblaze Report
19. Self-heal == Recompilation with Context • App changed? Recompile the step — against the app as it is now • The agent meets the objective… or says it can't • Off by default — failures stay actionable • % self-healed = your staleness signal
20. We're blazing a lot of trails… …so we have a trailmap 🗺 your tools · your trails · your app's map # trails/config/trailmaps/contacts/trailmap.yaml — in the repo today id: contacts dependencies: - trailblaze target: display_name: Contacts platforms: android: app_ids: - com.google.android.contacts - com.android.contacts tools: - contacts_android_launchApp # …ios, web, compose: same shape waypoints: # …100 named places in this app — that map arrives in a few minutes
21. Trailheads for Deterministic Starts • A trailhead is a tool — the designated start • Clear app data · launch args · known state • Test accounts & setup are real — AI can't invent state • Deterministic setup → deterministic replay • Most flaky tests die right here.
22. Trail Map and Waypoints Demo http://localhost:52525/waypoints/graph#target=contacts&platform=android
23. Create a Trailmap for Droidcon’s App 9:50pm - Wed, July 15th The currently connected Android Emulator has the Droidcon app installed. I'm making a presentation tomorrow and I need you to create a @trails/config/trailmaps trailmap for the android app please! Our goal is to explore the "Droidcon USA 2026" portion of the app primarily but you can peek at a few other events. Your job is to walk the app, create a trailhead that will allow you to launch/start the app in a reliable way, and then explore the app. You should be able to produce at least 20 waypoints along with their screenshots and samples, etc. Just explore the app USING trailblaze please to build our trailmap. Other examples include @trails/config/trailmaps/contacts (this is our prime example). Go! http://localhost:52525/waypoints/graph#target=droidcon
24. Custom Tools Demo 🛠
25. Tools are typesafe, can return data, not just text • Structured JSON results — typed by tool<In, Out> • listInstalledApps() · getUserProfile() • One step's result feeds the next step
26. trailblaze check One param change → hundreds of YAML files — no human reviews that diff • Gate 1: strict parsing — unknown fields are errors • Gate 2: the tsc trick — recordings compiled as TypeScript Errors map back to trail.yaml · step 3 [android-phone]
27. Trailblaze is NOT Just for Test Authoring • An agent + an objective + a device — that's enough • With a trailmap: fewer decisions, tools do the work underneath • Everything is already being captured
28. 2016 → 2026 The robot pattern outlived every framework it was written in. Now the robots write the tests. And for the first time — you can see it all. Questions? 🙋
29. Blaze once, trail forever. brew install block/tap/trailblaze Tell Claude / Codex to use it on your app github.com/block/trailblaze