Your first test 你的第一个测试
This walkthrough takes you from a blank folder to a green run in under five minutes. You'll install the Tapilot CLI, write a short DSL file that drives a real Android app, and see the same test executed three ways — desktop, CLI, and through an MCP agent. 本教程带你在五分钟内，从一个空文件夹抵达一条通过的测试记录。 你将安装 Tapilot CLI、编写一个驱动真实 Android 应用的 DSL 文件， 并通过三种方式运行同一条测试：桌面端、命令行、以及 MCP Agent。
Install Tapilot 安装 Tapilot #
Pick your platform. The tapilot CLI bundles the desktop UI, the MCP server, and the device bridges.
选择你的平台。tapilot CLI 已内置桌面端、MCP 服务和设备桥接。
# Homebrew — includes desktop app, CLI and MCP server brew install tapilot/tap/tapilot # Verify tapilot --version # → tapilot 0.3.7 (darwin/arm64, mcp 0.3.7)
# winget, or scoop bucket add tapilot https://github.com/tapilot/scoop winget install Tapilot.Tapilot # Ensure adb is on PATH for Android device tests tapilot doctor
# Static binary — no runtime deps curl -fsSL https://get.tapilot.dev | sh # Or via npm (CLI + MCP only, no desktop UI) npm i -g tapilot-mcp
Prefer a Docker image for CI? See Deployment → Docker. 希望在 CI 中使用 Docker？查看 部署 → Docker。
Write the DSL 编写 DSL #
Tapilot tests are YAML-flavored documents. A device key picks a target, and
steps is an ordered list of actions from the
24-action DSL. Indentation nests control flow; there are no hidden hooks
and no programming language to master.
Tapilot 测试是 YAML 风格的文档。device 选择目标设备，
steps 是一个有序的动作列表，来自
24 个 DSL 动作。缩进表示控制流嵌套，没有隐藏钩子，也不需要学习编程语言。
# tests/sign_in.tapilot.yml device: android vars: user: "alice@acme.dev" pin: "654321" steps: - open app: com.acme.shop - tap: "Sign in" - type: email = "{{ user }}" - type: pin = "{{ pin }}" - tap: "Continue" - assert visible: "Welcome, Alice" - assert count: "Order" >= 1 - screenshot: "home"
android, ios, web, or a named profile from tapilot.config.yml.{{ var }} — including from env and secret stores.
任何步骤都可以使用 {{ var }} 插值，支持环境变量与密钥存储。Run it 运行测试 #
Exactly the same test file, three entry points. Pick whichever fits the moment — iterate in the desktop app, wire it into CI with the CLI, or hand it to an LLM through MCP. 同一个测试文件，三种入口。桌面端用于迭代调试；CLI 用于接入 CI；MCP 让 LLM 直接调用。
# Opens the run in the desktop app — live DOM, video, and step timeline tapilot open tests/sign_in.tapilot.yml # → Pixel 7a (emulator-5554) · 14 steps · ✓ passed in 12.4s
# Headless — ideal for CI. --report emits a markdown + assets bundle. tapilot run tests/sign_in.tapilot.yml \ --device emulator-5554 \ --report out/sign_in \ --retries 1 # → ✓ sign_in 14/14 steps 12.4s out/sign_in/run.md
// Called by any MCP-aware client (Claude Desktop, Cursor, Zed, your own agent) { "tool": "tapilot.run_test", "args": { "file": "tests/sign_in.tapilot.yml", "device": "android:emulator-5554", "vars": { "pin": "654321" } } }
--watch to the CLI to re-run on file changes. Pair it with --only "step label" to iterate on a single step without replaying the whole flow.
在 CLI 加上 --watch 可监听文件变化自动重跑；配合 --only "步骤名" 可只重跑单个步骤，调试效率更高。
Read the report 查看报告 #
Every run produces a report pack — a zipped folder that is also a valid markdown document, so it renders cleanly in GitHub, Slack, Linear, and any LLM context window. 每次运行都会生成一个报告包——既是压缩文件夹，也是合法的 Markdown 文档，可以在 GitHub、Slack、Linear 及各类 LLM 上下文中直接渲染。