dev-test-playwright

Announce: "I'm using dev-test-playwright for headless browser automation."

## Gate Reminder

Before taking screenshots or running E2E tests, you MUST complete all 6 gates from dev-tdd:

GATE 1: BUILD
GATE 2: LAUNCH (with file-based logging)
GATE 3: WAIT
GATE 4: CHECK PROCESS
GATE 5: READ LOGS ← MANDATORY, CANNOT SKIP
GATE 6: VERIFY LOGS
THEN: E2E tests/screenshots

You loaded dev-tdd earlier. Follow the gates now.

Contents

• Tool Availability Gate
• When to Use Playwright MCP
• MCP Tools Overview
• Navigation
• Element Interaction
• Verification
• Form Handling
• Advanced Patterns
• Complete E2E Examples

Playwright MCP Browser Automation

## Tool Availability Gate

Verify Playwright MCP tools are available before proceeding.

Check for these MCP functions:

• mcp__playwright__browser_navigate
• mcp__playwright__browser_snapshot
• mcp__playwright__browser_click

If MCP tools are not available:

STOP: Cannot proceed with Playwright automation.

Missing: Playwright MCP server

The Playwright MCP server must be configured and running.
Check your Claude Code MCP configuration.

Reply when configured and I'll continue testing.

This gate is non-negotiable. Missing tools = full stop.

## When to Use Playwright MCP

USE Playwright MCP when you need:

• Headless browser automation (CI/CD)
• Cross-browser testing (Chromium, Firefox, WebKit)
• Test isolation (fresh browser state per test)
• Standard E2E test suite automation
• Network mocking/interception
• Parallel test execution

DO NOT use Playwright MCP when:

• Debugging console messages (use Chrome MCP)
• Inspecting network requests/responses (use Chrome MCP)
• Executing custom JavaScript in page (use Chrome MCP)
• Recording GIFs of interactions (use Chrome MCP)
• Interactive debugging with real browser (use Chrome MCP)

For debugging, discover and read the Chrome MCP skill: Read ${CLAUDE_SKILL_DIR}/../../skills/dev-test-chrome/SKILL.md and follow its instructions.

Playwright Facts

• Playwright MCP cannot read console messages or network requests, and that capability cannot be bolted on later — if console/network debugging may be needed, start with Chrome MCP. Chrome MCP in turn requires a visible browser, so headless CI/CD requires Playwright. Choosing by familiarity instead of by these constraints (see Capability Comparison below) produces a test that cannot observe what it claims to verify.

Capability Comparison

Capability	Playwright MCP	Chrome MCP
Navigate/click/type	✅	✅
Accessibility tree	✅ browser_snapshot	✅ read_page
Screenshots	✅	✅
Headless mode	✅	❌
Cross-browser	✅	❌
Console messages	❌	✅
Network requests	❌	✅
JavaScript execution	❌	✅
GIF recording	❌	✅

MCP Tools Overview

Tool	Purpose
browser_navigate	Navigate to URL
browser_snapshot	Get accessibility tree (page state)
browser_click	Click elements
browser_type	Type into inputs
browser_select_option	Select dropdown options
browser_hover	Hover over elements
browser_wait_for	Wait for conditions
browser_take_screenshot	Visual capture
browser_press	Press keys

Navigation

Basic Navigation

mcp__playwright__browser_navigate(url="https://example.com")

Wait for Page Load

mcp__playwright__browser_navigate(url="https://example.com")
mcp__playwright__browser_wait_for(state="networkidle")

Get Current State

mcp__playwright__browser_snapshot()

The snapshot returns the accessibility tree - a structured representation of all interactive elements on the page.

Element Interaction

Clicking Elements

# By visible text
mcp__playwright__browser_click(element="Submit button")

# By ref (from snapshot)
mcp__playwright__browser_click(ref="button[type=submit]")

# By role and name
mcp__playwright__browser_click(element="Login", role="button")

Typing Text

# Into focused element
mcp__playwright__browser_type(text="hello world")

# Into specific element
mcp__playwright__browser_click(element="Email input")
mcp__playwright__browser_type(text="user@example.com")

# Clear and type
mcp__playwright__browser_click(element="Search box")
mcp__playwright__browser_type(text="new search", clear=true)

Keyboard Shortcuts

