playwright-visual-testing

Playwright 视觉测试与浏览器自动化

这是一项全面的技能，利用 Playwright MCP 服务集成进行浏览器自动化和视觉测试。此技能可为现代 Web 应用实现快速 UI 测试、视觉回归检测、自动化浏览器交互和跨浏览器验证。

何时使用此技能

在以下情况下使用此技能：

• 在多个浏览器（Chromium、Firefox、WebKit）中测试 Web 应用
• 为 UI 更改实施视觉回归测试
• 自动化用户交互，以进行 QA 和测试
• 在不同视口中验证响应式设计
• 为文档或错误报告截取屏幕截图
• 测试表单提交和用户工作流
• 验证 Web 界面的无障碍性
• 调试特定浏览器的问题
• 创建自动化 E2E 测试套件
• 在部署前验证 Web 应用
• 测试 PWA 和单页应用
• 为设计评审捕获视觉状态

核心概念

Playwright 浏览器自动化理念

Playwright 为现代 Web 应用提供可靠的端到端测试：

• 自动等待：交互前自动等待元素可执行操作
• Web 优先断言：重试断言，直到通过或超时
• 跨浏览器：使用单一 API 在 Chromium、Firefox 和 WebKit 上进行测试
• 无障碍快照：使用语义结构而非视觉渲染浏览页面
• 视觉测试：比较屏幕截图以检测视觉回归
• 网络控制：拦截并模拟网络请求
• 多上下文：在隔离的浏览器上下文中测试多个场景

Playwright 关键实体

1. Browser：浏览器实例（Chromium、Firefox、WebKit）
2. Page：浏览器中的单个页面/标签页
3. Locator：使用无障碍树定位元素的选择器
4. Snapshot：页面状态的无障碍树表示
5. Screenshot：页面或元素的视觉捕获
6. Network Request：页面发出的 HTTP 请求
7. Console Messages：浏览器控制台输出
8. Dialog：浏览器提示框、警告框、确认框

视觉测试工作流

1. 导航到目标页面
2. 等待页面稳定（动画、加载）
3. 捕获无障碍快照以获取上下文
4. 截取屏幕截图，捕获页面或特定元素
5. 比较基准图像（可选）
6. 验证视觉效果和功能
7. 记录结果和问题

Playwright MCP 服务工具参考

浏览器生命周期管理

browser_navigate

在当前页面导航到某个 URL。

参数：

url: The URL to navigate to (required)

示例：

url: "https://example.com"

最佳实践：

• 使用包含协议（https://）的完整 URL
• 操作前等待导航完成
• 处理重定向和页面跳转

browser_navigate_back

返回历史记录中的上一页。

参数： 无

示例：

// Navigate back after clicking a link

使用场景：

• 测试导航流程
• 验证后退按钮行为
• 多步骤表单导航

browser_close

关闭当前浏览器页面。

参数： 无

使用时机：

• 测试后进行清理
• 释放系统资源
• 重置浏览器状态

browser_resize

调整浏览器视口大小。

参数：

width: Width in pixels (required)
height: Height in pixels (required)

常见视口：

// Mobile
width: 375, height: 667  // iPhone SE
width: 414, height: 896  // iPhone XR

// Tablet
width: 768, height: 1024  // iPad

// Desktop
width: 1280, height: 720  // HD
width: 1920, height: 1080 // Full HD

示例：

width: 375
height: 667

页面检查与快照

browser_snapshot

捕获当前页面的无障碍快照。

参数： 无

返回内容：

• 带有语义结构的无障碍树
• 用于交互的元素引用（ref）
• 文本内容和角色
• 交互元素及其状态

为何使用快照：

• 比屏幕截图更适合自动化
• 能够语义化地理解页面结构
• 提供用于精确交互的元素引用
• 比视觉解析更快
• 无需视觉渲染即可使用

快照结构示例：

heading "Welcome" [ref=123]
  text "to our site"
button "Sign In" [ref=456]
textbox "Email" [ref=789]
  value: ""

browser_take_screenshot

截取当前页面或元素的屏幕截图。

参数：

filename: Output filename (optional, defaults to page-{timestamp}.png)
type: Image format - "png" or "jpeg" (default: png)
fullPage: Capture full scrollable page (default: false)
element: Human-readable element description (optional)
ref: Element reference from snapshot (optional, requires element)

截图类型：

1. 视口截图（默认）：

filename: "homepage-viewport.png"

2. 整页截图：

filename: "homepage-full.png"
fullPage: true

3. 元素截图：

filename: "header.png"
element: "main header navigation"
ref: "123"

最佳实践：

