Flowtest— plugin

<p align="center"> <h1 align="center">FlowTest</h1> <p align="center">AI-powered cross-platform test runner for web, Android, and iOS</p> <p align="center"> <a href="#installation">Install</a> &bull; <a href="#quick-start">Quick Start</a> &bull; <a href="#writing-flows">Write Flows</a> &bull; <a href="#refine">Refine</a> &bull; <a href="#report">Report</a> &bull; <a href="#contributing">Contribute</a> </p> </p>

Write declarative YAML steps for predictable UI interactions. Add ai: steps where the UI is dynamic — Claude drives those sections automatically using full context from prior steps. Get an HTML report with video, screenshots, and step timeline.

No API keys. No extra billing. No TypeScript to maintain. Uses the claude CLI you already have.

Report Header

How it works

                    ┌─────────────────────────────────────────┐
                    │              flowtest                   │
flow.yaml ────────► │                                         │ ────► report/
                    │  Declarative steps → shell commands     │       ├── viewer.html
                    │  AI steps → Claude drives with context  │       ├── recording.webm
                    │  Screenshots after every action         │       ├── results.json
                    │                                         │       └── screenshots/
                    └─────────────────────────────────────────┘

• Declarative steps (tapOn:, assertVisible:, inputText:, etc.) are translated directly to shell commands against the platform driver — no AI reasoning, instant execution.
• AI steps (ai:) are driven by Claude using the full context accumulated from all prior steps — screenshots, element trees, results. Claude already knows the app state.
• Reports include video recording (web), screenshots per step, console logs, and a self-contained HTML viewer.

Installation

Prerequisites

Only install what you need. Web-only flows need claude + agent-browser + node.

Install flowtest

# Clone the repo
git clone https://github.com/anthropics/flowtest.git

# Copy the skill folder to your Claude Code skills directory
cp -r flowtest/flowtest ~/.claude/skills/flowtest

That's it. The flowtest/ skill folder contains everything — the runner skill, the refine sub-skill, report templates, and generation scripts. No extra setup needed.

After installing, /flowtest and /refine will be available as slash commands in Claude Code.

Quick Start

1. Write a flow

Create flows/checkout.yaml:

flow: checkout
platform: web # override with --platform web|android|ios
app: https://demo-store.example.com
bundle_android: com.example.demo
bundle_ios: com.example.demo

steps:
  - tapOn: "Sign in"
  - inputText: "[email protected]"
  - tapOn: "Log in"
  - wait: 2000
  - assertVisible: "Dashboard"
  - ai:
      goal: "Buy the first product and complete checkout with test credit card"
      max_steps: 30
  - assertVisible: "Order confirmed"
  - screenshot: order-confirmed

2. Refine it (optional but recommended)

/refine flows/checkout.yaml

Claude asks clarifying questions about your vague ai: goals and transforms them into detailed, actionable instructions. See Refine for details.

3. Run it

/flowtest flows/checkout.yaml

4. View the report

Open flowtest-report-checkout-<timestamp>/viewer.html in any browser.

Writing flows

Flows are YAML files with three required fields:

flow: my-flow-name               # Name (used in report directory)
platform: web                    # web | android | ios — override with --platform
app: https://myapp.com           # URL for web
bundle_android: com.example.demo # Android package ID
bundle_ios: com.example.demo     # iOS bundle ID

steps:
  -  # ... step list

Step types

Verify steps

verify: lets you define a list of plain-language checks that the agent evaluates using its AI judgment — screenshot analysis, DOM inspection, and visual reasoning. Each check is a natural language description of what should be true at that moment.

Works for:

• UI checks — element visibility, text content, layout state
• Animation checks — CSS transitions, canvas activity, motion indicators
• Logic checks — computed values, counters, conditional UI, form state

- verify:
    checks:
      - "Order confirmation message is visible"
      - "Order number is displayed on screen"
      - "Success animation plays after purchase"
      - "Total price matches what was in the cart"

Each check reports individually in the HTML report — you see which passed, which failed, and why. The overall step fails if any single check fails.

Environment variables

Reference env vars with $ prefix. Resolved at runtime.

- inputText: "$TEST_EMAIL"
- inputText:
    text: "$TEST_PASSWORD"
    mask: true

Platform conditionals

- when:
    platform: ios
    do:
      - tapOn: "Allow"
  else:
    do:
      - tapOn: "OK"

AI steps

AI steps hand control to Claude. Provide a goal describing what to accomplish and an optional max_steps limit.

- ai:
    goal: "Add the first product to cart and complete checkout"
    max_steps: 25

Simple goals work, but vague goals produce inconsistent results. Use /refine to strengthen them before running.

Supported platforms

Flutter

FlowTest works with Flutter apps on all three platforms. Build and install your app first, then run the flow as normal.

# Flutter web — run on a fixed port so the URL is predictable
flutter run -d web-server --web-port 54545

# Flutter Android — build a debug APK and install it
flutter build apk --debug
adb install -r build/app/outputs/flutter-apk/app-debug.apk

# Flutter iOS (simulator) — build and install via idb
flutter build ios --debug --simulator
idb install build/ios/iphonesimulator/Runner.app

Flutter works across all three platforms:

• Flutter web — works out of the box. Flutter generates a shadow DOM accessibility tree alongside its canvas, which agent-browser reads through Chrome DevTools accessibility APIs.
• Flutter Android — build an APK and install it via adb before running.
• Flutter iOS — build the app and install it via idb before running.

