Michi QA

What it does

• Reads requirements from Gherkin .feature files, Markdown, plain text, JSON and .eml.
• Builds a deterministic test plan with requirement-to-test traceability, runs it in Chromium, and writes JSON, JUnit and HTML reports with screenshots and traces.
• Runs as persistent background jobs, from a CLI, from an MCP stdio server (Michi, Claude Code), or from a Chrome side panel.
• Validates tickets: a harness hands it Gherkin for a story or a bug, and it returns a verdict per acceptance criterion, or whether the bug reproduced. It never writes to your tracker.

The model never marks a test as passed

An engine can choose scope and priority. It cannot declare a test passed or lower a deterministic safety floor. Infrastructure failures are inconclusive, never passed, and a step that matches nothing is not_implemented and is never run. The statuses are: passed, failed, skipped, blocked, not_implemented, not_executed, inconclusive.

• Michi Decider V3 answers two closed questions, difficulty and kind. Everything else in a decision (risk, scope, priority, category) comes from fixed rules and is labelled as such in every decision record.
• Jev is optional. It can also assist single steps over a redacted text snapshot of the page, and a judgment can fail a scenario but never pass one.
• Compare mode runs both; one controls the plan and the other only observes.

Install

Needs Node 22.5 or newer. The repository is private today, so GitHub CLI must be signed in as a collaborator (gh auth login).

The installer runs npm install, installs Chromium, builds, then asks you to set up the engines. For a project of your own: ./install.sh --dir ../my-app --base-url http://localhost:3000.

• V3 reuses the model and runtime Michi already keeps under ~/.michi. If they are missing it tells you what to install. Nothing is downloaded or copied.
• Jev key (optional) goes in a hidden prompt and into the OS keychain, or comes from an environment variable. It is never written to the config or logged.
• Register it with Michi (michi mcp add, Michi 5.8.4 or newer) and/or Claude Code.

Quick start

michi-qa init                              # writes michi-qa.yaml
michi-qa engines doctor                    # which engines are usable, and why not
michi-qa plan features/ --engine v3        # deterministic plan, JSON on stdout
michi-qa run features/ --engine compare    # run, wait, write reports
michi-qa run features/ --background        # returns a job id
michi-qa report <id> --format junit

Exit codes: 0 ok, 1 tests failed, 2 usage or config, 3 engine unavailable, 4 environment or inconclusive, 5 waiting for approval.

Safety

• Every browser request is checked against an allowlist; cloud metadata addresses are always blocked.
• Destructive scenarios need a person to approve them, and are never allowed in production. MCP callers cannot approve.
• The Jev key is redacted from logs and reports, and page snapshots exclude passwords and field values.

Limits

• Only Chromium has been tested. Windows and Linux have not been run.
• V3 needs its model and runtime on your machine; if they are missing it reports unavailable and is never replaced by a mock.
• Jev-assisted steps have so far been tested only against a scripted mock. Their thresholds are not calibrated for this tool.
• Engine agreement is not accuracy, and the bundled benchmark is small and author-labelled.