test-web-ui

Web 测试技能

将任何网站或项目转化为结构化 QA 测试流程： 探索 → 规划 → 执行 → 报告

---

阶段概览

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

---

选择执行工具

选择你的环境中第一个可用的选项：

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

如果可以使用 Playwright MCP 工具（例如 mcp__plugin_playwright_playwright__*）， 请使用它们——这是速度最快且最节省 token 的选项（比 CLI 快约 2.8 倍， 所需工具调用次数更少，因为每次 MCP 调用都能完成更多工作）：

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

选项 2：Playwright CLI

@playwright/cli 是专为编码 Agent 设计的 CLI。MCP 工具不可用时使用。必要时进行安装：

npm install -g @playwright/cli@latest

QA 测试的关键命令：

# 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 默认以无头模式运行。添加 --headed 可直观看到浏览器运行情况。 使用 playwright-cli show 可打开显示所有活动会话的控制面板。

选项 3：Python Playwright 脚本

如果已安装 Python 和 Playwright，请使用 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

选项 4：手动测试

如果以上选项都不可用，请直接阅读源代码并进行手动分析。使用 curl 或 fetch 进行基本的 HTTP 检查。

---

阶段 1：探索

收集内容

• URL — 如果用户提供了可访问的 URL，请打开并探索
• 项目文件 — 如果没有可访问的 URL，请检查项目目录中的源文件
• 用途 — 网站的功能是什么？（着陆页、电商、仪表板、博客等）
• 关键页面 — 首页、身份验证页、主要功能页、表单、结账页等
• 技术栈 — 可选，但有助于开展有针对性的检查

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

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

使用 Python 脚本探索

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

本地项目（没有可访问的 URL）

只有源文件可用时：

1. 启动本地服务：python -m http.server 8080 --directory <project-path> （或使用 npx serve <project-path> 或其他静态服务）
2. 针对 http://localhost:8080 进行探索
3. 如果端口正忙，请尝试 8081、8082 等

重要： 某些工具可能会屏蔽 file:// URL。请始终优先使用 HTTP 服务。

---

阶段 2：生成用例

探索之后，从最终用户的视角列出用例。

格式

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

应涵盖的类别

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

根据网站的复杂程度，目标为 10–25 个用例。

---

阶段 3：测试计划

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

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

应包含的测试用例类型

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

如果使用 Python 脚本，请将测试计划保存为 test_plan.json — JSON 架构见 references/test_case_schema.md。

---

第 4 阶段：测试执行

对于每个测试用例，无论使用哪种工具，都遵循以下模式：

1. 导航到目标页面
2. 截取“之前”的屏幕截图
3. 执行步骤——点击、填写表单、滚动、等待
4. 运行断言——元素是否存在、文本内容、控制台错误、图像是否加载
5. 如果发生了交互，截取“之后”的屏幕截图
6. 记录结果——PASS / FAIL / SKIP + 错误消息 + 持续时间

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

使用 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> "[email protected]"
playwright-cli press Enter

# After screenshot
playwright-cli screenshot --name tc01_after

进行移动视口测试时，请使用移动设备尺寸打开单独的会话，或调整浏览器大小。

进行状态码测试（例如，检查 /404 是否返回 404）时：使用 playwright-cli 导航——该工具会在输出中报告 HTTP 状态码。请注意， 在某些工具中，导航到 4xx/5xx 页面可能会引发错误；请妥善捕获错误， 并从错误消息中记录状态码。

使用 Python 脚本执行

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

收集控制台错误

控制台错误是重要信号。请在每次测试期间收集这些错误：

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

图像加载检查

如需检测损坏的图像，请在页面上运行此 JS：

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

结果为空表示所有图像均已加载。否则，请列出损坏的 URL。

无障碍检查

在每个页面上运行的快速检查：

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

---

第 5 阶段：生成报告

报告内容

• 摘要仪表板——测试总数、通过 / 失败 / 跳过数量、通过率 %、测试的 URL、时间戳
• 用例列表，并附上与测试用例的可追溯关系
• 测试结果表——TC ID、名称、状态徽章、持续时间、错误消息
• 屏幕截图集——每个测试用例的内嵌 base64 屏幕截图（或文件路径）
• 控制台错误日志——捕获到的任何 JS 错误
• 建议——根据失败自动生成的改进建议

报告格式

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

使用 Python 报告生成器

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

手动生成报告

如果 Python 脚本不可用，请直接生成 HTML 报告。 构建一个自包含的 HTML 文件，其中包含：

• 深色页眉，显示站点名称、URL 和时间戳
• 统计卡片：测试总数、通过、失败、跳过、通过率
• 结果表，带有状态徽章（绿色 PASS、红色 FAIL、黄色 SKIP）
• 嵌入的屏幕截图（以 base64 编码的 PNG）
• 根据失败生成的建议部分

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

---

工作流摘要（分步）

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

---

常见情况处理

本地项目没有线上 URL → 在本地提供文件服务：python -m http.server 8080 或 npx serve . → 针对 http://localhost:8080 进行测试 → 请勿使用 file:// URL——它们可能会被阻止

站点需要身份验证 → 向用户索取测试凭据，或 → 仅测试面向公众的页面 → 将需要身份验证的测试标记为 SKIP，并附上说明

单页应用（React/Vue/Angular） → 等待页面完全渲染（networkidle 或特定选择器） → 检查 JS 包是否加载，且无控制台错误 → 使用快照 / 评估验证动态渲染的内容

大型站点（页面众多） → 优先关注关键用户路径 → 限定为最重要的前 5–10 个流程 → 在报告中说明未覆盖的页面

状态码测试（4xx/5xx 页面） → 某些工具会对非 2xx 响应引发错误 → 捕获错误并从中提取状态码 → 或使用 JS fetch() 在不导航的情况下检查状态码

移动端响应式测试 → 将视口调整为 390×844（iPhone）或 360×800（Android） → 检查是否存在水平溢出：document.body.scrollWidth > window.innerWidth → 验证关键元素仍清晰可见且易于阅读

---

参考文件

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