• 使用能体现上下文的描述性文件名
• UI 元素使用 PNG 格式（无损）
• 照片/图像使用 JPEG 格式（文件较小）
• 文档使用整页截图
• 针对重点测试使用元素截图

浏览器交互

browser_click

点击元素。

参数：

element: Human-readable element description (required)
ref: Element reference from snapshot (required)
button: "left", "right", or "middle" (default: left)
doubleClick: true for double-click (default: false)
modifiers: Array of modifier keys ["Alt", "Control", "ControlOrMeta", "Meta", "Shift"]

示例：

1. 基本点击：

element: "Submit button"
ref: "456"

2. 右键点击：

element: "Context menu trigger"
ref: "789"
button: "right"

3. 使用修饰键点击：

element: "Link to open in new tab"
ref: "123"
modifiers: ["ControlOrMeta"]

4. 双击：

element: "Word to select"
ref: "321"
doubleClick: true

browser_type

在可编辑元素中输入文本。

参数：

element: Human-readable element description (required)
ref: Element reference from snapshot (required)
text: Text to type (required)
slowly: Type one character at a time (default: false)
submit: Press Enter after typing (default: false)

示例：

1. 表单输入：

element: "Email textbox"
ref: "123"
text: "[email protected]"

2. 搜索并提交：

element: "Search field"
ref: "456"
text: "playwright testing"
submit: true

3. 逐字符输入（触发按键处理程序）：

element: "Auto-complete input"
ref: "789"
text: "New York"
slowly: true

browser_press_key

按下键盘按键。

参数：

key: Key name or character (required)

常用按键：

ArrowLeft, ArrowRight, ArrowUp, ArrowDown
Enter, Escape, Tab, Backspace, Delete
Home, End, PageUp, PageDown
F1-F12
Control, Alt, Shift, Meta

示例：

// Navigation
key: "ArrowDown"

// Submit form
key: "Enter"

// Close dialog
key: "Escape"

// Tab through fields
key: "Tab"

browser_fill_form

一次填写多个表单字段。

参数：

fields: Array of field objects (required)
  - name: Human-readable field name
  - type: "textbox", "checkbox", "radio", "combobox", "slider"
  - ref: Element reference from snapshot
  - value: Value to set (string, "true"/"false" for checkboxes)

示例：

fields: [
  {
    name: "Username",
    type: "textbox",
    ref: "123",
    value: "john_doe"
  },
  {
    name: "Password",
    type: "textbox",
    ref: "456",
    value: "secretpass123"
  },
  {
    name: "Remember me",
    type: "checkbox",
    ref: "789",
    value: "true"
  }
]

browser_select_option

从下拉菜单中选择选项。

参数：

element: Human-readable element description (required)
ref: Element reference from snapshot (required)
values: Array of values to select (required)

示例：

element: "Country dropdown"
ref: "123"
values: ["United States"]

多选：

element: "Programming languages"
ref: "456"
values: ["JavaScript", "Python", "Go"]

browser_hover

将鼠标悬停在元素上。

参数：

element: Human-readable element description (required)
ref: Element reference from snapshot (required)

使用场景：

• 触发工具提示
• 显示下拉菜单
• 测试悬停状态
• 显示隐藏元素

示例：

element: "Help icon"
ref: "123"

browser_drag

在元素之间拖放。

参数：

startElement: Source element description (required)
startRef: Source element reference (required)
endElement: Target element description (required)
endRef: Target element reference (required)

示例：

startElement: "Task card"
startRef: "123"
endElement: "Done column"
endRef: "456"

使用场景：

• 拖放界面
• 重新排序列表
• 文件上传
• 看板

高级交互

browser_evaluate

在页面上下文中执行 JavaScript。

参数：

function: JavaScript function as string (required)
element: Element description (optional)
ref: Element reference (optional, requires element)

示例：

1. 页面级脚本：

function: "() => { return document.title; }"

2. 元素级脚本：

element: "Custom widget"
ref: "123"
function: "(element) => { return element.getAttribute('data-value'); }"

常见使用场景：

// Get page title
function: "() => document.title"

// Scroll to bottom
function: "() => window.scrollTo(0, document.body.scrollHeight)"

// Get element dimensions
function: "(element) => { const rect = element.getBoundingClientRect(); return { width: rect.width, height: rect.height }; }"

// Set local storage
function: "() => localStorage.setItem('theme', 'dark')"

// Get computed style
function: "(element) => getComputedStyle(element).backgroundColor"

browser_file_upload

将文件上传到文件输入框。

参数：

paths: Array of absolute file paths (required)
  - Omit or pass empty array to cancel file chooser

