Skip to main content

​
Browser Verification

Frontend stories must be verified in a browser. Ralph can do this automatically using the dev-browser skill.

​
Why Browser Verification?

Typecheck and tests can’t catch visual bugs:
  • Layout issues
  • Broken styles
  • Missing elements
  • Incorrect interactions
A frontend story is NOT complete until visually verified. Many subtle bugs only appear in the browser.

​
Setting Up Browser Verification

1

Install dev-browser skill (Amp users)

The dev-browser skill is typically installed separately. Check if you have it:
ls ~/.config/amp/skills/ | grep browser
If not installed, you’ll need to add a browser automation skill compatible with Amp.
2

Add to acceptance criteria

For any UI story, include this criterion:
{
  "id": "US-003",
  "title": "Add status badge to task cards",
  "acceptanceCriteria": [
    "Each task card shows colored status badge",
    "Badge colors: gray=pending, blue=in_progress, green=done",
    "Typecheck passes",
    "Verify in browser using dev-browser skill"
  ]
}
3

Configure your dev server

Ensure your dev server can be started and accessed at a known URLAdd to your customized prompt.md:
## Browser Testing

For UI stories:
1. Ensure dev server is running on http://localhost:3000
2. Load the `dev-browser` skill
3. Navigate to the relevant page
4. Verify the changes work as expected
5. Take a screenshot for the progress log

​
Browser Verification Workflow

When Ralph encounters a story with browser verification:
1

Load the skill

Ralph will load the dev-browser skill:
Load the dev-browser skill
2

Navigate to the page

Ralph navigates to the URL where changes should be visible:
Navigate to http://localhost:3000/tasks
3

Interact with UI

Ralph performs actions to verify behavior:
Click the status dropdown on the first task
Verify the options appear: Pending, In Progress, Done
Select "In Progress"
Verify the badge color changes to blue
4

Take screenshot

Ralph captures evidence for the progress log:
Take a screenshot showing the blue badge
5

Document in progress.txt

Ralph records what was verified:
## 2026-03-11 14:30 - US-003

- Added status badge component to task cards
- Verified in browser:
  - All three status colors render correctly
  - Badge appears on each task card
  - Screenshot: [attached]

​
Claude Code Users

Claude Code doesn’t have built-in browser automation, but you can use MCP (Model Context Protocol) servers: 
## Browser Testing (via Playwright MCP)

For UI stories, verify changes using the Playwright MCP server:

1. Ensure dev server is running on http://localhost:3000
2. Use Playwright MCP tools to:
   - Navigate to the page
   - Interact with elements
   - Take screenshots
3. Document verification in progress.txt

Example:
Use playwright_navigate to http://localhost:3000/tasks Use playwright_click on the status dropdown Use playwright_screenshot to capture the result
If browser tools are not available, note in progress.txt that manual browser verification is needed after the iteration completes.

​
Writing Good Verification Criteria

Be specific about what to verify:

​
✅ Good Criteria

"acceptanceCriteria": [
  "Status dropdown appears when clicking the badge",
  "Dropdown shows three options: Pending, In Progress, Done",
  "Selecting an option updates the badge color immediately",
  "Badge colors: gray (pending), blue (in progress), green (done)",
  "Verify in browser using dev-browser skill"
]

​
❌ Vague Criteria

"acceptanceCriteria": [
  "Status badge works",
  "UI looks good",
  "Test in browser"
]
The more specific your criteria, the better Ralph can verify the implementation matches your requirements.

​
Common Verification Patterns

Acceptance Criteria:
- New "Export" button appears in the toolbar
- Button has a download icon
- Button is positioned to the right of the filter dropdown
- Verify in browser using dev-browser skill

Ralph will:
1. Navigate to the page
2. Locate the toolbar
3. Confirm button exists with correct icon and position
4. Screenshot the toolbar

Acceptance Criteria:
- Clicking "Mark as done" changes task status
- Task moves to the "Completed" section
- Page updates without refresh
- Verify in browser using dev-browser skill

Ralph will:
1. Navigate to the tasks page
2. Click "Mark as done" on a task
3. Verify the task moves to completed section
4. Verify no page reload occurred
5. Screenshot before and after

Acceptance Criteria:
- Submitting empty form shows "Title is required" error
- Error appears below the title input
- Error is red text
- Verify in browser using dev-browser skill

Ralph will:
1. Navigate to the form
2. Click submit without entering data
3. Verify error message appears
4. Verify error styling
5. Screenshot the validation error

Acceptance Criteria:
- Navigation collapses to hamburger menu on mobile (< 768px)
- Clicking hamburger opens slide-out menu
- Menu items are stacked vertically
- Verify in browser using dev-browser skill at mobile viewport

Ralph will:
1. Navigate to the page
2. Resize viewport to 375x667 (iPhone)
3. Verify hamburger menu appears
4. Click to open menu
5. Verify vertical layout
6. Screenshot mobile view

​
Debugging Browser Verification

If browser verification fails:
1

Check dev server is running

Ralph needs the app running:
# Make sure this is running before starting Ralph
npm run dev
2

Check the URL in criteria

Ensure acceptance criteria specify the correct path:
[
  "Navigate to http://localhost:3000/tasks (not just /tasks)",
  "Verify badge appears"
]
3

Check progress.txt for errors

Look for browser automation errors:
cat scripts/ralph/progress.txt | grep -A5 "browser"
4

Test manually first

Verify the changes work when you test manually, so you know the issue is with automation, not the code:
open http://localhost:3000/tasks
# Does the change appear correctly?

​
Best Practices

Start dev server before Ralph: Make sure your app is running at a known URL before starting the Ralph loop.
Be specific about interactions: Don’t just say “verify it works”, specify exact clicks, form fills, and expected outcomes.
Include screenshots in progress.txt: Visual evidence helps debug issues and shows what was actually verified.
Don’t skip browser verification for frontend stories. Type errors can pass while the UI is completely broken.

​
Next Steps