test-web-ui（测试网页用户界面）

Web Tester Skill

Transforms any website or project into a structured QA run: Discover → Plan → Execute → Report

Overview of Phases

Phase 1 → DISCOVERY   : Explore the site, understand its purpose and features
Phase 2 → USE CASES   : Generate end-user use case list
Phase 3 → TEST PLAN   : Convert use cases into concrete, executable test cases
Phase 4 → EXECUTION   : Run tests with Playwright, capture screenshots
Phase 5 → REPORT      : Compile HTML + Markdown report with all results

Choosing Your Execution Tool

Pick the first option that works in your environment:

Option 1: Playwright MCP Tools (recommended)

If Playwright MCP tools are available (e.g., mcp__plugin_playwright_playwright__*), use them — they are the fastest and most token-efficient option (~2.8x faster than CLI, fewer tool calls needed since each MCP call does more work):

browser_navigate → navigate to URL
browser_snapshot → get page state and element refs
browser_take_screenshot → capture screenshots
browser_click → click elements
browser_type → type into inputs
browser_evaluate → run JS assertions
browser_resize → test mobile viewports
browser_console_messages → check for JS errors

Option 2: Playwright CLI

The @playwright/cli is a CLI designed for coding agents. Use it when MCP tools are not available. Install if needed:

npm install -g @playwright/cli@latest

Key commands for QA testing:

# Open a page
playwright-cli open https://example.com

# Take a snapshot (returns element refs for interaction)
playwright-cli snapshot

# Screenshot the page
playwright-cli screenshot

# Click, fill forms, type
playwright-cli click <ref>
playwright-cli fill <ref> "text value"
playwright-cli type "search query"
playwright-cli press Enter

# Mobile viewport testing — use a named session with mobile config
playwright-cli -s=mobile open https://example.com
# (configure viewport in .playwright/cli.config.json)

# Check console errors via snapshot output
playwright-cli snapshot

# Close when done
playwright-cli close

Playwright CLI is headless by default. Add --headed to watch the browser visually. Use playwright-cli show to open a dashboard of all active sessions.

Option 3: Python Playwright Scripts

If Python and Playwright are installed, use the bundled scripts in scripts/:

# Install if needed
pip install playwright && playwright install chromium

# Run discovery
python scripts/discover.py --url <URL> --output discovery.json

# Run tests
python scripts/run_tests.py --url <URL> --test-plan test_plan.json --output test_results/

# Generate report
python scripts/generate_report.py --results test_results/results.json --output qa_report.html

Option 4: Manual Testing

If none of the above are available, read the source code directly and perform manual analysis. Use curl or fetch for basic HTTP checks.

Phase 1: Discovery

What to gather

• URL — if the user provides a live URL, navigate to it and explore
• Project files — if no live URL, inspect source files in the project directory
• Purpose — what does the site do? (landing page, e-commerce, dashboard, blog, etc.)
• Key pages — home, auth, main feature pages, forms, checkout, etc.
• Tech stack — optional but helpful for targeted checks

Discovery with Playwright MCP

1. browser_navigate to the URL
2. browser_snapshot to get the page structure
3. browser_take_screenshot for visual reference
4. Examine links, forms, headings, navigation from the snapshot
5. Navigate to discovered subpages and repeat

Discovery with Playwright CLI

playwright-cli open <URL>
playwright-cli screenshot --name discovery_home
playwright-cli snapshot
# Examine snapshot output for links, forms, navigation, headings
# Follow important links to discover subpages
playwright-cli goto <subpage-url>
playwright-cli screenshot --name discovery_subpage

Discovery with Python script

python scripts/discover.py --url <URL> --max-pages 10 --output discovery.json

Local project (no live URL)

When only source files are available:

1. Start a local server: python -m http.server 8080 --directory <project-path> (or npx serve <project-path> or any other static server)
2. Run discovery against http://localhost:8080
3. If the port is busy, try 8081, 8082, etc.

Important: file:// URLs may be blocked by some tools. Always prefer HTTP serving.

Phase 2: Generate Use Cases

After discovery, produce a use case list from the perspective of an end user.

Format

UC-01: [Actor] can [action] so that [goal]
UC-02: [Actor] can [action] so that [goal]
...

Categories to cover

• Navigation — user browses pages, menu works, links resolve
• Authentication — sign up, log in, password reset, logout
• Core feature flows — the main thing the site does (purchase, search, submit form, etc.)
• Content validation — required text, images, prices, labels appear correctly
• Forms — fill in, submit, validate errors, success states
• Responsiveness — works on mobile viewport
• Error handling — 404 pages, empty states, invalid inputs
• Performance / visual — no broken images, no console errors, reasonable load
• Accessibility basics — alt text on images, heading hierarchy, landmark elements

Aim for 10–25 use cases depending on site complexity.

Phase 3: Test Plan

Convert each use case into a concrete test case:

TC-01 [UC-01]: Homepage Navigation
  Given: User opens the site root URL
  When:  Page finishes loading
  Then:  - Page title is not empty
         - Navigation menu is visible
         - Logo/brand element is present
         - No 404/500 status code
         Checks: title, nav links count > 0, hero text present

Test case types to include

If using the Python scripts, save the test plan as test_plan.json — see references/test_case_schema.md for the JSON schema.

Phase 4: Test Execution

For each test case, follow this pattern regardless of which tool you use:

1. Navigate to the target page
2. Capture a "before" screenshot
3. Execute steps — clicks, form fills, scrolling, waiting
4. Run assertions — element presence, text content, console errors, image loading
5. Capture an "after" screenshot if any interaction occurred
6. Record result — PASS / FAIL / SKIP + error message + duration

Execution with Playwright MCP

browser_navigate to target URL
browser_take_screenshot for "before" capture
browser_snapshot to check element presence
browser_evaluate to run JS assertions:
  - document.title !== ''
  - document.querySelectorAll('nav').length > 0
  - document.querySelectorAll('img').filter(i => i.naturalWidth === 0).length
browser_click / browser_type for interactions
browser_take_screenshot for "after" capture
browser_console_messages to check for JS errors
browser_resize for mobile viewport testing

Execution with Playwright CLI

# Navigate and screenshot
playwright-cli goto <URL>
playwright-cli screenshot --name tc01_before

# Get page state for assertions
playwright-cli snapshot
# Parse snapshot output to verify elements exist, text content matches, etc.

# Interact
playwright-cli click <ref>
playwright-cli fill <ref> "test@example.com"
playwright-cli press Enter

# After screenshot
playwright-cli screenshot --name tc01_after

For mobile viewport testing, open a separate session with mobile dimensions or resize the browser.

For status code testing (e.g., checking that /404 returns 404): use playwright-cli navigation — the tool reports HTTP status in its output. Note that navigating to a 4xx/5xx page may throw an error in some tools; catch it gracefully and record the status code from the error message.

Execution with Python scripts

python scripts/run_tests.py \
  --url <URL> \
  --test-plan test_plan.json \
  --output test_results/

Console error collection

Console errors are important signals. Collect them during each test:

• Playwright MCP: Use browser_console_messages or browser_evaluate
• Playwright CLI: Check snapshot output or use playwright-cli evaluation
• Python scripts: The script registers a console listener before navigation

Image loading checks

To detect broken images, run this JS on the page:

Array.from(document.images)
  .filter(img => img.naturalWidth === 0 && img.src && !img.src.startsWith('data:'))
  .map(img => img.src)

An empty result means all images loaded. Otherwise, list the broken URLs.

Accessibility checks

Quick checks to run on each page:

// Images missing alt text
document.querySelectorAll('img:not([alt]), img[alt=""]').length

// Heading hierarchy (should have h1, not skip levels)
[...document.querySelectorAll('h1,h2,h3,h4,h5,h6')].map(h => h.tagName)

// Landmark elements
document.querySelectorAll('main, nav, header, footer, [role]').length

Phase 5: Report Generation

Report contents

• Summary dashboard — total tests, pass/fail/skip counts, pass rate %, tested URL, timestamp
• Use case list with traceability to test cases
• Test results table — TC ID, name, status badge, duration, error message
• Screenshot gallery — inline base64 screenshots per test case (or file paths)
• Console errors log — any JS errors captured
• Recommendations — auto-generated improvement suggestions based on failures

Report format

• Primary: HTML (self-contained, with embedded screenshots as base64)
• Secondary: Markdown summary for quick reading

Using the Python report generator

python scripts/generate_report.py \
  --results test_results/results.json \
  --screenshots test_results/screenshots/ \
  --output qa_report.html

Manual report generation

If the Python script is not available, generate the HTML report directly. Build a self-contained HTML file with:

• A dark header with site name, URL, and timestamp
• Stat cards: total tests, passed, failed, skipped, pass rate
• A results table with status badges (green PASS, red FAIL, yellow SKIP)
• Embedded screenshots (base64-encoded PNGs)
• Recommendations section based on failures

Save the report in the current working directory or wherever the user specified.

Workflow Summary (step-by-step)

1. Receive URL or project files from user
2. Pick your execution tool (MCP > Playwright CLI > Python > Manual)
3. Run discovery → understand pages, structure, features
4. Generate use case list (10–25 use cases)
5. Generate test plan → structured test cases
6. Run tests → collect results + screenshots
7. Generate HTML report
8. Show the report path to the user

Handling Common Situations

Local project without a live URL → Serve files locally: python -m http.server 8080 or npx serve. → Test against http://localhost:8080 → Do NOT use file:// URLs — they may be blocked

Site requires authentication → Ask user for test credentials OR → Test only the public-facing pages → Mark auth-gated tests as SKIP with note

Single-page app (React/Vue/Angular) → Wait for page to fully render (networkidle or specific selectors) → Check that JS bundle loads without console errors → Use snapshot/evaluate to verify dynamically rendered content

Large site (many pages) → Focus on critical user paths first → Limit to top 5–10 most important flows → Mention in report which pages were NOT covered

Status code testing (4xx/5xx pages) → Some tools throw errors on non-2xx responses → Catch the error and extract the status code from it → Or use JS fetch() to check status codes without navigation

Mobile responsiveness testing → Resize viewport to 390×844 (iPhone) or 360×800 (Android) → Check for horizontal overflow: document.body.scrollWidth > window.innerWidth → Verify key elements are still visible and readable

Reference Files

• references/test_case_schema.md — JSON schema for test_plan.json
• scripts/discover.py — Site discovery automation (Python + Playwright)
• scripts/run_tests.py — Test execution engine (Python + Playwright)
• scripts/generate_report.py — HTML report generator (Python)