示例：

paths: [
  "/Users/user/Documents/resume.pdf",
  "/Users/user/Photos/headshot.jpg"
]

单个文件：

paths: ["/Users/user/Downloads/report.csv"]

取消上传：

paths: []

浏览器状态与调试

browser_console_messages

获取浏览器中的控制台消息。

参数：

onlyErrors: Return only error messages (default: false)

返回：

• 所有 console.log、console.error、console.warn 消息
• 时间戳和消息类型
• JavaScript 错误和堆栈跟踪

示例：

1. 所有消息：

onlyErrors: false

2. 仅错误：

onlyErrors: true

使用场景：

• 调试 JavaScript 错误
• 监控 API 故障
• 跟踪控制台警告
• 验证日志记录行为

browser_network_requests

获取页面加载以来的所有网络请求。

参数： 无

返回：

• URL、方法、状态码
• 请求/响应标头
• 计时信息
• 请求/响应正文

使用场景：

• 验证 API 调用
• 检查资源加载
• 调试失败的请求
• 监控性能
• 验证分析跟踪

browser_handle_dialog

响应浏览器对话框。

参数：

accept: Accept or dismiss dialog (required)
promptText: Text for prompt dialogs (optional)

对话框类型：

• alert：信息消息
• confirm：是/否选项
• prompt：文本输入请求
• beforeunload：页面导航警告

示例：

1. 接受警告框：

accept: true

2. 关闭确认框：

accept: false

3. 回答提示框：

accept: true
promptText: "John Doe"

browser_wait_for

等待条件满足后再继续。

参数：

text: Wait for text to appear (optional)
textGone: Wait for text to disappear (optional)
time: Wait for specified seconds (optional)

示例：

1. 等待文本出现：

text: "Loading complete"

2. 等待元素移除：

textGone: "Loading..."

3. 固定等待时间：

time: 2

最佳实践：

• 优先等待特定条件，而非固定时长
• 用于等待动态内容加载
• 等待动画完成
• 截图前确保页面稳定

标签页管理

browser_tabs

管理浏览器标签页。

参数：

action: "list", "new", "close", "select" (required)
index: Tab index for close/select (optional)

操作：

1. 列出标签页：

action: "list"

2. 新建标签页：

action: "new"

3. 关闭标签页：

action: "close"
index: 1  // Optional, closes current if omitted

4. 切换标签页：

action: "select"
index: 0

使用场景：

• 多标签页工作流
• 测试特定于标签页的功能
• 在新标签页中打开链接
• 管理多个会话

浏览器安装

browser_install

安装配置中指定的浏览器。

参数： 无

适用场景：

• 首次设置
• 出现“未安装浏览器”错误
• 更新浏览器版本
• 设置 CI/CD 环境

视觉测试工作流模式

模式 1：基础视觉回归测试

场景： 验证首页的视觉效果未发生变化

1. Navigate to page
   - Use browser_navigate with target URL
   - Wait for page to load completely

2. Capture baseline
   - Take full-page screenshot
   - Use browser_snapshot for context
   - Document visible elements

3. Make changes (if testing changes)
   - Update code, deploy
   - Clear cache

4. Capture new state
   - Navigate to same URL
   - Take identical screenshot
   - Compare manually or with tools

5. Validate differences
   - Expected changes present
   - No unexpected regressions
   - Document findings

模式 2：响应式设计测试

场景： 测试不同设备上的布局

1. Define viewports
   - Mobile: 375x667 (iPhone SE)
   - Tablet: 768x1024 (iPad)
   - Desktop: 1920x1080 (Full HD)

2. For each viewport:
   a. Resize browser
      - browser_resize with dimensions

   b. Navigate to page
      - browser_navigate to URL

   c. Wait for layout
      - browser_wait_for with condition

   d. Capture snapshot
      - browser_snapshot for structure

   e. Take screenshot
      - browser_take_screenshot with descriptive name
      - Include viewport in filename

3. Compare layouts
   - Verify responsive breakpoints
   - Check element reflow
   - Validate mobile navigation
   - Ensure content accessibility

4. Document issues
   - Screenshot any problems
   - Note viewport where issue occurs
   - Record expected vs actual behavior

模式 3：表单测试工作流

场景： 测试多步骤表单提交

1. Navigate to form
   - browser_navigate to form URL
   - browser_snapshot to get field refs

2. Fill form fields
   - Use browser_fill_form for batch entry
   - Or individual browser_type for each field
   - Include validation triggers

3. Test validation
   - Submit with invalid data
   - browser_snapshot to see errors
   - Screenshot error states
   - Verify error messages appear

