HarshJudge E2E Testing
AI-native E2E testing with MCP tools and visual evidence capture.
Core Principles
- Evidence First: Screenshot before and after every action
- Fail Fast: Stop on error, report with context
- Complete Runs: Always call
completeRun, even on failure
- Step Isolation: Each step executes in its own spawned agent for token efficiency
- Knowledge Accumulation: Learnings go to
prd.md, not scenarios
Step-Based Execution
HarshJudge uses a step-based agent pattern for token-efficient test execution:
Main Agent Step Agents (spawned per step)
│
├─ startRun(scenarioSlug)
│ ↓
│ Returns: runId, steps[]
│
├─► Spawn Agent: Step 01 ──────────────────────► Execute actions
│ │ │
│ │ ◄─────────────────────────────────── Return: { status, evidencePaths }
│ │
│ completeStep(runId, "01", status)
│ │
├─► Spawn Agent: Step 02 ──────────────────────► Execute actions
│ │ │
│ │ ◄─────────────────────────────────── Return: { status, evidencePaths }
│ │
│ completeStep(runId, "02", status)
│ │
│ ... (repeat for each step)
│
└─ completeRun(runId, finalStatus)
Benefits:
- Each step agent has isolated context (no token accumulation)
- Large outputs (screenshots, logs) saved to files, not returned
- Main agent only receives concise summaries
- Automatic token optimization without manual management
Workflows
| Intent |
Reference |
Key Tools |
| Initialize project |
references/setup.md |
initProject |
| Create scenario |
references/create.md |
createScenario |
| Run scenario |
references/run.md |
startRun, completeStep, completeRun |
| Fix failed test |
references/iterate.md |
getStatus, createScenario |
| Check status |
references/status.md |
getStatus |
Project Structure
.harshJudge/
config.yaml # Project configuration
prd.md # Product requirements (from assets/prd.md template)
scenarios/{slug}/
meta.yaml # Scenario definition + run statistics
steps/ # Individual step files
01-step-slug.md # Step 01 details
02-step-slug.md # Step 02 details
...
runs/{runId}/ # Run history
result.json # Run result with per-step data
step-01/evidence/ # Step 01 evidence
step-02/evidence/ # Step 02 evidence
...
snapshots/ # Inspection tool outputs (token-saving pattern)
Quick Reference
HarshJudge MCP Tools
| Tool |
Purpose |
initProject |
Initialize project (spawns dashboard) |
createScenario |
Create/update scenario with step files |
toggleStar |
Toggle/set scenario starred status |
startRun |
Start test run, returns step list |
recordEvidence |
Capture evidence for a step |
completeStep |
Complete a step, get next step ID |
completeRun |
Finalize run with status |
getStatus |
Check project or scenario status |
openDashboard / closeDashboard |
Manage dashboard server |
Playwright MCP Tools
| Tool |
Purpose |
browser_navigate |
Navigate to URL |
browser_snapshot |
Get accessibility tree (use before click/type) |
browser_click |
Click element using ref |
browser_type |
Type into input using ref |
browser_take_screenshot |
Capture screenshot for evidence |
browser_console_messages |
Get console logs |
browser_network_requests |
Get network activity |
browser_wait_for |
Wait for text/condition |
Step Agent Prompt Template
When spawning an agent for each step:
Execute step {stepId} of scenario {scenarioSlug}:
## Step Content
{content from steps/{stepId}-{slug}.md}
## Project Context
Base URL: {from config.yaml}
Auth: {from prd.md if needed}
## Previous Step
Status: {pass|fail|first step}
## Your Task
1. Execute the actions using Playwright MCP tools
2. Use browser_snapshot before clicking to get element refs
3. Capture before/after screenshots using browser_take_screenshot
4. Record evidence using recordEvidence with step={stepNumber}
Return ONLY a JSON object:
{
"status": "pass" | "fail",
"evidencePaths": ["path1.png", "path2.png"],
"error": null | "error message"
}
DO NOT return full evidence content. DO NOT explain your work.
Error Handling
On ANY error:
- STOP - Do not proceed
- Report - Tool, params, error, resolution
- Check prd.md - Is this a known pattern?
- Do NOT retry - Unless user instructs
1---2name: harshjudge3description: AI-native E2E testing orchestration for Claude Code. Use when creating, running, or managing end-to-end test scenarios with visual evidence capture. Activates for tasks involving E2E tests, browser automation testing, test scenario creation, test execution with screenshots, or checking test status.4---5
6# HarshJudge E2E Testing
7
8AI-native E2E testing with MCP tools and visual evidence capture.
9
10## Core Principles
11
121. **Evidence First**: Screenshot before and after every action
132. **Fail Fast**: Stop on error, report with context
143. **Complete Runs**: Always call `completeRun`, even on failure
154. **Step Isolation**: Each step executes in its own spawned agent for token efficiency
165. **Knowledge Accumulation**: Learnings go to `prd.md`, not scenarios
17
18## Step-Based Execution
19
20HarshJudge uses a **step-based agent pattern** for token-efficient test execution:
21
22```
23Main Agent Step Agents (spawned per step)
24 │
25 ├─ startRun(scenarioSlug)
26 │ ↓
27 │ Returns: runId, steps[]
28 │
29 ├─► Spawn Agent: Step 01 ──────────────────────► Execute actions
30 │ │ │
31 │ │ ◄─────────────────────────────────── Return: { status, evidencePaths }
32 │ │
33 │ completeStep(runId, "01", status)
34 │ │
35 ├─► Spawn Agent: Step 02 ──────────────────────► Execute actions
36 │ │ │
37 │ │ ◄─────────────────────────────────── Return: { status, evidencePaths }
38 │ │
39 │ completeStep(runId, "02", status)
40 │ │
41 │ ... (repeat for each step)
42 │
43 └─ completeRun(runId, finalStatus)
44```
45
46**Benefits:**
47- Each step agent has isolated context (no token accumulation)
48- Large outputs (screenshots, logs) saved to files, not returned
49- Main agent only receives concise summaries
50- Automatic token optimization without manual management
51
52## Workflows
53
54| Intent | Reference | Key Tools |
55|--------|-----------|-----------|
56| Initialize project | [references/setup.md](references/setup.md) | `initProject` |
57| Create scenario | [references/create.md](references/create.md) | `createScenario` |
58| Run scenario | [references/run.md](references/run.md) | `startRun`, `completeStep`, `completeRun` |
59| Fix failed test | [references/iterate.md](references/iterate.md) | `getStatus`, `createScenario` |
60| Check status | [references/status.md](references/status.md) | `getStatus` |
61
62## Project Structure
63
64```
65.harshJudge/
66 config.yaml # Project configuration
67 prd.md # Product requirements (from assets/prd.md template)
68 scenarios/{slug}/
69 meta.yaml # Scenario definition + run statistics
70 steps/ # Individual step files
71 01-step-slug.md # Step 01 details
72 02-step-slug.md # Step 02 details
73 ...
74 runs/{runId}/ # Run history
75 result.json # Run result with per-step data
76 step-01/evidence/ # Step 01 evidence
77 step-02/evidence/ # Step 02 evidence
78 ...
79 snapshots/ # Inspection tool outputs (token-saving pattern)
80```
81
82## Quick Reference
83
84### HarshJudge MCP Tools
85
86| Tool | Purpose |
87|------|---------|
88| `initProject` | Initialize project (spawns dashboard) |
89| `createScenario` | Create/update scenario with step files |
90| `toggleStar` | Toggle/set scenario starred status |
91| `startRun` | Start test run, returns step list |
92| `recordEvidence` | Capture evidence for a step |
93| `completeStep` | Complete a step, get next step ID |
94| `completeRun` | Finalize run with status |
95| `getStatus` | Check project or scenario status |
96| `openDashboard` / `closeDashboard` | Manage dashboard server |
97
98### Playwright MCP Tools
99
100| Tool | Purpose |
101|------|---------|
102| `browser_navigate` | Navigate to URL |
103| `browser_snapshot` | Get accessibility tree (use before click/type) |
104| `browser_click` | Click element using ref |
105| `browser_type` | Type into input using ref |
106| `browser_take_screenshot` | Capture screenshot for evidence |
107| `browser_console_messages` | Get console logs |
108| `browser_network_requests` | Get network activity |
109| `browser_wait_for` | Wait for text/condition |
110
111## Step Agent Prompt Template
112
113When spawning an agent for each step:
114
115```
116Execute step {stepId} of scenario {scenarioSlug}:
117
118## Step Content
119{content from steps/{stepId}-{slug}.md}
120
121## Project Context
122Base URL: {from config.yaml}
123Auth: {from prd.md if needed}
124
125## Previous Step
126Status: {pass|fail|first step}
127
128## Your Task
1291. Execute the actions using Playwright MCP tools
1302. Use browser_snapshot before clicking to get element refs
1313. Capture before/after screenshots using browser_take_screenshot
1324. Record evidence using recordEvidence with step={stepNumber}
133
134Return ONLY a JSON object:
135{
136 "status": "pass" | "fail",
137 "evidencePaths": ["path1.png", "path2.png"],
138 "error": null | "error message"
139}
140
141DO NOT return full evidence content. DO NOT explain your work.
142```
143
144## Error Handling
145
146On ANY error:
1471. **STOP** - Do not proceed
1482. **Report** - Tool, params, error, resolution
1493. **Check prd.md** - Is this a known pattern?
1504. **Do NOT retry** - Unless user instructs
majiayu000