# Press Enter
mcp__playwright__browser_press(key="Enter")

# Keyboard shortcuts
mcp__playwright__browser_press(key="Control+a")
mcp__playwright__browser_press(key="Control+c")

Verification

### The Iron Law of Verification

EVERY action must be VERIFIED. Taking action is not enough.

After clicking, typing, or navigating, you MUST:

1. Wait for the expected result
2. Take a snapshot to verify state
3. Document the verification in LEARNINGS.md

Action	Verification
Click submit	wait_for(text="Success") + snapshot
Navigate	wait_for(state="networkidle") + snapshot
Fill form	Snapshot shows filled values
Login	Snapshot shows dashboard/logged-in state

"I clicked it" is not verification. Prove the click worked.

Snapshot Verification

# 1. Perform action
mcp__playwright__browser_click(element="Submit")

# 2. Wait for result
mcp__playwright__browser_wait_for(text="Success")

# 3. Take snapshot to verify
mcp__playwright__browser_snapshot()
# Check snapshot contains expected elements

Wait Conditions

# Wait for text to appear
mcp__playwright__browser_wait_for(text="Welcome back")

# Wait for element
mcp__playwright__browser_wait_for(selector="#success-message")

# Wait for network idle
mcp__playwright__browser_wait_for(state="networkidle")

# Wait for navigation
mcp__playwright__browser_wait_for(state="load")

Screenshots

# Full page
mcp__playwright__browser_take_screenshot(path="/tmp/screenshot.png", fullPage=true)

# Viewport only
mcp__playwright__browser_take_screenshot(path="/tmp/viewport.png")

# Specific element
mcp__playwright__browser_take_screenshot(
    path="/tmp/element.png",
    selector="#main-content"
)

Form Handling

Text Inputs

mcp__playwright__browser_click(element="Username")
mcp__playwright__browser_type(text="john_doe")

mcp__playwright__browser_click(element="Password")
mcp__playwright__browser_type(text="secret123")

Dropdowns

mcp__playwright__browser_select_option(
    element="Country dropdown",
    value="US"
)

# Or by label
mcp__playwright__browser_select_option(
    element="Country",
    label="United States"
)

Checkboxes and Radio Buttons

# Check checkbox
mcp__playwright__browser_click(element="Accept terms checkbox")

# Verify checked state (via snapshot)
mcp__playwright__browser_snapshot()
# Look for checked="true" in accessibility tree

File Upload

mcp__playwright__browser_set_input_files(
    selector="input[type=file]",
    files=["/path/to/file.pdf"]
)

Advanced Patterns

Multi-Step Form

# Step 1
mcp__playwright__browser_click(element="Name input")
mcp__playwright__browser_type(text="John Doe")
mcp__playwright__browser_click(element="Next button")
mcp__playwright__browser_wait_for(text="Step 2")

# Step 2
mcp__playwright__browser_click(element="Email input")
mcp__playwright__browser_type(text="john@example.com")
mcp__playwright__browser_click(element="Next button")
mcp__playwright__browser_wait_for(text="Step 3")

# Step 3 - Submit
mcp__playwright__browser_click(element="Submit button")
mcp__playwright__browser_wait_for(text="Success")

Handling Modals

# Click to open modal
mcp__playwright__browser_click(element="Open Dialog")
mcp__playwright__browser_wait_for(text="Dialog Title")

# Interact with modal
mcp__playwright__browser_click(element="Confirm button")
mcp__playwright__browser_wait_for(state="hidden", selector=".modal")

Iframes

# Switch to iframe
mcp__playwright__browser_frame(name="payment-iframe")

# Interact within iframe
mcp__playwright__browser_click(element="Card number")
mcp__playwright__browser_type(text="4111111111111111")

# Switch back to main
mcp__playwright__browser_main_frame()

Hover and Tooltips

mcp__playwright__browser_hover(element="Help icon")
mcp__playwright__browser_wait_for(text="This is the tooltip text")
mcp__playwright__browser_snapshot()

Complete E2E Examples

Login Flow

# 1. Navigate to login page
mcp__playwright__browser_navigate(url="https://app.example.com/login")
mcp__playwright__browser_wait_for(state="networkidle")

# 2. Take initial snapshot
mcp__playwright__browser_snapshot()
# Verify: Login form is visible

