| name | visual-tester |
| description | Visually test web UIs using Chrome CDP — spot layout issues, interaction bugs, responsive breakage, and produce a structured report |
Visual Tester
Ad-hoc visual QA for web UIs. You use Chrome CDP (scripts/cdp.mjs) to control the browser, take screenshots, inspect accessibility trees, interact with elements, and report what looks wrong.
This is not a formal test suite — it's "let me look at this and check if it's right."
Setup
You interact with the browser via the scripts/cdp.mjs CLI. Read the chrome-cdp skill for the full command reference.
Prerequisites
- Chrome with remote debugging enabled:
chrome://inspect/#remote-debugging → toggle the switch
- The target page open in a Chrome tab
1. Find your target tab
scripts/cdp.mjs list
Pick the target from the list. Use the targetId prefix (e.g. 6BE827FA) for all subsequent commands.
2. Take a screenshot to verify connection
scripts/cdp.mjs shot <target> /tmp/screenshot.png
If you get an image back, you're connected.
3. Get the page structure
scripts/cdp.mjs snap <target>
Taking Screenshots
Standard screenshot
scripts/cdp.mjs shot <target> /tmp/screenshot.png
Captures the viewport. Output includes DPR for coordinate conversion.
Accessibility snapshot (text-only structure)
For text-heavy pages where you need to read content without a screenshot:
scripts/cdp.mjs snap <target>
What to Look For
Layout & Spacing
- Elements not aligned with their siblings
- Inconsistent padding/margins between similar components
- Content touching container edges (missing padding)
- Elements overflowing their containers
- Unexpected scrollbars
Typography
- Text clipped or truncated without ellipsis
- Text overflowing containers
- Font sizes that look wrong relative to hierarchy (h1 smaller than h2, etc.)
- Line height too tight or too loose
- Missing or broken web fonts (fallback serif/sans showing)
Colors & Contrast
- Text hard to read against its background
- Inconsistent color usage (different shades of the "same" color)
- Focus indicators invisible or missing
- Active/hover states using wrong colors
Images & Media
- Broken images (alt text showing, empty boxes)
- Images stretched or squashed (wrong aspect ratio)
- Images not responsive (overflowing on mobile)
- Missing placeholder/loading states
Z-index & Overlapping
- Modals or dropdowns appearing behind other elements
- Fixed headers overlapping content
- Tooltips or popovers clipped by parent overflow
Empty & Edge States
- What does the page look like with no data?
- What about very long text? Very short text?
- Error states — are they styled or raw browser defaults?
- Loading states — spinner, skeleton, or nothing?
Responsive Testing
Test at these breakpoints by changing the viewport via eval:
| Name | Width | Height |
|---|
| Mobile | 375 | 812 |
| Tablet | 768 | 1024 |
| Desktop | 1280 | 800 |
| Wide | 1920 | 1080 |
scripts/cdp.mjs evalraw <target> Emulation.setDeviceMetricsOverride '{"width":375,"height":812,"deviceScaleFactor":2,"mobile":true}'
scripts/cdp.mjs shot <target> /tmp/mobile.png
Reset to default after testing:
scripts/cdp.mjs evalraw <target> Emulation.clearDeviceMetricsOverride
Take a screenshot at each size. Look for:
- Navigation collapsing properly (hamburger menu on mobile)
- Content not overflowing horizontally
- Touch targets large enough on mobile (min 44x44px)
- Text remaining readable at all sizes
- Images scaling appropriately
- No horizontal scrollbar on mobile
You don't always need all four breakpoints. Use judgment — if it's a simple component, mobile + desktop may suffice.
Interaction Testing
Clicking elements
scripts/cdp.mjs click <target> 'button[type="submit"]'
scripts/cdp.mjs shot <target> /tmp/after-click.png
Or click by coordinates (CSS pixels):
scripts/cdp.mjs clickxy <target> 200 350
Always screenshot after actions to verify the result.
Forms
scripts/cdp.mjs click <target> 'input[name="email"]'
scripts/cdp.mjs type <target> 'test@example.com'
scripts/cdp.mjs click <target> 'input[name="password"]'
scripts/cdp.mjs type <target> 'password123'
scripts/cdp.mjs click <target> 'button[type="submit"]'
scripts/cdp.mjs shot <target> /tmp/form-submitted.png
Check: validation messages styled correctly? Success/error states clear?
Hover & Focus States
Use eval to trigger hover/focus for inspection:
scripts/cdp.mjs eval <target> "document.querySelector('button.primary').dispatchEvent(new MouseEvent('mouseover', {bubbles: true}))"
scripts/cdp.mjs shot <target> /tmp/hover.png
Navigation
Click through different routes/pages. Verify:
- Page transitions work
- Active nav item is highlighted
- Back button works
- URL updates correctly
scripts/cdp.mjs nav <target> http://localhost:3000/other-page
scripts/cdp.mjs shot <target> /tmp/other-page.png
Dark Mode / Light Mode
Toggle color scheme emulation via CDP:
scripts/cdp.mjs evalraw <target> Emulation.setEmulatedMedia '{"features":[{"name":"prefers-color-scheme","value":"dark"}]}'
scripts/cdp.mjs shot <target> /tmp/dark-mode.png
scripts/cdp.mjs evalraw <target> Emulation.setEmulatedMedia '{"features":[{"name":"prefers-color-scheme","value":"light"}]}'
scripts/cdp.mjs shot <target> /tmp/light-mode.png
Check:
- All text readable in both modes
- No "white flash" elements that didn't get themed
- Icons and images visible in both modes (not black-on-black or white-on-white)
- Consistent use of theme colors (no hardcoded colors leaking through)
CSS Inspection
When you spot something off, inspect the styles via eval:
scripts/cdp.mjs eval <target> "JSON.stringify(window.getComputedStyle(document.querySelector('.suspect-element')).cssText)"
Or get specific properties:
scripts/cdp.mjs eval <target> "window.getComputedStyle(document.querySelector('.suspect-element')).getPropertyValue('margin-top')"
Report Format
After testing, produce a structured report:
# Visual Test Report
**URL:** http://localhost:3000
**Date:** YYYY-MM-DD
**Viewports tested:** Mobile (375), Desktop (1280)
## Summary
Brief overall impression. Is this ready to ship? Major concerns?
## Findings
### P0 — Blockers (broken functionality, unusable UI)
#### [Finding title]
- **Location:** Page/component/element
- **Description:** What's wrong
- **Expected:** What it should look like/do
- **Suggested fix:** How to fix it
### P1 — Major (significant visual issues, poor UX)
...
### P2 — Minor (cosmetic issues, polish)
...
### P3 — Nits (nice-to-have improvements)
...
## What's Working Well
- List things that look good
- Positive observations help calibrate severity
Severity Guide
| Level | Meaning | Examples |
|---|
| P0 | Broken / unusable | Button doesn't work, page crashes, content invisible |
| P1 | Major visual/UX issue | Layout broken on mobile, text unreadable, form unusable |
| P2 | Noticeable cosmetic issue | Misaligned elements, inconsistent spacing, wrong colors |
| P3 | Polish / nit | Slightly off margins, could-be-better hover states |
Cleanup
Before writing the report, restore the page to its original state. Don't leave the browser in a modified viewport, dark mode, or on a different URL than where you started.
scripts/cdp.mjs evalraw <target> Emulation.clearDeviceMetricsOverride
scripts/cdp.mjs evalraw <target> Emulation.setEmulatedMedia '{"features":[]}'
scripts/cdp.mjs nav <target> <original-url>
Note the original URL at the start of testing.
Tips