4. Complete valid submission
   - Fill all required fields
   - browser_click submit button
   - Wait for success message
   - browser_wait_for confirmation text

5. Verify results
   - Check success page
   - Verify data submission
   - Screenshot confirmation
   - Check network requests

模式 4：特定元素视觉测试

场景： 测试单个组件的变更

1. Navigate to component page
   - browser_navigate to page
   - browser_snapshot for structure

2. Locate component
   - Find element ref from snapshot
   - Verify component is visible

3. Test states
   a. Default state
      - Take element screenshot
      - Document initial appearance

   b. Hover state
      - browser_hover on element
      - Take element screenshot
      - Compare with default

   c. Active/focused state
      - browser_click on element
      - Take element screenshot
      - Verify visual feedback

   d. Error state (if applicable)
      - Trigger validation error
      - Take element screenshot
      - Verify error styling

4. Document state changes
   - Compare screenshots
   - Note expected behaviors
   - Report any issues

模式 5：跨浏览器测试

场景： 验证不同浏览器间的一致性

1. Define browser matrix
   - Chromium (Chrome/Edge)
   - Firefox
   - WebKit (Safari)

2. For each browser:
   a. Configure browser
      - Set in MCP server config

   b. Run test suite
      - Navigate to pages
      - Capture snapshots
      - Take screenshots
      - Test interactions

   c. Document results
      - Save browser-specific screenshots
      - Note rendering differences
      - Log browser-specific bugs

3. Compare results
   - Side-by-side screenshots
   - Functionality differences
   - Performance variations
   - CSS rendering issues

4. Address discrepancies
   - Fix critical cross-browser bugs
   - Document acceptable differences
   - Add browser-specific styles if needed

模式 6：端到端用户旅程测试

场景： 验证完整的用户工作流

1. Start journey
   - browser_navigate to landing page
   - browser_snapshot initial state
   - Screenshot starting point

2. Authentication
   - Navigate to login
   - Fill credentials with browser_fill_form
   - Submit form
   - Wait for redirect
   - Screenshot logged-in state

3. Main workflow steps
   For each step:
   - Take snapshot before action
   - Perform user action
   - Wait for completion
   - Take screenshot after action
   - Verify expected state

4. Complete transaction
   - Submit final action
   - Wait for confirmation
   - Screenshot success state
   - Verify completion message

5. Cleanup
   - Logout if needed
   - Screenshot final state
   - Document journey results

模式 7：无障碍快照测试

场景： 验证语义结构和无障碍性

1. Navigate to page
   - browser_navigate to URL

2. Capture accessibility snapshot
   - browser_snapshot for semantic tree
   - Review element roles
   - Check heading hierarchy
   - Verify labels and descriptions

3. Validate structure
   - Proper heading levels (h1 → h2 → h3)
   - Form inputs have labels
   - Buttons have accessible names
   - Interactive elements have roles
   - ARIA attributes present

4. Test keyboard navigation
   - browser_press_key "Tab"
   - Snapshot after each tab
   - Verify focus indicators
   - Ensure logical tab order
   - Test skip links

5. Test screen reader experience
   - Review snapshot text content
   - Verify alt text present
   - Check ARIA live regions
   - Validate semantic landmarks
   - Ensure meaningful structure

6. Document findings
   - Screenshot accessibility tree
   - Note missing labels
   - Report hierarchy issues
   - Suggest improvements

浏览器自动化最佳实践

截图最佳实践

1. 统一命名规范

{page}-{viewport}-{state}-{timestamp}.png

Examples:
homepage-desktop-default-1634567890.png
login-mobile-error-1634567891.png
checkout-tablet-success-1634567892.png

2. 文件名组织

screenshots/
  ├── baselines/
  │   ├── homepage-desktop.png
  │   ├── homepage-mobile.png
  │   └── homepage-tablet.png
  ├── current/
  │   └── homepage-desktop-20251017.png
  └── diffs/
      └── homepage-desktop-diff-20251017.png

3. 整页截图与视口截图

• 文档记录使用整页截图
• 回归测试使用视口截图
• 组件使用元素截图
• 整页截图时考虑页面长度

4. 选择图像格式

• PNG：界面元素、文本、锐利边缘（无损）
• JPEG：照片、背景、大图像（体积更小）
• 测试时默认使用 PNG

快照与截图策略

使用快照的场景：

• 自动化交互
• 测试功能
• 验证结构
• 检查无障碍性
• 需要元素引用
• 测试动态内容

使用截图的场景：

