https://github.com/block/trailblaze
AI-driven UI testing framework.
https://github.com/block/trailblaze
Last synced: 2 months ago
JSON representation
AI-driven UI testing framework.
- Host: GitHub
- URL: https://github.com/block/trailblaze
- Owner: block
- License: apache-2.0
- Created: 2025-06-10T18:29:40.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-29T15:28:39.000Z (3 months ago)
- Last Synced: 2026-03-29T18:07:28.303Z (3 months ago)
- Language: Kotlin
- Homepage: https://block.github.io/trailblaze/
- Size: 28.1 MB
- Stars: 219
- Watchers: 5
- Forks: 11
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Support: docs/support.md
- Governance: GOVERNANCE.md
- Roadmap: docs/roadmap.md
Awesome Lists containing this project
README
# 🧭 Trailblaze
_[Trailblaze](https://github.com/block/trailblaze) is an AI-powered UI testing framework that lets you author and
execute tests using natural language._
## Current Vision
Trailblaze enables adoption of AI powered tests in regular Android on-device instrumentation tests.
This allows leveraging existing execution environments and reporting systems, providing a path to gradually adopt
AI-driven tests at scale.
Because Trailblaze uses [Maestro](https://github.com/mobile-dev-inc/maestro) Command Models for UI interactions it
enables a longer term vision of cross-platform ui testing while reusing the same authoring, agent
and reporting capabilities.
### Core Features
- **AI-Powered Testing**: More resilient tests using natural language test steps
- **On-Device Execution**: Runs directly on Android devices using standard instrumentation tests (Espresso, UiAutomator)
- **Custom Agent Tools**: Extend functionality by providing app-specific `TrailblazeTool`s to the agent
- **Detailed Reporting**: Comprehensive test execution reports
- **Maestro Integration**: Uses a custom on-device driver for Maestro to leverage intuitive, platform-agnostic UI interactions
### Multi-Agent V3 Features (Mobile-Agent-v3 Inspired)
Trailblaze implements cutting-edge features from [Mobile-Agent-v3](https://arxiv.org/abs/2508.15144) research:
| Feature | Description |
|---------|-------------|
| **Exception Handling** | Automatically handles popups, ads, loading states, and errors |
| **Reflection & Self-Correction** | Detects stuck states and loops, backtracks when needed |
| **Task Decomposition** | Breaks complex objectives into manageable subtasks |
| **Cross-App Memory** | Remembers information across app switches for complex workflows |
| **Enhanced Recording** | Captures pre/post conditions for more robust replay |
| **Progress Reporting** | Real-time MCP progress events for IDE integrations |
### Trail & Blaze Architecture
Trailblaze's unique "**blaze once, trail forever**" workflow:
- **Blaze Mode**: AI explores the app to achieve objectives, discovering the path dynamically
- **Trail Mode**: Replay recorded actions deterministically with zero LLM cost
- **Hybrid Mode**: Use recordings where available, fall back to AI when needed
```
┌─────────────────────────────────────────────────────────────┐
│ First Run: BLAZE │
│ AI explores → Records actions → Generates .trail.yaml │
└──────────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Future Runs: TRAIL │
│ Replay recordings → Zero LLM cost → Fast CI/CD execution │
└─────────────────────────────────────────────────────────────┘
```
## Installation
```bash
curl -fsSL https://raw.githubusercontent.com/block/trailblaze/main/install.sh | bash
```
## Getting Started
### Launch the Desktop App
```bash
trailblaze app
```
### MCP Server for Claude
Add Trailblaze as an MCP server so Claude can interact with connected devices:
```bash
trailblaze mcp install claude
```
Or manually add to your Claude config (`claude_desktop_config.json` or `.mcp.json`):
```json
{
"mcpServers": {
"trailblaze": {
"command": "trailblaze",
"args": ["mcp"]
}
}
}
```
## Documentation at block.github.io/trailblaze
See [Mobile-Agent-v3 Features Guide](docs/mobile-agent-v3-features.md) for detailed usage examples.