Refine

/refine is a flow improvement assistant. It reads your YAML, asks clarifying questions about vague ai: goals, and generates detailed, actionable goals that produce consistent results.

Before and after

Before — a vague goal:

- ai:
    goal: "Buy something and check out"
    max_steps: 30

After — /refine asks questions and produces:

- ai:
    goal: |
      Purchase the first available product and complete checkout.

      FOR EACH step:
      1. Navigate to Products page — tap "Shop" or "Products" in navigation
      2. Select the first product card
      3. Tap "Add to Cart" and verify cart badge updates
      4. Open cart and tap "Checkout"
      5. Fill shipping: Jane Doe, 123 Main St, San Francisco, CA 94102
      6. Fill payment: card 4242 4242 4242 4242, expiry 12/28, CVC 123
      7. Tap "Place Order"

      STOP when "Order confirmed" or "Thank you" appears.
    max_steps: 25

How refine works

1. Reads your YAML and identifies all ai: steps
2. Analyzes gaps — missing assertions, screenshots, wait steps
3. Asks clarifying questions one at a time, across 6 categories:

1. Generates refined YAML with structured goals and added declarative steps
2. Shows diff for your approval before writing

Usage

/refine flows/checkout.yaml

Report

Each run produces a self-contained report directory:

flowtest-report-checkout-2026-03-29T10-30-00/
  viewer.html           # Interactive HTML report
  results.json          # Machine-readable results
  recording.webm        # Video recording (web only)
  screenshots/
    step-00-tapOn.png
    step-03-sub-0-iter-0.png
    step-03-sub-0-iter-1.png
    step-03-sub-0-final.png
    ...

Viewer

Open viewer.html in any browser. No server needed.

Dashboard — flow name, health score, pass/fail counts, duration:

Report Header

Execution log — every step with result, duration, and timestamp:

Report Steps

AI sub-steps — click an AI step to expand. Each logical task (browse products, fill form, confirm order) is its own row with screenshots:

Report Sub-steps

Iteration details — expand a sub-step to see every action with screenshots:

Report Detail

Results JSON

The results.json file contains structured data for CI integration:

{
  "flow": "checkout",
  "platform": "web",
  "healthScore": 1.0,
  "totalSteps": 5,
  "passedSteps": 5,
  "failedSteps": 0,
  "duration": 262000,
  "steps": [
    {
      "index": 0,
      "type": "tapOn",
      "input": "Sign in",
      "result": "pass",
      "screenshot": "screenshots/step-00-tapOn.png",
      "subSteps": []
    }
  ]
}

AI steps include subSteps with per-task breakdowns and iterations with per-action detail.

Plugins

FlowTest ships with two Claude Code slash-command plugins:

Both plugins are installed together:

cp -r flowtest/flowtest ~/.claude/skills/flowtest

CLI Reference

/flowtest

/flowtest <yaml-file> [options]

Default platform: If --platform is not passed, the platform is read from the platform: field in the YAML. If that is also absent, web is used.

# Run on web (default if --platform is omitted)
/flowtest flows/my-flow.yaml

# Run on Android
/flowtest flows/my-flow.yaml --platform android

# Run on iOS
/flowtest flows/my-flow.yaml --platform ios

/refine

/refine <yaml-file>

Reads the flow, asks questions, suggests improvements, writes refined YAML on approval.

Project structure

flowtest/
├── flowtest/                    # Skill folder (copy this to ~/.claude/skills/flowtest)
│   ├── SKILL.md                 # /flowtest slash command (the runner)
│   ├── refine/
│   │   └── SKILL.md             # /refine slash command (flow improver)
│   ├── scripts/
│   │   └── generate-report.js   # results.json → viewer.html
│   └── templates/
│       └── viewer.html          # HTML report template
├── examples/
│   ├── sample-checkout.yaml     # Example checkout flow
│   └── sample-report/           # Example report with screenshots
├── docs/
│   └── images/                  # README screenshots
└── README.md

The flowtest/ folder is self-contained — copy it to ~/.claude/skills/flowtest and everything works.

Contributing

Contributions are welcome. Here's how to get started:

Development setup

git clone https://github.com/anthropics/flowtest.git
cd flowtest

# Install the skill locally for testing
cp -r flowtest ~/.claude/skills/flowtest

# Run the sample report to verify setup
node flowtest/scripts/generate-report.js examples/sample-report
open examples/sample-report/viewer.html

Areas to contribute

• New platform drivers — support for other browser automation tools
• Viewer improvements — new visualizations, filtering, search in the HTML report
• Step types — new declarative step types (drag, long press, pinch, etc.)
• CI integration — GitHub Actions, GitLab CI examples and helpers
• Documentation — guides, tutorials, more examples

Submitting changes

1. Fork the repo
2. Create a feature branch: git checkout -b feat/my-feature
3. Make your changes
4. Test with the sample report: node flowtest/scripts/generate-report.js examples/sample-report
5. Open a PR with a clear description

Code style

• Keep skill files (flowtest/SKILL.md, flowtest/refine/SKILL.md) focused and well-structured
• Keep the viewer template (flowtest/templates/viewer.html) as a single self-contained file
• Use vanilla JS in the viewer — no build step, no dependencies

License

MIT