• 视觉回归测试
• 文档记录
• 错误报告
• 设计评审
• 面向利益相关者的演示
• 视觉对比

同时使用的场景：

• 全面测试
• 调试视觉问题
• 创建测试报告
• 记录复杂流程

等待策略

1. 等待特定元素

// Good
browser_wait_for with text: "Data loaded"

// Avoid
browser_wait_for with time: 5

2. 等待动画结束

// Wait for loading spinner to disappear
browser_wait_for with textGone: "Loading..."

3. 等待网络空闲

// Check network requests after waiting
browser_network_requests to verify completion

4. 动态内容

// Wait for specific text before screenshot
browser_wait_for with text: "Results: 42 items"

交互可靠性

1. 始终先使用快照

1. browser_snapshot
2. Find element ref in snapshot
3. Use ref for interaction
4. Never guess element references

2. 验证元素状态

// Take snapshot to verify element exists
// Check element is visible and actionable
// Then perform interaction

3. 处理动态元素

// Wait for element to appear
browser_wait_for with text: "Submit"
// Then take fresh snapshot
browser_snapshot
// Get updated ref and interact

4. 错误恢复

// If interaction fails:
1. Take screenshot of current state
2. Capture console messages (browser_console_messages)
3. Check network requests (browser_network_requests)
4. Take new snapshot to see current state

表单测试策略

1. 批量输入与单独输入

// Batch for simple forms (faster)
browser_fill_form with all fields

// Individual for complex forms (better control)
browser_type for each field
browser_wait_for after each entry
Verify validation triggers

2. 验证测试

// Test each validation rule
1. Enter invalid data
2. Attempt submission
3. Snapshot to see errors
4. Screenshot error messages
5. Correct data
6. Verify error clears

3. 多步骤表单

// Document each step
1. Fill step 1
2. Screenshot before submit
3. Click next
4. Wait for step 2
5. Snapshot new state
6. Repeat for each step

网络监控

1. 跟踪 API 调用

// After user action
browser_network_requests
// Verify expected endpoints called
// Check status codes
// Validate request/response data

2. 性能测试

// Capture network timing
browser_network_requests
// Analyze:
- Request count
- Total transfer size
- Response times
- Failed requests

3. 调试失败的请求

browser_network_requests
// Find failed requests
// Check error messages
// Screenshot current state
// Console messages for errors

加速开发策略

策略 1：创建测试模板

创建可复用的测试模式：

Visual Regression Test Template:
1. Navigate: browser_navigate to {URL}
2. Wait: browser_wait_for for {condition}
3. Baseline: browser_take_screenshot "baseline-{name}.png", fullPage: true
4. [Make changes]
5. Capture: browser_take_screenshot "current-{name}.png", fullPage: true
6. Compare: [Manual or automated comparison]
7. Document: Screenshot any differences

Responsive Test Template:
For viewport in [mobile, tablet, desktop]:
  1. Resize: browser_resize to {viewport dimensions}
  2. Navigate: browser_navigate to {URL}
  3. Wait: browser_wait_for for stability
  4. Snapshot: browser_snapshot
  5. Screenshot: browser_take_screenshot "{page}-{viewport}.png"
  6. Validate: Check layout integrity

Form Test Template:
1. Navigate: browser_navigate to {form URL}
2. Snapshot: browser_snapshot for refs
3. Fill: browser_fill_form with test data
4. Screenshot: "form-filled.png"
5. Submit: browser_click submit button
6. Wait: browser_wait_for for result
7. Verify: Snapshot and screenshot result
8. Check: browser_network_requests for submission

策略 2：自动整理截图

系统地整理截图：

Project Structure:
tests/
  visual/
    baselines/        # Reference screenshots
    results/          # Current test screenshots
    diffs/            # Difference images
    reports/          # HTML reports with comparisons

Naming Convention:
{test-name}_{viewport}_{state}_{date}.png

Examples:
login_desktop_default_20251017.png
cart_mobile_empty_20251017.png
checkout_tablet_error_20251017.png

Metadata File:
screenshot-metadata.json:
{
  "screenshot": "login_desktop_default_20251017.png",
  "timestamp": "2025-10-17T10:30:00Z",
  "url": "https://example.com/login",
  "viewport": {"width": 1920, "height": 1080},
  "browser": "chromium",
  "test": "login_flow",
  "passed": true
}

策略 3：并行进行多浏览器测试

高效地在不同浏览器中测试：

Browser Matrix:
- Chromium (latest)
- Firefox (latest)
- WebKit (latest)

Parallel Execution:
1. Define test suite
2. Configure each browser
3. Run tests in parallel
4. Collect results
5. Compare across browsers
6. Generate cross-browser report

