test-web-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Web Tester Skill

Web 测试技能

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

将任意网站或项目转化为结构化的QA测试流程： 发现 → 规划 → 执行 → 报告

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

Phase 1 → 发现阶段   : 探索网站，了解其用途与功能
Phase 2 → 用例生成   : 生成终端用户用例列表
Phase 3 → 测试计划   : 将用例转化为具体可执行的测试用例
Phase 4 → 执行测试   : 通过Playwright运行测试，捕获截图
Phase 5 → 生成报告   : 整合HTML + Markdown格式的全量测试结果报告

Choosing Your Execution Tool

选择执行工具

Pick the first option that works in your environment:

选择在你的环境中可用的首个选项：

Option 1: Playwright MCP Tools (recommended)

选项1：Playwright MCP工具（推荐）

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

若Playwright MCP工具可用（如

mcp__plugin_playwright_playwright__*

），请优先使用——它们是速度最快且最节省令牌的选项（比CLI快约2.8倍，每个MCP调用可完成更多工作，所需工具调用次数更少）：

browser_navigate → 导航至指定URL
browser_snapshot → 获取页面状态与元素引用
browser_take_screenshot → 捕获截图
browser_click → 点击元素
browser_type → 在输入框中输入内容
browser_evaluate → 运行JS断言
browser_resize → 测试移动端视口
browser_console_messages → 检查JS错误

Option 2: Playwright CLI

选项2：Playwright CLI

The

@playwright/cli

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

bash

npm install -g @playwright/cli@latest

Key commands for QA testing:

bash

undefined

@playwright/cli

是一款为编码Agent设计的CLI工具。当MCP工具不可用时使用此选项。若未安装，请执行以下命令：

bash

npm install -g @playwright/cli@latest

QA测试核心命令：

bash

undefined

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)

(在.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.

playwright-cli close


Playwright CLI默认以无头模式运行。添加 `--headed` 参数可可视化查看浏览器操作。
使用 `playwright-cli show` 可打开所有活跃会话的控制面板。

Option 3: Python Playwright Scripts

选项3：Python Playwright脚本

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

scripts/

bash

undefined

若已安装Python与Playwright，可使用

scripts/

目录下的配套脚本：

bash

undefined

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

undefined

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

undefined

Option 4: Manual Testing

选项4：手动测试

If none of the above are available, read the source code directly and perform manual analysis. Use

curl

fetch

for basic HTTP checks.

若以上工具均不可用，请直接阅读源代码并执行手动分析。使用

curl

或

fetch

进行基础HTTP检查。

Phase 1: Discovery

阶段1：发现

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

URL —— 若用户提供在线URL，导航至该地址并探索
项目文件 —— 若无在线URL，检查项目目录下的源文件
用途 —— 网站的功能是什么？（着陆页、电商平台、仪表盘、博客等）
核心页面 —— 首页、认证页面、主要功能页面、表单、结账页面等
技术栈 —— 可选，但有助于针对性检查

Discovery with Playwright MCP

使用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

1. 使用browser_navigate导航至目标URL
2. 使用browser_snapshot获取页面结构
3. 使用browser_take_screenshot留存视觉参考
4. 从快照中分析链接、表单、标题、导航栏
5. 导航至发现的子页面并重复上述步骤

Discovery with Playwright CLI

使用Playwright CLI进行发现

bash

playwright-cli open <URL>
playwright-cli screenshot --name discovery_home
playwright-cli snapshot

bash

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

undefined

playwright-cli goto <subpage-url> playwright-cli screenshot --name discovery_subpage

undefined

Discovery with Python script

使用Python脚本进行发现

bash

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

bash

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

Local project (no live URL)

本地项目（无在线URL）

When only source files are available:

Start a local server:

python -m http.server 8080 --directory <project-path>

(or

npx serve <project-path>

or any other static server)

Run discovery against
```
http://localhost:8080
```
If the port is busy, try 8081, 8082, etc.

Important:

file://

URLs may be blocked by some tools. Always prefer HTTP serving.

当仅提供源文件时：

启动本地服务器：

python -m http.server 8080 --directory <project-path>

（或

npx serve <project-path>

或其他静态服务器）

针对
```
http://localhost:8080
```
运行发现阶段
若端口被占用，尝试8081、8082等端口

重要提示：部分工具可能阻止

file://

格式的URL。请始终优先使用HTTP服务。

Phase 2: Generate Use Cases

阶段2：生成用例

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]
...

UC-01: [角色] 可以 [执行操作] 以实现 [目标]
UC-02: [角色] 可以 [执行操作] 以实现 [目标]
...

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.

导航 —— 用户浏览页面、菜单正常工作、链接可正常跳转
认证 —— 注册、登录、密码重置、登出
核心功能流程 —— 网站的核心功能（购买、搜索、提交表单等）
内容验证 —— 必填文本、图片、价格、标签正确显示
表单 —— 填写、提交、验证错误、成功状态
响应式 —— 在移动端视口正常显示
错误处理 —— 404页面、空状态、无效输入处理
性能/视觉 —— 无损坏图片、无控制台错误、加载速度合理
基础可访问性 —— 图片包含替代文本、标题层级合理、地标元素存在

根据网站复杂度，目标生成10–25条用例。

Phase 3: Test Plan

阶段3：测试计划

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

将每条用例转化为具体的测试用例：

TC-01 [UC-01]: 首页导航
  前提条件: 用户打开网站根URL
  操作步骤: 页面加载完成
  预期结果:  - 页面标题非空
            - 导航菜单可见
            - Logo/品牌元素存在
            - 无404/500状态码
  检查项: 标题、导航链接数量>0、核心文案存在