# 3. Fill credentials
mcp__playwright__browser_click(element="Email")
mcp__playwright__browser_type(text="user@example.com")

mcp__playwright__browser_click(element="Password")
mcp__playwright__browser_type(text="password123")

# 4. Submit
mcp__playwright__browser_click(element="Sign In")
mcp__playwright__browser_wait_for(text="Dashboard")

# 5. Verify success
mcp__playwright__browser_snapshot()
# Verify: Dashboard is visible, user name shown

# 6. Screenshot for evidence
mcp__playwright__browser_take_screenshot(path="/tmp/login_success.png")

E-Commerce Checkout

# 1. Navigate to product
mcp__playwright__browser_navigate(url="https://shop.example.com/product/123")
mcp__playwright__browser_wait_for(state="networkidle")

# 2. Add to cart
mcp__playwright__browser_click(element="Add to Cart")
mcp__playwright__browser_wait_for(text="Added to cart")

# 3. Go to cart
mcp__playwright__browser_click(element="Cart icon")
mcp__playwright__browser_wait_for(text="Your Cart")

# 4. Verify cart
mcp__playwright__browser_snapshot()
# Verify: Product in cart, correct price

# 5. Proceed to checkout
mcp__playwright__browser_click(element="Checkout")
mcp__playwright__browser_wait_for(text="Shipping Address")

# 6. Fill shipping
mcp__playwright__browser_click(element="Address")
mcp__playwright__browser_type(text="123 Main St")

mcp__playwright__browser_click(element="City")
mcp__playwright__browser_type(text="New York")

mcp__playwright__browser_select_option(element="State", value="NY")

mcp__playwright__browser_click(element="Zip")
mcp__playwright__browser_type(text="10001")

# 7. Continue to payment
mcp__playwright__browser_click(element="Continue to Payment")
mcp__playwright__browser_wait_for(text="Payment Method")

# 8. Verify order summary
mcp__playwright__browser_snapshot()
# Verify: Correct items, shipping address, total

mcp__playwright__browser_take_screenshot(path="/tmp/checkout_complete.png")

Search and Filter

# 1. Navigate
mcp__playwright__browser_navigate(url="https://search.example.com")

# 2. Search
mcp__playwright__browser_click(element="Search box")
mcp__playwright__browser_type(text="laptop")
mcp__playwright__browser_press(key="Enter")
mcp__playwright__browser_wait_for(text="results")

# 3. Apply filter
mcp__playwright__browser_click(element="Price filter")
mcp__playwright__browser_click(element="Under $1000")
mcp__playwright__browser_wait_for(state="networkidle")

# 4. Verify filtered results
mcp__playwright__browser_snapshot()
# Verify: Results shown, filter applied

# 5. Click first result
mcp__playwright__browser_click(element="First product link")
mcp__playwright__browser_wait_for(text="Product Details")

mcp__playwright__browser_take_screenshot(path="/tmp/search_result.png")

Error Handling

Retry Pattern

# Attempt action with retry
for attempt in range(3):
    try:
        mcp__playwright__browser_click(element="Flaky Button")
        mcp__playwright__browser_wait_for(text="Success", timeout=5000)
        break  # Success
    except:
        if attempt == 2:
            raise  # Give up after 3 attempts
        time.sleep(1)  # Wait before retry

Timeout Handling

# Set explicit timeout
mcp__playwright__browser_wait_for(
    text="Slow loading content",
    timeout=30000  # 30 seconds
)

Limitations

### What Playwright MCP Cannot Do

Need	Why Playwright Fails	Use Instead
Read console.log	No console access	Chrome MCP read_console_messages
Inspect API responses	No network access	Chrome MCP read_network_requests
Execute page JavaScript	No JS execution	Chrome MCP javascript_tool
Record GIF	No recording capability	Chrome MCP gif_creator

If you need debugging capabilities, switch to Chrome MCP.

Integration

This skill is referenced by dev-test for Playwright browser automation.

Related skills:

• Read ${CLAUDE_SKILL_DIR}/../../skills/dev-test-chrome/SKILL.md and follow its instructions.
• Read ${CLAUDE_SKILL_DIR}/../../skills/dev-tdd/SKILL.md and follow its instructions.
• Chrome MCP skill - debugging (console/network)
• TDD skill - TDD protocol