Browser Testing
Verify UI changes by launching a development server, navigating to the relevant pages, and testing interactions with a browser automation tool. This provides visual and interactive verification that complements unit tests. The run is done when the Step 6 results table covers every check the change needs.
When to Use
- After implementing UI changes that need visual verification
- Testing user interaction flows (forms, navigation, modals)
- Verifying responsive layouts at different viewport sizes
- Checking accessibility in a real browser context
- When unit tests pass but you need to confirm the actual user experience
What You Need
A browser automation tool, such as a Playwright MCP server or Claude in Chrome, that can navigate to a URL, take an accessibility snapshot, click and type, and resize the viewport. Steps 2 to 5 use it.
If the host has none, say so at the start: the checks cannot be run here. Still start the dev server if you can (Step 1), then follow "Without a Browser Tool" below instead of Steps 2 to 5.
Process
Step 1: Start the Dev Server
# Start the development server (check CONVENTIONS.md for the correct command)
[dev server command] &
# Wait for it to be ready
# The server should output a URL like http://localhost:3000
If the dev server command isn't known, check:
package.jsonscripts (dev,start,serve)Makefiletargetsdocs/context/CONVENTIONS.md
Step 2: Navigate to the Page
With the browser tool:
- Open the browser and navigate to the relevant URL
- Wait for the page to fully load
- Take an accessibility snapshot to understand the page structure
Step 3: Verify Visual State
Take a snapshot and verify:
- The expected elements are present
- Layout matches expectations
- Text content is correct
- Interactive elements are visible and accessible
Step 4: Test Interactions
For each user flow to test:
- Identify the interactive elements from the snapshot
- Perform the interaction (click, type, select)
- Wait for the expected result
- Take another snapshot to verify the outcome
Common interactions:
- Fill out a form and submit it
- Click navigation links and verify page changes
- Open and close modals/dropdowns
- Test error states (invalid input, network errors)
Step 5: Test Responsive Behavior
If the change involves layout:
- Resize the browser to mobile width (375px)
- Take a snapshot — verify mobile layout
- Resize to tablet width (768px)
- Take a snapshot — verify tablet layout
- Resize back to desktop (1280px)
Step 6: Document Results
### Browser Test Results
**URL tested:** [URL]
**Changes verified:** [what was tested]
| Test | Result | Notes |
|------|--------|-------|
| [interaction/visual check] | Pass/Fail | [details] |
**Screenshots saved:** [paths if applicable]
Close the browser session when you are done, so it does not hold memory and connections the next run needs.
Without a Browser Tool
Give the user the checks to run by hand, built from Steps 2 to 5 for the pages this change touches:
- The URL of each affected page, and the elements and text it should show
- Each interaction to perform (submit a form, follow a link, open and close a modal or dropdown, enter invalid input) and the result to expect
- If the layout changed: the page at 375px (mobile), 768px (tablet) and 1280px (desktop)
- Keyboard navigation through the changed elements, with visible focus
Then fill in the Step 6 table with every row marked "Not run (manual)" rather than Pass, so nobody takes an unverified check as verified.
Quick Reference
| Verification Type | What to Check |
|---|---|
| Visual | Elements present, layout correct, text matches |
| Interactive | Click/type works, form submits, navigation flows |
| Responsive | Mobile/tablet/desktop layouts |
| Accessibility | Keyboard navigation, screen reader compatibility |
| Error states | Invalid input handling, error messages shown |
Common Mistakes
Not waiting for page load — Take a snapshot after navigation to confirm the page is ready before interacting.
Testing only the happy path — Also test error states, empty states, and edge cases (very long text, special characters).
Manual visual checks without snapshots — When a browser tool is available, use accessibility snapshots for programmatic verification. Visual-only checks can't be reproduced or automated later.