---
name: browser-testing
description: Use when you have finished modifying any template, template part, CSS/SCSS, theme.json styles, or any file that affects visual presentation. Also use when the user asks you to check a page in the browser.
---

# Browser Testing

## Overview

After any change that could affect visual output, you MUST verify the result in the browser before considering the task complete. This is not optional.

## When to Use

**ALWAYS after modifying:**
- Templates (`/templates/*.html`)
- Template parts (`/parts/*.html`)
- CSS/SCSS files (`/includes/assets/css/`, block styles)
- `theme.json` (styles, colors, typography, spacing, layout)
- Block editor JS that affects frontend output
- PHP content filters (`/includes/content-filters.php`, etc.)
- Any file where the change would be visible on the frontend

**NOT needed for:**
- Pure PHP logic with no visual output (e.g., redirects, SEO meta tags)
- Build config changes (webpack, package.json scripts)
- Documentation-only changes

## Procedure

### 1. Identify affected pages

Use the Template-to-URL mapping table in CLAUDE.md to find which URL(s) correspond to the file you changed. If the change affects a shared part (header, footer, sidebar), test multiple pages that use it.

### 2. Check if browser MCP tools are available

Try to use Chrome DevTools or Playwright MCP. If neither is available, skip to the **Manual Testing Fallback** section below.

### 3. Ensure MCP is running with certificate flags

The site requires ignoring certificate errors. If the MCP server isn't already running, start it with the correct flag:
- **Chrome DevTools**: `npx chrome-devtools-mcp@latest --accept-insecure-certs`
- **Playwright**: `npx @playwright/mcp@latest --ignore-https-errors`

### 4. Navigate and take a snapshot

Use Chrome DevTools MCP or Playwright MCP to navigate to the affected URL on `https://automattic.com`.

```
navigate_page → take_snapshot (or take_screenshot)
```

### 5. Check for issues

Verify:
- Layout renders correctly (no broken blocks, missing content, overlapping elements)
- Typography and spacing look intentional
- Colors match the design system
- No console errors related to the change

### 6. Test responsive breakpoints

Resize or emulate at minimum:
- **Desktop** (1200px+)
- **Tablet** (768px)
- **Mobile** (375px)

Take screenshots or snapshots at each breakpoint if the change involves layout.

### 7. Report findings

Tell the user what you checked and whether it looks correct. If something is broken, fix it and re-test before claiming completion.

## Manual Testing Fallback

When browser MCP tools are not available, provide the user with a checklist so they can verify manually:

1. List the specific URL(s) to check (from the CLAUDE.md mapping table)
2. Describe what to look for based on the change you made
3. Note any breakpoints worth checking if the change involves layout
4. Ask the user to report back what they see

Do NOT skip this step — even without automated browser testing, the user must still be prompted to verify visually.

## Common Mistakes

- Skipping browser testing because "it's a small CSS change" — small changes can break layouts
- Only checking desktop — responsive issues are the most common problems
- Checking the wrong page — always consult the URL mapping table
- Forgetting shared parts affect multiple pages — a header change needs testing on more than one template

## Browser Testing

### Template → URL Mappings

| Template | URL(s) | Notes |
|---|---|---|
| `404.html` | Any non-existent URL (e.g. `/this-does-not-exist/`) | |
| `category.html` | `/category/company-news/` | |
| `index.html` | `/` (homepage) | |
| `page.html` | `/benefits/`, `/creed/` | Generic page template |
| `search.html` | `/?s=wordpress` | |
| `single-post.html` | Any published blog post from `/news/` | |

All URLs are relative to `https://automattic.com`.