Walkthrough Agent

An agentic MCP server that reads your app's source code, generates contextually valid dummy data, and drives a browser through your pages — narrating every step.

What it does

Developer runs agent
       ↓
Agent reads source folder → understands page structure
       ↓
Gemini generates contextually valid dummy inputs
       ↓
Playwright opens localhost URL + fills inputs + navigates
       ↓
On validation error → extract error from DOM → Gemini corrects inputs → retry (up to 3x)
       ↓
Output: terminal narration + screenshots + markdown report + Playwright trace

Setup

git clone <this repo>
cd walkthrough-agent
npm install
npx playwright install chromium
cp .env.example .env
# Add your GEMINI_API_KEY to .env

Get a free Gemini API key at aistudio.google.com.

Usage

Standalone CLI (fastest)

# Analyze + generate inputs + run browser walkthrough
npx walkthrough-agent --url http://localhost:3000/signup --folder ./src/app/signup

# DOM-only mode (no source folder needed)
npx walkthrough-agent --url http://localhost:3000/login

# Analyze only — print PageAnalysis + InputMap, no browser
npx walkthrough-agent --url http://localhost:3000/signup --folder ./src --analyze-only

# Override entry file detection
npx walkthrough-agent --url http://localhost:3000 --folder ./src --entry App.tsx

# Adjust max retries
npx walkthrough-agent --url http://localhost:3000/signup --folder ./src --retries 5

Output

Each run creates a timestamped directory:

output/run-2026-01-15-143022/
  report.md           ← walkthrough narrative
  trace.zip           ← Playwright trace (open at trace.playwright.dev)
  screenshots/
    01-page-load.png
    02-fill-email.png
    03-submit.png
    04-result.png

As an MCP Server (Gemini CLI)

1. Build first: npm run build
2. Add to your Gemini CLI config:

{
  "mcpServers": {
    "walkthrough-agent": {
      "command": "node",
      "args": ["/path/to/walkthrough-agent/dist/server.js"],
      "env": { "GEMINI_API_KEY": "your-key-here" }
    }
  }
}

3. Tools available in Gemini CLI:
   • analyze_page — extract form structure from source + live DOM
   • generate_inputs — generate valid dummy data
   • run_walkthrough — drive Playwright through the page
   • generate_report — write markdown report

Example terminal output

Walkthrough Agent
──────────────────────────────────────────────────

Analyzing ./src/app/signup ...
   Entry file: page.tsx
   Found: email, password, confirm-password, submit
   Validation rules: valid email, min 8 chars, must match password

Generating inputs...
   email                → [email protected]
   password             → Walkthrough#42
   confirm-password     → Walkthrough#42

Output directory: output/run-2026-01-15-143022

   Opening http://localhost:3000/signup
    Page loaded
    email filled
    password filled
    confirm-password filled

   Submitting...
    Error detected: "Password must contain a special character"
    Retry 1/3 — correcting inputs...
    Submission successful

──────────────────────────────────────────────────
Screenshot(s) saved: 6 files in output/run-.../screenshots
Report saved:        output/run-.../report.md
Trace saved:         output/run-.../trace.zip

Known concerns (before shipping v1)

See PLAN.md for items to address before implementation:

• FormElement stable key algorithm
• Error selector → fieldId mapping
• analyze_page Playwright lifecycle in DOM-only mode
• TypeScript build tooling verified above
• Gemini free-tier quota — verify before heavy use
• Report schema — implemented in src/tools/report.ts

v2 roadmap

• Auth support (--session-cookie flag)
• Multi-page flow chaining
• Negative test case generation
• CI/CD — GitHub Action that posts walkthrough report as PR comment
• Claude Desktop MCP support