Result Organization:
screenshots/
  chromium/
    homepage.png
    login.png
  firefox/
    homepage.png
    login.png
  webkit/
    homepage.png
    login.png
  comparison/
    homepage-browsers.html
    login-browsers.html

策略 4：自动化视觉回归

自动化视觉对比工作流：

1. Capture Baselines (one-time):
   - Navigate to each page
   - Take reference screenshots
   - Store in baselines/

2. Run Visual Tests:
   - Navigate to each page
   - Take current screenshots
   - Store in results/

3. Compare Images:
   - Pixel-by-pixel comparison
   - Highlight differences
   - Generate diff images
   - Calculate similarity score

4. Generate Report:
   - List all comparisons
   - Show side-by-side views
   - Highlight failures
   - Include metrics

5. Review and Update:
   - Review failures
   - Accept intentional changes
   - Update baselines
   - Fix regressions

策略 5：组件库测试

测试设计系统组件：

Component Test Suite:
For each component:
  1. Navigate to component page
  2. Snapshot for structure
  3. Test each variant:
     - Default
     - Hover
     - Active
     - Disabled
     - Error
  4. Screenshot each state
  5. Verify accessibility
  6. Check responsive behavior

Documentation Generation:
1. Capture all component states
2. Organize by component
3. Generate visual catalog
4. Include code examples
5. Document usage guidelines

Example:
components/
  Button/
    button-default.png
    button-hover.png
    button-active.png
    button-disabled.png
    button-error.png
  Input/
    input-default.png
    input-focus.png
    input-error.png
    input-disabled.png

故障排除

常见问题

截图显示为空白

• 等待页面加载：browser_wait_for
• 检查元素是否可见：browser_snapshot
• 确保页面已完成渲染：添加延迟
• 确认 URL 正确

找不到要交互的元素

• 重新获取快照：browser_snapshot
• 检查元素引用是否为最新
• 等待元素出现：browser_wait_for
• 确认快照中存在该元素

浏览器无法启动

• 运行 browser_install
• 检查 MCP 服务配置
• 确认浏览器二进制文件路径
• 检查系统权限

截图与预期不符

• 检查视口大小：browser_resize
• 等待动画完成：browser_wait_for
• 确保字体加载完成
• 禁用动态内容（时间戳、广告）

表单提交失败

• 确认已填写所有必填字段
• 检查验证错误：browser_snapshot
• 等待提交按钮启用
• 检查控制台中的 JavaScript 错误：browser_console_messages

未捕获网络请求

• 操作后调用 browser_network_requests
• 确保页面已完成请求
• 检查请求是否失败
• 确认请求时间

未处理对话框

• 触发前设置 browser_handle_dialog
• 适当选择接受或取消
• 为提示对话框提供 promptText
• 提前测试对话框

调试工作流

1. 捕获当前状态

1. browser_snapshot - See page structure
2. browser_take_screenshot - See visual state
3. browser_console_messages onlyErrors: true - Check errors
4. browser_network_requests - See network activity

2. 隔离问题

1. Simplify test to minimum reproduction
2. Test in single browser
3. Disable dynamic content
4. Remove variable elements
5. Test step-by-step

3. 记录问题

1. Screenshot before issue
2. Screenshot at failure point
3. Capture console messages
4. Save network requests
5. Note expected vs actual
6. Include reproduction steps

实用示例

示例 1：主页视觉回归

测试主页是否发生视觉变化：

1. Navigate
   browser_navigate
   url: "https://example.com"

2. Wait for page load
   browser_wait_for
   textGone: "Loading..."

3. Capture baseline
   browser_take_screenshot
   filename: "homepage-baseline.png"
   fullPage: true

4. [After code changes, repeat]

5. Capture current
   browser_take_screenshot
   filename: "homepage-current.png"
   fullPage: true

6. Compare images manually or with tools
7. Document differences

示例 2：登录表单测试

测试登录表单功能：

1. Navigate to login
   browser_navigate
   url: "https://example.com/login"

2. Get form structure
   browser_snapshot

3. Fill form
   browser_fill_form
   fields: [
     {
       name: "Email",
       type: "textbox",
       ref: "123",
       value: "[email protected]"
     },
     {
       name: "Password",
       type: "textbox",
       ref: "456",
       value: "password123"
     }
   ]

4. Screenshot filled form
   browser_take_screenshot
   filename: "login-filled.png"

5. Submit
   browser_click
   element: "Sign In button"
   ref: "789"

6. Wait for redirect
   browser_wait_for
   text: "Welcome back"