Test case types to include

需包含的测试用例类型

Type	Examples
Presence checks	Element exists, text is visible, image loads
Functional checks	Button clickable, form submits, menu expands
Data validation	Price format, phone format, required fields
Navigation checks	Links don't 404, routing works
Form validation	Empty submit shows errors, valid submit succeeds
Responsiveness	Mobile viewport renders without overflow
Console errors	No JS errors on page load
Accessibility basics	Images have alt text, headings hierarchy, landmarks

If using the Python scripts, save the test plan as

test_plan.json

— see

references/test_case_schema.md

for the JSON schema.

类型	示例
存在性检查	元素存在、文本可见、图片加载正常
功能性检查	按钮可点击、表单可提交、菜单可展开
数据验证	价格格式、电话格式、必填字段检查
导航检查	链接无404错误、路由正常
表单验证	空提交显示错误、有效提交成功
响应式检查	移动端视口无横向溢出
控制台错误检查	页面加载时无JS错误
基础可访问性检查	图片含替代文本、标题层级合理、地标元素存在

若使用Python脚本，将测试计划保存为

test_plan.json

—— 可参考

references/test_case_schema.md

中的JSON schema。

Phase 4: Test Execution

阶段4：测试执行

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

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

无论使用哪种工具，每条测试用例均遵循以下流程：

导航至目标页面
捕获“操作前”截图
执行步骤 —— 点击、表单填写、滚动、等待
运行断言 —— 元素存在性、文本内容、控制台错误、图片加载状态
若发生交互，捕获“操作后”截图
记录结果 —— 通过/失败/跳过 + 错误信息 + 耗时

Execution with Playwright MCP

使用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

browser_navigate至目标URL
browser_take_screenshot捕获“操作前”截图
browser_snapshot检查元素存在性
browser_evaluate运行JS断言:
  - document.title !== ''
  - document.querySelectorAll('nav').length > 0
  - document.querySelectorAll('img').filter(i => i.naturalWidth === 0).length
browser_click / browser_type执行交互操作
browser_take_screenshot捕获“操作后”截图
browser_console_messages检查JS错误
browser_resize进行移动端视口测试

Execution with Playwright CLI

使用Playwright CLI执行测试

bash

undefined

bash

undefined

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.

playwright-cli screenshot --name tc01_after


对于**移动端视口测试**，打开带有移动端尺寸的独立会话或调整浏览器窗口大小。

对于**状态码测试**（如检查/404是否返回404）：使用 `playwright-cli` 导航——工具会在输出中报告HTTP状态码。注意：部分工具在导航至4xx/5xx页面时可能抛出错误，请优雅捕获并从错误信息中提取状态码。

Execution with Python scripts

使用Python脚本执行测试

bash

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

bash

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

browser_evaluate

Playwright CLI: Check snapshot output or use
```
playwright-cli
```
evaluation
Python scripts: The script registers a console listener before navigation

控制台错误是重要的信号。在每次测试中收集：

Playwright MCP: 使用

browser_console_messages

或

browser_evaluate

Playwright CLI: 检查快照输出或使用
```
playwright-cli
```
执行评估
Python脚本: 脚本会在导航前注册控制台监听器

Image loading checks

图片加载检查

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

javascript

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.

为检测损坏图片，在页面上运行以下JS代码：

javascript

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

若结果为空，则所有图片加载正常；否则，列出损坏的URL。

Accessibility checks

可访问性检查

Quick checks to run on each page:

javascript

// 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

在每个页面上执行以下快速检查：

javascript

// 缺少替代文本的图片
document.querySelectorAll('img:not([alt]), img[alt=""]').length

// 标题层级（应包含h1，且不跳过层级）
[...document.querySelectorAll('h1,h2,h3,h4,h5,h6')].map(h => h.tagName)

// 地标元素
document.querySelectorAll('main, nav, header, footer, [role]').length

Phase 5: Report Generation

阶段5：报告生成

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

摘要仪表盘 —— 测试总数、通过/失败/跳过数量、通过率、测试URL、时间戳
用例列表 —— 与测试用例关联追溯
测试结果表格 —— 测试用例ID、名称、状态标识、耗时、错误信息
截图库 —— 每条测试用例对应的内嵌base64截图（或文件路径）
控制台错误日志 —— 捕获到的所有JS错误
建议 —— 根据失败结果自动生成改进建议

Report format

报告格式

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

主格式：HTML（自包含，截图以base64嵌入）
次要格式：Markdown（快速阅读摘要）

Using the Python report generator

使用Python报告生成器

bash

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

bash

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.

若Python脚本不可用，可直接生成HTML报告。构建自包含HTML文件，包含：

深色头部：显示网站名称、URL、时间戳
统计卡片：测试总数、通过数、失败数、跳过数、通过率
结果表格：带状态标识（绿色通过、红色失败、黄色跳过）
内嵌截图（base64编码的PNG图片）
基于失败结果的建议部分

将报告保存至当前工作目录或用户指定的位置。

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

```
references/test_case_schema.md
```
—— test_plan.json的JSON schema
```
scripts/discover.py
```
—— 网站发现自动化脚本（Python + Playwright）
```
scripts/run_tests.py
```
—— 测试执行引擎（Python + Playwright）
```
scripts/generate_report.py
```
—— HTML报告生成器（Python）

Handling Common Situations

—

Local project without a live URL → Serve files locally:

python -m http.server 8080

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)

—