test（测试）

/test - Web E2E Testing Agent

Model: haiku (straightforward test execution)

Command Flags

Flag Handling

On -h or --help:

/test - Web E2E Testing Agent

Usage:
  /test {ID}                         Interactive mode (Playwright MCP)
  /test --ci {ID}                    CI mode, keeps test scripts
  /test --ci --cleanup {ID}          CI mode, deletes scripts after
  /test --ci {ID} "instructions"     CI mode with custom instructions
  /test -h, --help                   Show this help message
  /test -v, --version                Show version

Arguments:
  {ID}    Task ID (number) or task filename (e.g., 001-auth-jwt)

Options:
  --ci        Headless mode using Playwright test runner
  --cleanup   Delete test scripts after completion (with --ci)

Examples:
  /test 1                            # Interactive visual testing
  /test 001-auth-jwt                 # Using task filename
  /test --ci 1                       # CI mode, scripts kept
  /test --ci --cleanup 1             # CI mode, scripts deleted

Next: /document {ID}

On -v or --version: Display:

Workflow Skills v1.4.1
https://github.com/eljun/claude-skills

Prerequisites

Playwright MCP Setup (One-Time)

Interactive mode requires Playwright MCP. No npm install needed - Claude Code handles it automatically.

Setup Steps:

1. Create .mcp.json in your project root (not in .claude/ or subdirectories): {"mcpServers": {"playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}}}
2. Restart Claude Code (required after adding/modifying .mcp.json)
3. Verify MCP is active - you should see mcp__playwright__browser_* tools available

How it works:

• Claude Code reads .mcp.json on startup
• The npx command auto-downloads the package (no manual install)
• MCP server starts automatically and exposes browser control tools
• Tools like mcp__playwright__browser_navigate, mcp__playwright__browser_click become available

Interactive Mode (Default)

Playwright MCP is REQUIRED for interactive mode. Before running tests, verify that mcp__playwright__browser_navigate is available as a tool. If Playwright MCP tools are not available:

1. STOP - Do not proceed with testing
2. Notify the user with this message: Playwright MCP is not configured. Interactive testing requires the MCP server. Add this to your project's.mcp.json: {"mcpServers": {"playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}}} Then restart Claude Code and re-run /test. Alternative: Use CI mode which doesn't require MCP: /test --ci {task-name}
3. Do NOT fall back to curl commands or source code inspection as a substitute for browser testing. This produces misleading test reports.

CI Mode (--ci flag)

Playwright MCP is NOT required for CI mode. CI mode uses the standard Playwright test runner.

Requirements for CI mode:

# Install Playwright as dev dependency (if not already)
npm install -D @playwright/test

# Install browsers (first time only)
npx playwright install

CI mode generates test scripts and runs them with npx playwright test - no MCP server needed.

CRITICAL: Mode-Specific Rules

Interactive Mode (Default) - What NOT To Do

DO NOT generate test script files. Interactive mode uses Playwright MCP tools directly in the conversation - NOT by creating external test files.

Prohibited in Interactive Mode:

• ❌ Creating .ts, .js, or .spec test files (e.g., test-app.ts, e2e-test.js)
• ❌ Creating TEST_REPORT.md, TEST_SUMMARY.txt in project root
• ❌ Creating test-screenshots/ or similar folders in project root
• ❌ Running npx playwright test or similar CLI commands
• ❌ Spawning subagents to run headless tests in background
• ❌ Using "CI/CD style" or "headless mode" testing workflows

Required in Interactive Mode:

• ✅ Use mcp__playwright__browser_* tools directly in conversation
• ✅ Write final report ONLY to docs/testing/{task-name}.md
• ✅ Interactive browser testing where you can see each step
• ✅ Take screenshots using mcp__playwright__browser_take_screenshot (stored in Playwright's temp directory, not project)

CI Mode (--ci flag) - Allowed Actions

CI mode IS allowed to generate test scripts, but must follow these rules:

Allowed in CI Mode:

• ✅ Create test scripts in tests/e2e/{task-name}/ (NOT project root)
• ✅ Run npx playwright test for headless execution
• ✅ Spawn subagents for parallel test execution
• ✅ Generate temporary screenshots during testing

Required in CI Mode:

• ✅ Write final report to docs/testing/{task-name}.md
• ✅ MUST cleanup all temporary artifacts after tests (see Cleanup section)
• ✅ Ask user if they want to keep test scripts for CI pipeline
• ✅ Never leave artifacts in project root

When to Use

Invoke /test {ID} when:

• Task is in "Testing" status in TASKS.md
• Implementation is complete from /implement
• Ready to verify the feature works

Example: /test 1 or /test 001-dashboard-redesign

Task ID Resolution

The {ID} can be:

• Numeric ID: 1, 2, 3 → Looks up in TASKS.md, finds matching task document
• Padded ID: 001, 002 → Same as numeric
• Full filename: 001-dashboard-redesign → Direct file reference

Syntax

/test {ID}                              → Interactive mode (default)
/test --ci {ID}                         → CI mode, keeps scripts (default)
/test --ci --cleanup {ID}               → CI mode, deletes scripts after test
/test --ci {ID} "instructions"          → CI mode with additional test instructions

Examples:

• /test 1 - Interactive visual testing
• /test --ci 2 - Headless CI testing, scripts kept for regression
• /test --ci --cleanup 3 - CI testing, scripts deleted (minor changes)
• /test --ci 4 "test empty cart and full cart" - CI mode with specific scenarios

Flag Reference

CRITICAL: Mode Detection (Execute FIRST)

You MUST execute this decision tree BEFORE doing anything else:

┌─────────────────────────────────────────────────────────────┐
│  STEP 1: Parse the command for --ci flag                    │
└─────────────────────────────────────────────────────────────┘
                           │
           ┌───────────────┴───────────────┐
           │                               │
           ▼                               ▼
   Has --ci flag?                    No --ci flag?
           │                               │
           │                               │
           ▼                               ▼
┌─────────────────────┐      ┌─────────────────────────────────┐
│ MODE = CI           │      │ STEP 2: Check for Playwright MCP │
│ Proceed to CI       │      │ Is mcp__playwright__browser_*    │
│ workflow            │      │ available as a tool?             │
└─────────────────────┘      └─────────────────────────────────┘
                                           │
                             ┌─────────────┴─────────────┐
                             │                           │
                             ▼                           ▼
                      Available?                  NOT Available?
                             │                           │
                             ▼                           ▼
               ┌─────────────────────┐    ┌──────────────────────────┐
               │ MODE = Interactive  │    │ **STOP IMMEDIATELY**     │
               │ Proceed to          │    │                          │
               │ Interactive workflow│    │ Display this message:    │
               └─────────────────────┘    │ "Playwright MCP is not   │
                                          │ configured. See prereqs."│
                                          │                          │
                                          │ DO NOT:                  │
                                          │ - Fall back to CI mode   │
                                          │ - Use curl/source code   │
                                          │ - Proceed with testing   │
                                          └──────────────────────────┘

ABSOLUTE RULES:

1. No --ci flag + No Playwright MCP = STOP. Do not proceed. Do not fall back.
2. No --ci flag + Playwright MCP available = Interactive mode ONLY. Never create test scripts.
3. --ci flag present = CI mode. Playwright MCP not required.

How to check for Playwright MCP: Look for tools starting with mcp__playwright__browser_ in your available tools. If you see tools like mcp__playwright__browser_navigate, mcp__playwright__browser_click, etc., Playwright MCP is available.

Workflow

IMPORTANT: Always execute "Mode Detection" section FIRST before following any workflow below.

Interactive Mode (Default) — REQUIRES Playwright MCP

Entry condition: No --ci flag AND Playwright MCP tools are available.

If Playwright MCP is NOT available: STOP. Do not use this workflow. Do not fall back to CI mode. Notify user to configure Playwright MCP.

/test {task-name}
       ↓
0. [ALREADY DONE] Mode Detection confirmed:
   - No --ci flag
   - Playwright MCP IS available
   - MODE = Interactive (locked in)
       ↓
1. Read task document for requirements
2. Check Automation field (manual | auto)
3. Read implementation for context
4. Create test plan
5. Check if email testing required (see Email Testing section)
   └── If auth keywords found → MUST use Mailinator
6. Execute tests via Playwright MCP tools directly
   ⚠️ DO NOT create test script files
   ⚠️ DO NOT run npx playwright test
   ⚠️ DO NOT spawn subagents for testing
7. If auth flow → Verify email received & confirmation works
8. Write report to docs/testing/{task-name}.md
9. Update TASKS.md with result
       ↓
┌─── Automation Mode? ───┐
│                        │
▼ Manual                 ▼ Auto
PASS → notify user       PASS → invoke /document
FAIL → notify user       FAIL → invoke /implement with test report

CI/CD Mode (--ci flag) — Does NOT require Playwright MCP

Entry condition: --ci flag IS present in the command.

IMPORTANT: This mode is ONLY used when the user explicitly provides the --ci flag. Never auto-switch to this mode when Playwright MCP is unavailable.

/test --ci {task-name}
       ↓
0. [ALREADY DONE] Mode Detection confirmed:
   - --ci flag IS present
   - MODE = CI (locked in)
   - Playwright MCP: not required
       ↓
1. Read task document for requirements
2. Create test directory: tests/e2e/{task-name}/
3. Generate Playwright test script(s)
4. Run tests headlessly via: npx playwright test
5. Capture results and screenshots
6. Write report to docs/testing/{task-name}.md
7. Clean temporary artifacts (keep test scripts by default)
8. Update TASKS.md with result
       ↓
Same automation mode handling as interactive

/test --ci --cleanup {task-name}
       ↓
Same as above, but ALSO deletes tests/e2e/{task-name}/ at step 7

CI Mode Advantages:

• Parallel test execution
• Test scripts kept by default for regression testing
• Faster for large test suites
• Can spawn subagents for concurrent testing
• Accumulated tests run on every future PR

CI Mode: Directory Structure (CRITICAL)

You MUST follow this exact directory structure. Do NOT put files in wrong locations.

project-root/
├── tests/
│   └── e2e/
│       └── {task-name}/           ← Test scripts go HERE (*.spec.ts)
│           ├── {task-name}.spec.ts
│           └── helpers.ts (if needed)
│
├── docs/
│   └── testing/
│       └── {task-name}.md         ← ONLY the final report goes HERE
│
└── (temporary - ALWAYS DELETE)
    ├── TEST_REPORT.md
    ├── TEST_CASES.md
    ├── TEST_SUMMARY.txt
    ├── test_results.md
    ├── test_execution_summary.md
    ├── TEST_REPORT_INDEX.md
    ├── playwright_mcp_test_log.md
    ├── test-screenshots/
    ├── test-results/
    └── playwright-report/

PROHIBITED File Locations

NEVER create these files in docs/testing/:

• ❌ docs/testing/TEST_CASES.md
• ❌ docs/testing/test_results.md
• ❌ docs/testing/test_execution_summary.md
• ❌ docs/testing/TEST_REPORT_INDEX.md
• ❌ docs/testing/playwright_mcp_test_log.md
• ❌ docs/testing/TEST_SUMMARY.txt
• ❌ docs/testing/*.spec.ts (test scripts)

ONLY allowed in docs/testing/:

• ✅ docs/testing/{task-name}.md (final test report, one per task)
• ✅ docs/testing/README.md (if project has one)

CI Mode: Artifact Management

Default Behavior (Scripts Kept)

By default, /test --ci {task-name} keeps test scripts for regression testing:

tests/e2e/{task-name}/     ← KEPT for future regression testing
docs/testing/{task-name}.md ← KEPT as final test report (ONLY file in docs/testing/)

Temporary artifacts are ALWAYS cleaned (run at end of every CI test):

# Remove from project root
rm -f TEST_REPORT.md TEST_SUMMARY.txt TEST_CASES.md
rm -f test_results.md test_execution_summary.md TEST_REPORT_INDEX.md
rm -f playwright_mcp_test_log.md
rm -rf test-screenshots/ test-results/ playwright-report/
rm -f test-*.ts test-*.js *.spec.ts  # Root-level scripts

# Remove from docs/testing/ (ONLY final report should remain)
rm -f docs/testing/TEST_CASES.md
rm -f docs/testing/test_results.md
rm -f docs/testing/test_execution_summary.md
rm -f docs/testing/TEST_REPORT_INDEX.md
rm -f docs/testing/playwright_mcp_test_log.md
rm -f docs/testing/TEST_SUMMARY.txt
rm -f docs/testing/*.spec.ts

With --cleanup Flag (Scripts Deleted)

When using /test --ci --cleanup {task-name}, test scripts are also deleted:

# Additional cleanup with --cleanup flag
rm -rf tests/e2e/{task-name}/

# Clean empty parent directories
rmdir tests/e2e 2>/dev/null || true
rmdir tests 2>/dev/null || true

Artifact Summary

Why Keep Scripts by Default?

Feature A: /test --ci auth-flow
  → tests/e2e/auth-flow/ KEPT

Feature B: /test --ci checkout
  → tests/e2e/checkout/ KEPT

Future PR touches auth code:
  → npx playwright test runs BOTH
  → Catches if new code breaks auth ✅

Safe by default - scripts accumulate for regression protection. Use --cleanup only for minor, one-time verifications.

Auto Mode Behavior

When task document has Automation: auto:

On PASS

Use Task tool to spawn document agent with model: haiku:

[AUTO] Tests PASSED. Spawning /document with haiku model...

Task({subagent_type: "general-purpose", model: "haiku", prompt: "/document {ID}"})

On FAIL

Use Task tool to spawn implement agent with model: opus (needs advanced reasoning to fix issues):

[AUTO] Tests FAILED. Spawning /implement with opus model for fixes...

Issues found:
1. {Issue summary}
2. {Issue summary}

Re-running implementation with fixes...

Task({subagent_type: "general-purpose", model: "opus", prompt: "/implement {ID} - Fix issues from test report: {summary}"})

Note: The implement skill will receive the test report context and should focus on fixing the specific issues identified. After fixes, it will chain back to /test (with haiku).

IMPORTANT: For any task involving registration, login, magic links, or email verification:

• The test is NOT complete until email confirmation is verified via Mailinator
• See "Email-Based Authentication Testing" section for detailed steps

Pre-Testing Setup

1. Read the Task Document (Primary Context Source)

docs/task/{ID}-{task-name}.md

IMPORTANT — Context Efficiency: The task document contains all the context you need from the planning phase. Do NOT perform broad codebase exploration. Only read the specific files referenced in the task document.

Focus on:

• Requirements checklist
• Testing checklist (if provided)
• Expected behavior
• Files that were modified (listed in the task document)

2. Understand the Implementation

Review only the files that were changed (as listed in the task document):

• What was created?
• What was modified?
• What are the entry points?

DO NOT scan the entire codebase or read unrelated files. The task document already provides the necessary context.

3. Identify Test Scenarios

Create a test plan covering:

• Happy path (main use case)
• Edge cases
• Error handling
• Cross-platform (if applicable)

4. Detect If Email Testing Is Required

CRITICAL: Scan the task document for these keywords:

• Registration / Sign up / Create account
• Magic Link / OTP / Email verification
• Email confirmation / Confirm email
• Password reset / Forgot password
• Account activation

If ANY of these keywords appear:

1. MANDATORY - Use Mailinator for email testing (see "Email-Based Authentication Testing" section below)
2. DO NOT mark the test as PASS without verifying:

- Email was received in Mailinator inbox - Confirmation/verification link works - Post-confirmation redirect is correct

1. Include "Authentication Tests" section in test report

Example detection:

Task doc says: "Magic Link authentication as primary signup method"
→ This REQUIRES email testing via Mailinator
→ Test is NOT complete until email verification is confirmed

Testing with Playwright MCP

Available Tools

Use the Playwright MCP tools for browser automation:

mcp__playwright__browser_navigate    - Go to URL
mcp__playwright__browser_snapshot    - Capture accessibility snapshot
mcp__playwright__browser_click       - Click elements
mcp__playwright__browser_type        - Type text
mcp__playwright__browser_fill_form   - Fill form fields
mcp__playwright__browser_take_screenshot - Capture screenshot
mcp__playwright__browser_console_messages - Check console
mcp__playwright__browser_network_requests - Check network
mcp__playwright__browser_wait_for    - Wait for conditions

Test Execution Pattern

// 1. Navigate to the page
mcp__playwright__browser_navigate({ url: "http://localhost:3000/path" })

// 2. Take snapshot to understand page structure
mcp__playwright__browser_snapshot()

// 3. Interact with elements (use ref from snapshot)
mcp__playwright__browser_click({ ref: "button[Submit]", element: "Submit button" })

// 4. Verify results
mcp__playwright__browser_snapshot()

// 5. Check for errors
mcp__playwright__browser_console_messages({ level: "error" })

Responsive Testing

For responsive web features, resize the viewport:

mcp__playwright__browser_resize({ width: 390, height: 844 }) // iPhone 14 Pro
mcp__playwright__browser_resize({ width: 768, height: 1024 }) // iPad

Test Report Template

Create report in docs/testing/{ID}-{task-name}.md:

# Test Report: {Task Name}

> **Task ID:** {ID}
> **Status:** PASS | FAIL | PARTIAL
> **Tested:** {Date}
> **Task Doc:** [link](../task/{ID}-{task-name}.md)

## Summary

{1-2 sentence summary of test results}

## Test Environment

- Platform: Web
- Browser: Chromium (Playwright)
- Base URL: http://localhost:3000
- Viewport: {dimensions if relevant}

## Test Results

### Requirement Tests

| # | Requirement | Status | Notes |
|---|-------------|--------|-------|
| 1 | {Requirement from task doc} | PASS/FAIL | {Details} |
| 2 | {Requirement} | PASS/FAIL | {Details} |

### Functional Tests

#### Test 1: {Test Name}
**Steps:**
1. Navigate to {page}
2. Click {element}
3. Verify {expected result}

**Result:** PASS/FAIL
**Evidence:** {Screenshot or description}

#### Test 2: {Test Name}
{Same format}

### Edge Cases

| Case | Result | Notes |
|------|--------|-------|
| Empty state | PASS/FAIL | {Details} |
| Error handling | PASS/FAIL | {Details} |
| Loading state | PASS/FAIL | {Details} |

### Console Errors

{Any console errors found, or "None"}

### Network Issues

{Any failed requests, or "None"}

## Issues Found

### Issue 1: {Title}
**Severity:** Critical | Major | Minor
**Description:** {What's wrong}
**Steps to Reproduce:**
1. Step 1
2. Step 2
**Expected:** {What should happen}
**Actual:** {What actually happens}
**Screenshot:** {If applicable}

### Issue 2: {Title}
{Same format}

## Screenshots

{Include relevant screenshots}

## Recommendations

{Any suggestions for fixes or improvements}

## Verdict

**PASS** - All requirements met, ready for documentation
OR
**FAIL** - Issues found, needs fixes (see Issues section)
OR
**PARTIAL** - Core functionality works, minor issues noted

Update TASKS.md

If PASS

Move to "Approved" section (pending user approval):

## Testing

| ID | Task | Task Doc | Test Report | Status |
|----|------|----------|-------------|--------|
| 1 | Quick Actions Redesign | [001-quick-actions.md](...) | [001-quick-actions.md](docs/testing/001-quick-actions.md) | PASS - Awaiting approval |

If FAIL

Keep in "Testing" with failure note:

## Testing

| ID | Task | Task Doc | Test Report | Status |
|----|------|----------|-------------|--------|
| 1 | Quick Actions Redesign | [001-quick-actions.md](...) | [001-quick-actions.md](docs/testing/001-quick-actions.md) | FAIL - See report |

Handoff

Check the task document for Automation: auto field.

Manual Mode

On PASS

Testing complete: #{ID} - {Task Title}

Result: PASS
Test Report: docs/testing/{ID}-{task-name}.md

All requirements verified. Ready for your approval.

Next Steps (after approval):
  /document {ID}              # e.g., /document 1
  /document {ID}-{task-name}  # e.g., /document 001-auth-jwt

On FAIL

Testing complete: #{ID} - {Task Title}

Result: FAIL
Test Report: docs/testing/{ID}-{task-name}.md

Issues found:
1. {Issue summary 1}
2. {Issue summary 2}

Next Steps (fix and re-test):
  /implement {ID}             # e.g., /implement 1
  /implement {ID}-{task-name} # e.g., /implement 001-auth-jwt

Then re-run:
  /test {ID}

Auto Mode

On PASS

Testing complete: #{ID} - {Task Title}

Result: PASS
Test Report: docs/testing/{ID}-{task-name}.md

[AUTO] Spawning /document with haiku model...

Use Task tool: Task({subagent_type: "general-purpose", model: "haiku", prompt: "/document {ID}"})

On FAIL

Testing complete: #{ID} - {Task Title}

Result: FAIL
Test Report: docs/testing/{ID}-{task-name}.md

Issues found:
1. {Issue summary 1}
2. {Issue summary 2}

[AUTO] Spawning /implement with opus model for fixes...

Use Task tool: Task({subagent_type: "general-purpose", model: "opus", prompt: "/implement {ID} - Fix: {issue summaries}"})

Email-Based Authentication Testing

For testing account registration, email verification, password reset, and email notifications using temporary email services.

CRITICAL: Tests involving email verification, account activation, password reset, or any email-dependent flow MUST NOT be marked as PASS until the email verification is confirmed working. If email testing fails due to service limits, mark the test as BLOCKED and notify the user to take action.

Supported Email Services (Priority Order)

Always start with Mail.tm. Only fall back to other services if Mail.tm returns rate limit errors (HTTP 429) or account creation fails.

Email Testing Workflow

1. Create temporary email via Mail.tm API
2. Navigate to registration/action page
3. Fill form with temporary email
4. Poll Mail.tm API for incoming email
5. Extract verification link from email
6. Complete verification flow
7. Verify account is active
8. Include email test results in report

Mail.tm API Reference (Primary Service)

Mail.tm provides a REST API for creating temporary emails and retrieving messages.

Base URL: https://api.mail.tm

Step 1: Get Available Domain

# Get list of available domains
curl https://api.mail.tm/domains

# Response example:
# { "hydra:member": [{ "id": "...", "domain": "mail.tm" }] }

Step 2: Create Temporary Account

# Create account with random address
curl -X POST https://api.mail.tm/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "address": "test-1706234567890@mail.tm",
    "password": "TestPassword123!"
  }'

# Response: { "id": "...", "address": "test-...@mail.tm" }

Step 3: Get Authentication Token

# Get JWT token for API access
curl -X POST https://api.mail.tm/token \
  -H "Content-Type: application/json" \
  -d '{
    "address": "test-1706234567890@mail.tm",
    "password": "TestPassword123!"
  }'

# Response: { "token": "eyJ..." }

Step 4: Poll for Messages

# Check inbox (poll every 3-5 seconds)
curl https://api.mail.tm/messages \
  -H "Authorization: Bearer {token}"

# Response: { "hydra:member": [{ "id": "...", "subject": "...", "from": {...} }] }

Step 5: Get Message Content

# Get full message with HTML content
curl https://api.mail.tm/messages/{messageId} \
  -H "Authorization: Bearer {token}"

# Response includes: { "html": "<html>...", "text": "..." }
# Extract verification link from html or text field

Step-by-Step: Account Registration Test

Step 1: Create Mail.tm Account via Bash

# Generate unique email address
TIMESTAMP=$(date +%s)
RANDOM_STR=$(head /dev/urandom | tr -dc a-z0-9 | head -c 4)
TEST_EMAIL="test-${TIMESTAMP}-${RANDOM_STR}@mail.tm"
TEST_PASSWORD="TestPassword123!"

# Get available domain (verify mail.tm is available)
curl -s https://api.mail.tm/domains | jq '.["hydra:member"][0].domain'

# Create the temporary email account
curl -s -X POST https://api.mail.tm/accounts \
  -H "Content-Type: application/json" \
  -d "{\"address\": \"${TEST_EMAIL}\", \"password\": \"${TEST_PASSWORD}\"}"

# Get authentication token
TOKEN=$(curl -s -X POST https://api.mail.tm/token \
  -H "Content-Type: application/json" \
  -d "{\"address\": \"${TEST_EMAIL}\", \"password\": \"${TEST_PASSWORD}\"}" \
  | jq -r '.token')

echo "Test email: ${TEST_EMAIL}"
echo "Token: ${TOKEN}"

Step 2: Navigate to Registration Page

mcp__playwright__browser_navigate({ url: "http://localhost:3000/register" })
mcp__playwright__browser_snapshot()

Step 3: Fill Registration Form

// Get element refs from snapshot, then fill form
// Use the TEST_EMAIL created in Step 1
mcp__playwright__browser_fill_form({
  fields: [
    { name: "Email", type: "textbox", ref: "input[email]", value: TEST_EMAIL },
    { name: "Password", type: "textbox", ref: "input[password]", value: "TestPassword123!" },
    { name: "Confirm Password", type: "textbox", ref: "input[confirmPassword]", value: "TestPassword123!" }
  ]
})
mcp__playwright__browser_click({ ref: "button[Submit]", element: "Submit button" })

Step 4: Poll Mail.tm for Verification Email

# Poll for messages (repeat every 5 seconds, up to 60 seconds)
for i in {1..12}; do
  MESSAGES=$(curl -s https://api.mail.tm/messages \
    -H "Authorization: Bearer ${TOKEN}")

  COUNT=$(echo $MESSAGES | jq '.["hydra:member"] | length')

  if [ "$COUNT" -gt "0" ]; then
    echo "Email received!"
    MESSAGE_ID=$(echo $MESSAGES | jq -r '.["hydra:member"][0].id')
    break
  fi

  echo "Waiting for email... attempt $i/12"
  sleep 5
done

Step 5: Extract Verification Link

# Get full message content
MESSAGE=$(curl -s https://api.mail.tm/messages/${MESSAGE_ID} \
  -H "Authorization: Bearer ${TOKEN}")

# Extract verification link from HTML content
# Adjust the grep pattern based on your auth provider
VERIFY_LINK=$(echo $MESSAGE | jq -r '.html' | grep -oP 'href="\K[^"]*confirm[^"]*' | head -1)

# Or from text content
VERIFY_LINK=$(echo $MESSAGE | jq -r '.text' | grep -oP 'https?://[^\s]*confirm[^\s]*' | head -1)

echo "Verification link: ${VERIFY_LINK}"

Step 6: Complete Verification

// Navigate to the verification link
mcp__playwright__browser_navigate({ url: VERIFY_LINK })
mcp__playwright__browser_snapshot()
// Should see success message or redirect to dashboard

Password Reset Testing

# 1. Use the same Mail.tm account created earlier
# 2. Trigger password reset in the app
# 3. Poll for reset email
MESSAGES=$(curl -s https://api.mail.tm/messages \
  -H "Authorization: Bearer ${TOKEN}")

MESSAGE_ID=$(echo $MESSAGES | jq -r '.["hydra:member"][0].id')

# 4. Extract reset link
MESSAGE=$(curl -s https://api.mail.tm/messages/${MESSAGE_ID} \
  -H "Authorization: Bearer ${TOKEN}")

RESET_LINK=$(echo $MESSAGE | jq -r '.html' | grep -oP 'href="\K[^"]*reset[^"]*' | head -1)

Email Notification Testing

For testing transactional emails (booking confirmations, notifications, etc.):

# 1. Trigger the action that sends email (e.g., make a booking via Playwright)
# 2. Poll Mail.tm for notification (may take longer)
for i in {1..24}; do  # Up to 2 minutes
  MESSAGES=$(curl -s https://api.mail.tm/messages \
    -H "Authorization: Bearer ${TOKEN}")

  # Look for specific subject
  NOTIFICATION=$(echo $MESSAGES | jq -r '.["hydra:member"][] | select(.subject | contains("Booking"))')

  if [ -n "$NOTIFICATION" ]; then
    echo "Notification received!"
    break
  fi

  sleep 5
done

# 3. Verify email content
MESSAGE_ID=$(echo $NOTIFICATION | jq -r '.id')
MESSAGE=$(curl -s https://api.mail.tm/messages/${MESSAGE_ID} \
  -H "Authorization: Bearer ${TOKEN}")

# Validate content
echo $MESSAGE | jq '.html' | grep -q "booking details" && echo "Content valid"

Fallback: When Mail.tm Hits Rate Limits

If Mail.tm returns HTTP 429 (Too Many Requests) or account creation fails:

Fallback to Mailinator (Browser-based)

// Generate Mailinator email (no account creation needed)
const testEmail = `test-${Date.now()}@mailinator.com`;
const inboxName = testEmail.split('@')[0];

// After triggering email, navigate to inbox
mcp__playwright__browser_navigate({
  url: `https://www.mailinator.com/v4/public/inboxes.jsp?to=${inboxName}`
})
mcp__playwright__browser_wait_for({ time: 10 })
mcp__playwright__browser_snapshot()

// Click on email row and extract link
mcp__playwright__browser_click({ ref: "row[YourApp]", element: "Email from app" })
mcp__playwright__browser_snapshot()

Fallback to Guerrilla Mail (Browser-based)

// Navigate to Guerrilla Mail
mcp__playwright__browser_navigate({ url: "https://www.guerrillamail.com/" })
mcp__playwright__browser_snapshot()

// Get the generated email address from the page
// Use this address for registration
// Check inbox on the same page for incoming emails

Troubleshooting

When to Mark Test as BLOCKED

Mark the test as BLOCKED (not FAIL) when:

• All email services are rate-limited
• Cannot create temporary email account
• Email never arrives after 2+ minutes across multiple services

**Result:** BLOCKED
**Reason:** Email service rate limits reached
**Action Required:** User must manually verify email flow or wait for rate limits to reset

Test Report: Email Authentication Section

Add to test report when testing auth flows:

### Authentication Tests

| Test | Email Service | Email Used | Result | Notes |
|------|---------------|------------|--------|-------|
| Registration | Mail.tm | test-xxx@mail.tm | PASS/FAIL/BLOCKED | {Details} |
| Email verification | Mail.tm | (same) | PASS/FAIL/BLOCKED | Link received in Xs |
| Password reset | Mail.tm | (same) | PASS/FAIL/BLOCKED | {Details} |
| Login after verify | - | (same) | PASS/FAIL | {Details} |

### Email Delivery

| Email Type | Service Used | Received | Time | Content Valid |
|------------|--------------|----------|------|---------------|
| Verification | Mail.tm | Yes/No | Xs | Yes/No |
| Password Reset | Mail.tm | Yes/No | Xs | Yes/No |
| Booking Confirm | Mail.tm | Yes/No | Xs | Yes/No |

### Service Fallback Log (if applicable)

| Attempt | Service | Result | Error |
|---------|---------|--------|-------|
| 1 | Mail.tm | Failed | 429 Too Many Requests |
| 2 | Mailinator | Success | - |

Manual Testing Guidance

For features that can't be fully automated:

What to Test Manually

• Complex user interactions
• Visual design accuracy
• Animation smoothness

Document Manual Tests

Include in report:

## Manual Testing Required

| Test | Instructions | Expected Result |
|------|--------------|-----------------|
| Visual accuracy | Compare to design | Matches mockup |
| Animation | Trigger X action | Smooth 60fps |

Related Skills

Recommended Plugins (Install Separately)

These plugins must be installed separately. Once installed, they MUST be invoked — do not skip them: