maestro-testgen

English | 中文

A skill that derives UI-behavior regression tests from a git diff or a natural-language description: it first produces a durable manual test case document, and only when automation is actually feasible generates a runnable Maestro YAML flow. Targets UI-behavior regression for Android / iOS / Web.

Core idea: decide first → keep a manual case → then automate.

Does / Doesn't

Does	Doesn't
Judge whether a change is user-visible UI behavior	Generate YAML straight from a diff
Write a durable, human-runnable manual test case first	Generate Maestro for pure logic (Mapper/Service/sort/format…)
Generate Maestro YAML when feasible (stable selectors, no coordinates)	Delete core assertions just to make a test pass
Auto-run YAML via CLI when a device is online, emit an HTML report + screenshots into the qa dir & triage failures; inspect the live hierarchy via MCP to calibrate selectors	Hardcode YAML when evidence is insufficient
Degrade when no device is online: print the run command + prompt to start a device	Hard-run maestro test with no device

Directory layout

maestro-testgen/
├── .claude-plugin/     # plugin.json + marketplace.json (self-hosted marketplace)
├── .mcp.json           # bundled Maestro MCP server (auto-registered on install)
├── SKILL.md            # required, contains name + description
├── commands/           # /maestro-testgen slash command (auto-discovered by the plugin)
├── references/         # 5 on-demand reference files
│   ├── workflow.md             # input modes A(git diff) / B(natural language), what to read
│   ├── decision-rules.md       # what suits Maestro vs not
│   ├── manual-case-template.md # manual test case format
│   ├── maestro-yaml-rules.md   # Maestro YAML authoring rules
│   └── run-and-mcp.md          # MCP setup, device detect, auto-run, failure triage
├── agents/openai.yaml  # Codex UI metadata
└── USAGE.md            # usage guide (non-standard skill file, excludable when distributing)

Install

As a plugin (recommended)

/plugin marketplace add ujffdi/maestro-testgen
/plugin install maestro-testgen@maestro-testgen

The plugin bundles a .mcp.json, so the Maestro MCP server is registered automatically on install — no manual claude mcp add needed.

Manual (copy the skill)

# Claude Code (project scope)
cp -R maestro-testgen <your-project>/.claude/skills/
# then register the MCP server yourself:
claude mcp add -s project maestro -- maestro mcp

Either way, install the Maestro CLI (required to auto-run YAML):

curl -fsSL "https://get.maestro.mobile.dev" | bash

Full usage → USAGE.md.

Workflow (always in this order)

1. Detect input mode (git diff vs natural language)
2. Gather evidence (read the change / related code)
3. Emit the Test Routing Decision (UI behavior vs pure logic)
4. Write the manual test case document (primary deliverable)
5. Judge automation feasibility
6. Generate Maestro YAML only when ready
7. Auto-run: maestro list-devices → if a device is online, run maestro test end-to-end with --format (default is NOOP = no report), emit an HTML report to qa/manual-cases/reports/ + screenshots to qa/manual-cases/evidence/, then triage failures; if none, degrade (print command + prompt maestro start-device). Otherwise explain the blocker and what to supply.