# 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

```bash
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](https://aistudio.google.com).

## Usage

### Standalone CLI (fastest)

```bash
# 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:

```json
{
  "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                → alex.morgan@testmail.dev
   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](./PLAN.md#known-concerns) 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