7. Screenshot success
   browser_take_screenshot
   filename: "login-success.png"

8. Verify network request
   browser_network_requests

示例 3：响应式设计检查

测试响应式布局：

Mobile:
1. Resize to mobile
   browser_resize
   width: 375
   height: 667

2. Navigate
   browser_navigate
   url: "https://example.com"

3. Wait
   browser_wait_for
   time: 2

4. Screenshot
   browser_take_screenshot
   filename: "homepage-mobile.png"
   fullPage: true

Tablet:
5. Resize to tablet
   browser_resize
   width: 768
   height: 1024

6. Navigate
   browser_navigate
   url: "https://example.com"

7. Screenshot
   browser_take_screenshot
   filename: "homepage-tablet.png"
   fullPage: true

Desktop:
8. Resize to desktop
   browser_resize
   width: 1920
   height: 1080

9. Navigate
   browser_navigate
   url: "https://example.com"

10. Screenshot
    browser_take_screenshot
    filename: "homepage-desktop.png"
    fullPage: true

示例 4：组件状态测试

测试按钮状态：

1. Navigate to component library
   browser_navigate
   url: "https://example.com/components/button"

2. Get page structure
   browser_snapshot

3. Default state
   browser_take_screenshot
   filename: "button-default.png"
   element: "Primary button"
   ref: "123"

4. Hover state
   browser_hover
   element: "Primary button"
   ref: "123"

   browser_take_screenshot
   filename: "button-hover.png"
   element: "Primary button"
   ref: "123"

5. Active state
   browser_click
   element: "Primary button"
   ref: "123"

   browser_take_screenshot
   filename: "button-active.png"
   element: "Primary button"
   ref: "123"

6. Snapshot for verification
   browser_snapshot

示例 5：端到端结账流程

测试完整的结账流程：

1. Navigate to product
   browser_navigate
   url: "https://example.com/products/item-123"

2. Add to cart
   browser_snapshot

   browser_click
   element: "Add to Cart button"
   ref: "456"

   browser_wait_for
   text: "Added to cart"

3. Go to cart
   browser_click
   element: "Cart icon"
   ref: "789"

   browser_take_screenshot
   filename: "cart-with-item.png"

4. Proceed to checkout
   browser_click
   element: "Checkout button"
   ref: "101"

5. Fill shipping info
   browser_snapshot

   browser_fill_form
   fields: [
     {name: "Name", type: "textbox", ref: "111", value: "John Doe"},
     {name: "Address", type: "textbox", ref: "222", value: "123 Main St"},
     {name: "City", type: "textbox", ref: "333", value: "New York"},
     {name: "Zip", type: "textbox", ref: "444", value: "10001"}
   ]

6. Screenshot checkout
   browser_take_screenshot
   filename: "checkout-filled.png"
   fullPage: true

7. Complete order
   browser_click
   element: "Place Order button"
   ref: "555"

   browser_wait_for
   text: "Order confirmed"

8. Screenshot confirmation
   browser_take_screenshot
   filename: "order-confirmed.png"
   fullPage: true

9. Verify network requests
   browser_network_requests

示例 6：无障碍测试

测试键盘导航和结构：

1. Navigate to page
   browser_navigate
   url: "https://example.com/form"

2. Capture semantic structure
   browser_snapshot

3. Verify heading hierarchy
   - Check h1 → h2 → h3 order
   - Ensure single h1
   - Verify logical structure

4. Test keyboard navigation
   browser_press_key
   key: "Tab"

   browser_snapshot

   browser_take_screenshot
   filename: "focus-field-1.png"

5. Continue tabbing
   browser_press_key
   key: "Tab"

   browser_snapshot

   browser_take_screenshot
   filename: "focus-field-2.png"

6. Verify all interactive elements reachable
   - Buttons
   - Links
   - Form fields
   - Custom widgets

7. Check ARIA labels
   - Form labels present
   - Button labels descriptive
   - Error messages announced
   - Status updates live

8. Screenshot accessibility tree
   browser_take_screenshot
   filename: "accessibility-structure.png"

示例 7：网络调试

调试失败的 API 调用：

1. Navigate to page
   browser_navigate
   url: "https://example.com/dashboard"

2. Wait for page
   browser_wait_for
   time: 3

3. Check console errors
   browser_console_messages
   onlyErrors: true

4. Check network requests
   browser_network_requests

5. Find failed requests
   - Status: 4xx or 5xx
   - Timeout errors
   - CORS issues

6. Screenshot error state
   browser_take_screenshot
   filename: "api-error-state.png"

7. Retry action
   browser_click
   element: "Refresh button"
   ref: "123"

