QA Web Testing with Chrome DevTools MCP

Automate visual QA testing of web pages using Chrome DevTools MCP tools. Connects to an already-running Chrome browser session, navigates to pages, emulates viewports, takes screenshots, and inspects CSS properties to catch responsive layout bugs.

Inputs

Raw arguments: $ARGUMENTS

Infer from the arguments:

• TARGET_URL: the URL to test
• OUT_DIR: output directory for QA report and screenshots, or ./qa-reports if not provided

Output Location

• Creates or updates OUT_DIR/qa-report-{timestamp}.md
• Screenshots are saved to OUT_DIR/screenshots/
• Run mkdir -p OUT_DIR/screenshots before writing to ensure directories exist.

Prerequisites

1. Chrome running with remote debugging enabled (or Chrome DevTools MCP server configured)
2. Target page accessible (dev server running, or staging/production URL)
3. If the page requires authentication, attempt to find credentials from environment variables. If none are found or authentication fails, skip the test

Before You Start

After connecting to the browser and navigating to the target URL, always hard-refresh the page and clear the cache before any testing:

// Run via evaluate_script to clear page cache and hard-refresh
caches.keys().then(names => names.forEach(name => caches.delete(name)));
location.reload(true);

Then wait for the page to fully reload before proceeding.

Workflow

Follow these steps in order. Read each step file for detailed instructions.

1. Connect to browser — List pages and navigate to target URL
2. Determine breakpoints — Choose viewport widths to test
3. Emulate and capture — Set viewport, screenshot, inspect dimensions
4. CSS inspection — Inspect computed styles and container queries
5. Visual design inspection — Check typography, color, spacing, borders, and visibility
6. Report results — Summarize findings with pass/fail table

Reference Files

| Reference | When to Read | |-----------|-------------| | references/breakpoints.md | Common breakpoint values, container query vs media query gotchas | | references/css-inspection.md | JS snippets for overflow detection, grid/flex inspection, DOM traversal |