8. Monitor new requests
   browser_network_requests

9. Document findings
   - Failed endpoint
   - Error message
   - Request/response data
   - Screenshot

示例 8：对话框处理

测试确认对话框：

1. Navigate to page
   browser_navigate
   url: "https://example.com/settings"

2. Trigger delete action
   browser_snapshot

   browser_click
   element: "Delete Account button"
   ref: "123"

3. Handle confirmation
   browser_handle_dialog
   accept: false  # Cancel first time

4. Verify still on page
   browser_snapshot

5. Try again
   browser_click
   element: "Delete Account button"
   ref: "123"

6. Accept this time
   browser_handle_dialog
   accept: true

7. Wait for result
   browser_wait_for
   text: "Account deleted"

8. Screenshot confirmation
   browser_take_screenshot
   filename: "account-deleted.png"

示例 9：标签页管理

测试多标签页工作流：

1. List current tabs
   browser_tabs
   action: "list"

2. Open link in new tab
   browser_click
   element: "Privacy Policy link"
   ref: "123"
   modifiers: ["ControlOrMeta"]

3. Switch to new tab
   browser_tabs
   action: "select"
   index: 1

4. Screenshot new tab
   browser_take_screenshot
   filename: "privacy-policy.png"

5. Switch back
   browser_tabs
   action: "select"
   index: 0

6. Close extra tab
   browser_tabs
   action: "close"
   index: 1

7. Verify single tab
   browser_tabs
   action: "list"

示例 10：动画测试

测试加载动画：

1. Navigate to page
   browser_navigate
   url: "https://example.com/data-heavy"

2. Screenshot loading state
   browser_take_screenshot
   filename: "loading-spinner.png"

3. Wait for loading to complete
   browser_wait_for
   textGone: "Loading..."

4. Wait for animations
   browser_wait_for
   time: 1

5. Screenshot final state
   browser_take_screenshot
   filename: "content-loaded.png"
   fullPage: true

6. Verify stability
   browser_wait_for
   time: 2

   browser_take_screenshot
   filename: "stable-state.png"
   fullPage: true

7. Compare screenshots
   - loading-spinner.png
   - content-loaded.png
   - stable-state.png

快速参考

基本命令

Navigate:
  browser_navigate url: "{URL}"

Snapshot:
  browser_snapshot

Screenshot:
  browser_take_screenshot filename: "{name}.png"

Full Page Screenshot:
  browser_take_screenshot filename: "{name}.png", fullPage: true

Element Screenshot:
  browser_take_screenshot filename: "{name}.png", element: "{description}", ref: "{ref}"

Click:
  browser_click element: "{description}", ref: "{ref}"

Type:
  browser_type element: "{description}", ref: "{ref}", text: "{text}"

Fill Form:
  browser_fill_form fields: [{name, type, ref, value}, ...]

Wait:
  browser_wait_for text: "{text}"
  browser_wait_for textGone: "{text}"
  browser_wait_for time: {seconds}

Resize:
  browser_resize width: {width}, height: {height}

Console:
  browser_console_messages onlyErrors: true

Network:
  browser_network_requests

常见视口大小

Mobile:
  375 x 667   (iPhone SE)
  390 x 844   (iPhone 12/13/14)
  414 x 896   (iPhone 11 Pro Max)
  360 x 640   (Android Small)
  412 x 915   (Android Large)

Tablet:
  768 x 1024  (iPad Portrait)
  1024 x 768  (iPad Landscape)
  810 x 1080  (Android Tablet)

Desktop:
  1280 x 720  (HD)
  1366 x 768  (Laptop)
  1920 x 1080 (Full HD)
  2560 x 1440 (2K)
  3840 x 2160 (4K)

测试组织模板

tests/
  ├── visual/
  │   ├── baselines/
  │   ├── results/
  │   └── diffs/
  ├── e2e/
  │   ├── auth/
  │   ├── checkout/
  │   └── navigation/
  ├── responsive/
  │   ├── mobile/
  │   ├── tablet/
  │   └── desktop/
  └── components/
      ├── buttons/
      ├── forms/
      └── navigation/

reports/
  ├── visual-regression.html
  ├── cross-browser.html
  └── accessibility.html

资源

• Playwright 文档
• Playwright API 参考
• Playwright MCP 服务
• 视觉测试指南
• 最佳实践
• 无障碍测试

---

技能版本：1.0.0 最后更新：2025 年 10 月 技能类别：浏览器自动化、视觉测试、质量保证 兼容对象：Playwright MCP 服务、Chromium、Firefox、WebKit