playwright-visual-testing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Playwright Visual Testing & Browser Automation

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

A comprehensive skill for browser automation and visual testing using Playwright MCP server integration. This skill enables rapid UI testing, visual regression detection, automated browser interactions, and cross-browser validation for modern web applications.

这是一项基于Playwright MCP Server集成的浏览器自动化与视觉测试综合技能。该技能可实现现代Web应用的快速UI测试、视觉回归检测、自动化浏览器交互以及跨浏览器验证。

When to Use This Skill

何时使用该技能

Use this skill when:

Testing web applications across multiple browsers (Chromium, Firefox, WebKit)
Implementing visual regression testing for UI changes
Automating user interactions for QA and testing
Validating responsive designs across different viewports
Taking screenshots for documentation or bug reports
Testing form submissions and user workflows
Verifying accessibility of web interfaces
Debugging browser-specific issues
Creating automated E2E test suites
Validating web applications before deployment
Testing PWAs and single-page applications
Capturing visual states for design reviews

在以下场景中使用本技能：

在多款浏览器（Chromium、Firefox、WebKit）中测试Web应用
为UI变更实现视觉回归测试
为QA和测试自动化用户交互流程
在不同视口下验证响应式设计
为文档或Bug报告截取截图
测试表单提交与用户工作流
验证Web界面的可访问性
调试浏览器特定问题
创建自动化端到端（E2E）测试套件
部署前验证Web应用
测试PWA与单页应用
为设计评审捕获视觉状态

Core Concepts

核心概念

Playwright Browser Automation Philosophy

Playwright浏览器自动化理念

Playwright provides reliable end-to-end testing for modern web apps:

Auto-wait: Automatically waits for elements to be actionable before interacting
Web-first assertions: Retry assertions until they pass or timeout
Cross-browser: Test on Chromium, Firefox, and WebKit with single API
Accessibility snapshots: Navigate pages using semantic structure, not visual rendering
Visual testing: Compare screenshots to detect visual regressions
Network control: Intercept and mock network requests
Multi-context: Test multiple scenarios in isolated browser contexts

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

Auto-wait：自动等待元素可交互后再执行操作
Web-first assertions：反复重试断言直到通过或超时
Cross-browser：通过统一API在Chromium、Firefox和WebKit上测试
Accessibility snapshots：通过语义结构而非视觉渲染导航页面
Visual testing：对比截图检测视觉回归
Network control：拦截并模拟网络请求
Multi-context：在隔离的浏览器上下文中测试多个场景

Key Playwright Entities

Playwright关键实体

Browser: The browser instance (Chromium, Firefox, WebKit)
Page: A single page/tab in the browser
Locator: Element selector using accessibility tree
Snapshot: Accessibility tree representation of page state
Screenshot: Visual capture of page or element
Network Request: HTTP requests made by the page
Console Messages: Browser console output
Dialog: Browser prompts, alerts, confirms

Browser：浏览器实例（Chromium、Firefox、WebKit）
Page：浏览器中的单个页面/标签页
Locator：使用可访问性树的元素选择器
Snapshot：页面状态的可访问性树表示
Screenshot：页面或特定元素的视觉捕获
Network Request：页面发起的HTTP请求
Console Messages：浏览器控制台输出
Dialog：浏览器提示框、警告框、确认框

Visual Testing Workflow

视觉测试工作流

Navigate to the target page
Wait for page to stabilize (animations, loading)
Capture accessibility snapshot for context
Take screenshot of page or specific elements
Compare against baseline (optional)
Validate visual appearance and functionality
Document results and issues

导航至目标页面
等待页面稳定（动画、加载完成）
捕获可访问性快照以获取上下文
截取页面或特定元素的截图
对比与基准版本（可选）
验证视觉外观与功能
记录结果与问题

Playwright MCP Server Tools Reference

Playwright MCP Server工具参考

Browser Lifecycle Management

浏览器生命周期管理

browser_navigate

Navigate to a URL in the current page.

Parameters:

url: The URL to navigate to (required)

Example:

javascript

url: "https://example.com"

Best Practices:

Use full URLs including protocol (https://)
Wait for navigation to complete before taking actions
Handle redirects and page transitions

在当前页面导航至指定URL。

参数：

url: 要导航的URL（必填）

示例：

javascript

url: "https://example.com"

最佳实践：

使用包含协议的完整URL（如https://）
等待导航完成后再执行后续操作
处理重定向与页面跳转

browser_navigate_back

Navigate back to the previous page in history.

Parameters: None

Example:

javascript

// Navigate back after clicking a link

Use Cases:

Testing navigation flows
Verifying back button behavior
Multi-step form navigation

导航至历史记录中的上一页。

参数：无

示例：

javascript

// 点击链接后返回上一页

适用场景：

测试导航流程
验证返回按钮行为
多步骤表单导航

browser_close

Close the current browser page.

Parameters: None

When to Use:

Clean up after testing
Free system resources
Reset browser state

关闭当前浏览器页面。

参数：无

使用时机：

测试完成后清理环境
释放系统资源
重置浏览器状态

browser_resize

Resize the browser viewport.

Parameters:

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

Common Viewports:

javascript

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

Example:

javascript

width: 375
height: 667

调整浏览器视口大小。

参数：

width: 宽度（像素，必填）
height: 高度（像素，必填）

常见视口尺寸：

javascript

// 移动端
width: 375, height: 667  // iPhone SE
width: 414, height: 896  // iPhone XR

// 平板端
width: 768, height: 1024  // iPad

// 桌面端
width: 1280, height: 720  // HD
width: 1920, height: 1080 // 全高清

示例：

javascript

width: 375
height: 667

Page Inspection & Snapshots

页面检查与快照

browser_snapshot

Capture accessibility snapshot of the current page.

Parameters: None

Returns:

Accessibility tree with semantic structure
Element references (ref) for interactions
Text content and roles
Interactive elements and states

Why Use Snapshots:

Better than screenshots for automation
Semantic understanding of page structure
Element references for precise interactions
Faster than visual parsing
Works without visual rendering

Example Snapshot Structure:

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

捕获当前页面的可访问性快照。

参数：无

返回结果：

带语义结构的可访问性树
用于交互的元素引用（ref）
文本内容与角色
交互元素与状态

为何使用快照：

比截图更适合自动化交互
语义化理解页面结构
用于精准交互的元素引用
比视觉解析更快
无需视觉渲染即可工作

示例快照结构：

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

browser_take_screenshot

Take a screenshot of the current page or element.

Parameters:

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)

Screenshot Types:

Viewport Screenshot (default):

javascript

filename: "homepage-viewport.png"

Full Page Screenshot:

javascript

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

Element Screenshot:

javascript

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

Best Practices:

Use descriptive filenames with context
PNG for UI elements (lossless)
JPEG for photos/images (smaller size)
Full page for documentation
Element screenshots for focused testing

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

参数：

filename: 输出文件名（可选，默认值为page-{timestamp}.png）
type: 图片格式 - "png" 或 "jpeg"（默认：png）
fullPage: 捕获完整可滚动页面（默认：false）
element: 人类可读的元素描述（可选）
ref: 快照中的元素引用（可选，需配合element使用）

截图类型：

视口截图（默认）：

javascript

filename: "homepage-viewport.png"

全页面截图：

javascript

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

元素截图：

javascript

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

最佳实践：

使用带上下文的描述性文件名
UI元素使用PNG（无损压缩）
照片/图片使用JPEG（文件更小）
文档使用全页面截图
聚焦测试使用元素截图

Browser Interaction

浏览器交互

browser_click

Perform click on an element.

Parameters:

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

Examples:

Basic Click:

javascript

element: "Submit button"
ref: "456"

Right Click:

javascript

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

Click with Modifier:

javascript

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

Double Click:

javascript

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

点击指定元素。

参数：

element: 人类可读的元素描述（必填）
ref: 快照中的元素引用（必填）
button: "left"、"right" 或 "middle"（默认：left）
doubleClick: 双击则设为true（默认：false）
modifiers: 修饰键数组 ["Alt", "Control", "ControlOrMeta", "Meta", "Shift"]

示例：

基础点击：

javascript

element: "Submit button"
ref: "456"

右键点击：

javascript

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

带修饰键点击：

javascript

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

双击：

javascript

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

browser_type

Type text into an editable element.

Parameters:

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)

Examples:

Form Input:

javascript

element: "Email textbox"
ref: "123"
text: "user@example.com"

Search with Submit:

javascript

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

Character-by-Character (triggers key handlers):

javascript

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

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

参数：

element: 人类可读的元素描述（必填）
ref: 快照中的元素引用（必填）
text: 要输入的文本（必填）
slowly: 逐字符输入（默认：false）
submit: 输入后按回车键（默认：false）

示例：

表单输入：

javascript

element: "Email textbox"
ref: "123"
text: "user@example.com"

提交搜索：

javascript

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

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

javascript

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

browser_press_key

Press a keyboard key.

Parameters:

key: Key name or character (required)

Common Keys:

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

Examples:

javascript

// Navigation
key: "ArrowDown"

// Submit form
key: "Enter"

// Close dialog
key: "Escape"

// Tab through fields
key: "Tab"

按下键盘按键。

参数：

key: 按键名称或字符（必填）

常见按键：

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

示例：

javascript

// 导航
key: "ArrowDown"

// 提交表单
key: "Enter"

// 关闭对话框
key: "Escape"

// 切换输入框
key: "Tab"

browser_fill_form

Fill multiple form fields at once.

Parameters:

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)

Example:

javascript

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"
  }
]

批量填充多个表单字段。

参数：

fields: 字段对象数组（必填）
  - name: 人类可读的字段名称
  - type: "textbox"、"checkbox"、"radio"、"combobox"、"slider"
  - ref: 快照中的元素引用
  - value: 要设置的值（字符串，复选框使用"true"/"false"）

示例：

javascript

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

Select option from dropdown.

Parameters:

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

Example:

javascript

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

Multi-select:

javascript

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

从下拉菜单中选择选项。

参数：

element: 人类可读的元素描述（必填）
ref: 快照中的元素引用（必填）
values: 要选择的值数组（必填）

示例：

javascript

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

多选：

javascript

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

browser_hover

Hover over an element.

Parameters:

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

Use Cases:

Trigger tooltips
Show dropdown menus
Test hover states
Reveal hidden elements

Example:

javascript

element: "Help icon"
ref: "123"

悬停在元素上。

参数：

element: 人类可读的元素描述（必填）
ref: 快照中的元素引用（必填）

适用场景：

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

示例：

javascript

element: "Help icon"
ref: "123"

browser_drag

Drag and drop between elements.

Parameters:

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

Example:

javascript

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

Use Cases:

Drag-and-drop interfaces
Reordering lists
File uploads
Kanban boards

在元素之间拖放。

参数：

startElement: 源元素描述（必填）
startRef: 源元素引用（必填）
endElement: 目标元素描述（必填）
endRef: 目标元素引用（必填）

示例：

javascript

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

适用场景：

拖放界面
列表重排序
文件上传
看板系统

Advanced Interactions

高级交互

browser_evaluate

Execute JavaScript in page context.

Parameters:

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

Examples:

Page-level Script:

javascript

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

Element-level Script:

javascript

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

Common Use Cases:

javascript

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

在页面上下文中执行JavaScript。

参数：

function: 作为字符串的JavaScript函数（必填）
element: 元素描述（可选）
ref: 元素引用（可选，需配合element使用）

示例：

页面级脚本：

javascript

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

元素级脚本：

javascript

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

常见适用场景：

javascript

// 获取页面标题
function: "() => document.title"

// 滚动至底部
function: "() => window.scrollTo(0, document.body.scrollHeight)"

// 获取元素尺寸
function: "(element) => { const rect = element.getBoundingClientRect(); return { width: rect.width, height: rect.height }; }"

// 设置本地存储
function: "() => localStorage.setItem('theme', 'dark')"

// 获取计算样式
function: "(element) => getComputedStyle(element).backgroundColor"

browser_file_upload

Upload files to file input.

Parameters:

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

Example:

javascript

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

Single File:

javascript

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

Cancel Upload:

javascript

paths: []

向文件输入框上传文件。

参数：

paths: 绝对文件路径数组（必填）
  - 省略或传入空数组可取消文件选择

示例：

javascript

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

单个文件：

javascript

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

取消上传：

javascript

paths: []

Browser State & Debugging

浏览器状态与调试

browser_console_messages

Get console messages from the browser.

Parameters:

onlyErrors: Return only error messages (default: false)

Returns:

All console.log, console.error, console.warn messages
Timestamps and message types
JavaScript errors and stack traces

Examples:

All Messages:

javascript

onlyErrors: false

Errors Only:

javascript

onlyErrors: true

Use Cases:

Debug JavaScript errors
Monitor API failures
Track console warnings
Verify logging behavior

获取浏览器控制台消息。

参数：

onlyErrors: 仅返回错误消息（默认：false）

返回结果：

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

示例：

所有消息：

javascript

onlyErrors: false

仅错误：

javascript

onlyErrors: true

适用场景：

调试JavaScript错误
监控API失败
跟踪控制台警告
验证日志行为

browser_network_requests

Get all network requests since page load.

Parameters: None

Returns:

URL, method, status code
Request/response headers
Timing information
Request/response bodies

Use Cases:

Verify API calls
Check resource loading
Debug failed requests
Monitor performance
Validate analytics tracking

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

参数：无

返回结果：

URL、方法、状态码
请求/响应头
时间信息
请求/响应体

适用场景：

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

browser_handle_dialog

Respond to browser dialogs.

Parameters:

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

Dialog Types:

alert: Information message
confirm: Yes/No choice
prompt: Text input request
beforeunload: Page navigation warning

Examples:

Accept Alert:

javascript

accept: true

Dismiss Confirm:

javascript

accept: false

Answer Prompt:

javascript

accept: true
promptText: "John Doe"

响应浏览器对话框。

参数：

accept: 接受或关闭对话框（必填）
promptText: 提示对话框的输入文本（可选）

对话框类型：

alert：信息提示框
confirm：确认框（是/否选择）
prompt：输入请求框
beforeunload：页面导航警告框

示例：

接受警告框：

javascript

accept: true

关闭确认框：

javascript

accept: false

回答提示框：

javascript

accept: true
promptText: "John Doe"

browser_wait_for

Wait for conditions before proceeding.

Parameters:

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

Examples:

Wait for Text:

javascript

text: "Loading complete"

Wait for Removal:

javascript

textGone: "Loading..."

Fixed Wait:

javascript

time: 2

Best Practices:

Prefer waiting for specific conditions over fixed time
Use for dynamic content loading
Wait for animations to complete
Ensure page stability before screenshots

等待指定条件满足后再继续。

参数：

text: 等待文本出现（可选）
textGone: 等待文本消失（可选）
time: 等待指定秒数（可选）

示例：

等待文本出现：

javascript

text: "Loading complete"

等待文本消失：

javascript

textGone: "Loading..."

固定时长等待：

javascript

time: 2

最佳实践：

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

Tab Management

标签页管理

browser_tabs

Manage browser tabs.

Parameters:

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

Actions:

List Tabs:

javascript

action: "list"

New Tab:

javascript

action: "new"

Close Tab:

javascript

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

Switch Tab:

javascript

action: "select"
index: 0

Use Cases:

Multi-tab workflows
Testing tab-specific features
Opening links in new tabs
Managing multiple sessions

管理浏览器标签页。

参数：

action: "list"、"new"、"close"、"select"（必填）
index: 关闭/选择标签页的索引（可选）

操作：

列出标签页：

javascript

action: "list"

新建标签页：

javascript

action: "new"

关闭标签页：

javascript

action: "close"
index: 1  // 可选，省略则关闭当前标签页

切换标签页：

javascript

action: "select"
index: 0

适用场景：

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

Browser Installation

浏览器安装

browser_install

Install the browser specified in config.

Parameters: None

When to Use:

First-time setup
"Browser not installed" errors
Updating browser version
CI/CD environment setup

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

参数：无

使用时机：

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

Visual Testing Workflow Patterns

视觉测试工作流模式

Pattern 1: Basic Visual Regression Test

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

Scenario: Verify homepage hasn't changed visually

workflow

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

场景： 验证主页视觉效果未发生变更

workflow

1. 导航至页面
   - 使用browser_navigate访问目标URL
   - 等待页面完全加载

2. 捕获基准版本
   - 截取全页面截图
   - 使用browser_snapshot获取上下文
   - 记录可见元素

3. 进行变更（若测试变更）
   - 更新代码、部署
   - 清除缓存

4. 捕获新状态
   - 导航至同一URL
   - 截取完全相同的截图
   - 手动或使用工具对比

5. 验证差异
   - 确认预期变更已呈现
   - 无意外回归
   - 记录发现

Pattern 2: Responsive Design Testing

模式2：响应式设计测试

Scenario: Test layout across devices

workflow

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

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

workflow

1. 定义视口尺寸
   - 移动端：375x667（iPhone SE）
   - 平板端：768x1024（iPad）
   - 桌面端：1920x1080（全高清）

2. 针对每个视口：
   a. 调整浏览器尺寸
      - 使用browser_resize设置对应尺寸

   b. 导航至页面
      - 使用browser_navigate访问URL

   c. 等待布局稳定
      - 使用browser_wait_for等待指定条件

   d. 捕获快照
      - 使用browser_snapshot获取结构

   e. 截取截图
      - 使用browser_take_screenshot并使用描述性名称
      - 文件名中包含视口信息

3. 对比布局
   - 验证响应式断点
   - 检查元素重排
   - 验证移动端导航
   - 确保内容可访问性

4. 记录问题
   - 截图保存问题
   - 记录问题出现的视口
   - 记录预期与实际行为

Pattern 3: Form Testing Workflow

模式3：表单测试工作流

Scenario: Test multi-step form submission

workflow

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

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

workflow

1. 导航至表单页面
   - 使用browser_navigate访问表单URL
   - 使用browser_snapshot获取字段引用

2. 填充表单字段
   - 使用browser_fill_form批量输入
   - 或使用单个browser_type为每个字段输入
   - 包含验证触发操作

3. 测试验证逻辑
   - 提交无效数据
   - 使用browser_snapshot查看错误
   - 截取错误状态截图
   - 验证错误消息已显示

4. 完成有效提交
   - 填写所有必填字段
   - 使用browser_click点击提交按钮
   - 等待成功消息
   - 使用browser_wait_for等待确认文本

5. 验证结果
   - 检查成功页面
   - 验证数据已提交
   - 截取确认页面截图
   - 检查网络请求

Pattern 4: Element-Specific Visual Testing

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

Scenario: Test individual component changes

workflow

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

场景： 测试单个组件变更

workflow

1. 导航至组件页面
   - 使用browser_navigate访问页面
   - 使用browser_snapshot获取结构

2. 定位组件
   - 从快照中找到元素引用
   - 验证组件可见

3. 测试不同状态
   a. 默认状态
      - 截取元素截图
      - 记录初始外观

   b. 悬停状态
      - 使用browser_hover悬停在元素上
      - 截取元素截图
      - 与默认状态对比

   c. 激活/聚焦状态
      - 使用browser_click点击元素
      - 截取元素截图
      - 验证视觉反馈

   d. 错误状态（若适用）
      - 触发验证错误
      - 截取元素截图
      - 验证错误样式

4. 记录状态变化
   - 对比截图
   - 记录预期行为
   - 报告问题

Pattern 5: Cross-Browser Testing

模式5：跨浏览器测试

Scenario: Verify consistency across browsers

workflow

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

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

workflow

1. 定义浏览器矩阵
   - Chromium（Chrome/Edge）
   - Firefox
   - WebKit（Safari）

2. 针对每个浏览器：
   a. 配置浏览器
      - 在MCP Server配置中设置

   b. 运行测试套件
      - 导航至页面
      - 捕获快照
      - 截取截图
      - 测试交互

   c. 记录结果
      - 保存浏览器特定截图
      - 记录渲染差异
      - 记录浏览器特定Bug

3. 对比结果
   - 并排对比截图
   - 功能差异
   - 性能差异
   - CSS渲染问题

4. 解决差异
   - 修复关键跨浏览器Bug
   - 记录可接受的差异
   - 必要时添加浏览器特定样式

Pattern 6: E2E User Journey Testing

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

Scenario: Complete user workflow validation

workflow

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

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

workflow

1. 启动旅程
   - 使用browser_navigate访问着陆页
   - 使用browser_snapshot获取初始状态
   - 截取起始点截图

2. 身份验证
   - 导航至登录页
   - 使用browser_fill_form填充凭据
   - 提交表单
   - 等待重定向
   - 截取登录成功状态截图

3. 主工作流步骤
   针对每个步骤：
   - 操作前捕获快照
   - 执行用户操作
   - 等待操作完成
   - 操作后截取截图
   - 验证预期状态

4. 完成交易
   - 提交最终操作
   - 等待确认
   - 截取成功状态截图
   - 验证完成消息

5. 清理
   - 如需则退出登录
   - 截取最终状态截图
   - 记录旅程结果

Pattern 7: Accessibility Snapshot Testing

模式7：可访问性快照测试

Scenario: Verify semantic structure and accessibility

workflow

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

场景： 验证语义结构与可访问性

workflow

1. 导航至页面
   - 使用browser_navigate访问URL

2. 捕获可访问性快照
   - 使用browser_snapshot获取语义树
   - 检查元素角色
   - 检查标题层级
   - 验证标签与描述

3. 验证结构
   - 正确的标题层级（h1 → h2 → h3）
   - 表单输入框有标签
   - 按钮有可访问名称
   - 交互元素有角色
   - 存在ARIA属性

4. 测试键盘导航
   - 使用browser_press_key "Tab"
   - 每次Tab后捕获快照
   - 验证焦点指示器
   - 确保合理的Tab顺序
   - 测试跳转链接

5. 测试屏幕阅读器体验
   - 检查快照文本内容
   - 验证替代文本存在
   - 检查ARIA实时区域
   - 验证语义地标
   - 确保结构有意义

6. 记录发现
   - 截图保存可访问性树
   - 记录缺失的标签
   - 报告层级问题
   - 提出改进建议

Browser Automation Best Practices

浏览器自动化最佳实践

Screenshot Best Practices

截图最佳实践

Consistent Naming Convention

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

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

Filename Organization

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

Full Page vs Viewport

Use full page for documentation
Use viewport for regression testing
Element screenshots for components
Consider page length for full-page captures

Image Format Selection

PNG: UI elements, text, sharp edges (lossless)
JPEG: Photos, backgrounds, large images (smaller size)
Use PNG by default for testing

一致的命名规范

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

示例：
homepage-desktop-default-1634567890.png
login-mobile-error-1634567891.png
checkout-tablet-success-1634567892.png

文件组织

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

全页面 vs 视口截图

文档使用全页面截图
回归测试使用视口截图
组件测试使用元素截图
全页面截图需考虑页面长度

图片格式选择

PNG：UI元素、文本、锐利边缘（无损）
JPEG：照片、背景、大图片（文件更小）
测试默认使用PNG

Snapshot vs Screenshot Strategy

快照与截图策略

Use Snapshots When:

Automating interactions
Testing functionality
Verifying structure
Checking accessibility
Need element references
Testing dynamic content

Use Screenshots When:

Visual regression testing
Documentation
Bug reports
Design reviews
Stakeholder presentations
Visual comparisons

Use Both When:

Comprehensive testing
Debugging visual issues
Creating test reports
Documenting complex flows

使用快照的场景：

自动化交互
功能测试
验证结构
检查可访问性
需要元素引用
测试动态内容

使用截图的场景：

视觉回归测试
文档
Bug报告
设计评审
向利益相关者展示
视觉对比

同时使用两者的场景：

全面测试
调试视觉问题
生成测试报告
记录复杂流程

Waiting Strategies

等待策略

Wait for Specific Elements

javascript

// Good
browser_wait_for with text: "Data loaded"

// Avoid
browser_wait_for with time: 5

Wait for Animations

javascript

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

Wait for Network Idle

javascript

// Check network requests after waiting
browser_network_requests to verify completion

Dynamic Content

javascript

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

等待特定元素

javascript

// 推荐
browser_wait_for with text: "Data loaded"

// 避免
browser_wait_for with time: 5

等待动画完成

javascript

// 等待加载 spinner 消失
browser_wait_for with textGone: "Loading..."

等待网络空闲

javascript

// 等待后检查网络请求
browser_network_requests 验证请求已完成

动态内容

javascript

// 截图前等待特定文本
browser_wait_for with text: "Results: 42 items"

Interaction Reliability

交互可靠性

Always Use Snapshots First

workflow

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

Verify Element State

javascript

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

Handle Dynamic Elements

javascript

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

Error Recovery

javascript

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

始终先使用快照

workflow

1. browser_snapshot
2. 在快照中找到元素引用
3. 使用引用进行交互
4. 绝不猜测元素引用

验证元素状态

javascript

// 捕获快照验证元素存在
// 检查元素可见且可交互
// 然后执行交互

处理动态元素

javascript

// 等待元素出现
browser_wait_for with text: "Submit"
// 然后捕获新快照
browser_snapshot
// 获取更新后的引用并交互

错误恢复

javascript

// 若交互失败：
1. 截取当前状态截图
2. 捕获控制台消息（browser_console_messages）
3. 检查网络请求（browser_network_requests）
4. 捕获新快照查看当前状态

Form Testing Strategy

表单测试策略

Batch vs Individual Entry

javascript

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

Validation Testing

javascript

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

Multi-Step Forms

javascript

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

批量 vs 单个输入

javascript

// 简单表单使用批量输入（更快）
browser_fill_form 填充所有字段

// 复杂表单使用单个输入（控制更精细）
browser_type 为每个字段输入
browser_wait_for 在每个输入后等待
验证触发的验证逻辑

验证逻辑测试

javascript

// 测试每条验证规则
1. 输入无效数据
2. 尝试提交
3. 快照查看错误
4. 截取错误消息截图
5. 修正数据
6. 验证错误已清除

多步骤表单

javascript

// 记录每个步骤
1. 填写步骤1
2. 提交前截图
3. 点击下一步
4. 等待步骤2加载
5. 捕获新状态快照
6. 对每个步骤重复操作

Network Monitoring

网络监控

Track API Calls

javascript

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

Performance Testing

javascript

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

Debug Failed Requests

javascript

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

跟踪API调用

javascript

// 用户操作后
browser_network_requests
// 验证预期端点已调用
// 检查状态码
// 验证请求/响应数据

性能测试

javascript

// 捕获网络计时数据
browser_network_requests
// 分析：
- 请求数量
- 总传输大小
- 响应时间
- 失败请求

调试失败的请求

javascript

browser_network_requests
// 找到失败的请求
- 状态码：4xx 或 5xx
- 超时错误
- CORS问题

// 截取错误状态截图
browser_take_screenshot
// 控制台消息查看错误
browser_console_messages

Development Acceleration Strategies

开发加速策略

Strategy 1: Test Template Creation

策略1：测试模板创建

Create reusable test patterns:

template

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

创建可复用的测试模式：

template

视觉回归测试模板：
1. 导航：browser_navigate 访问 {URL}
2. 等待：browser_wait_for 等待 {condition}
3. 基准：browser_take_screenshot "baseline-{name}.png", fullPage: true
4. [进行变更]
5. 捕获：browser_take_screenshot "current-{name}.png", fullPage: true
6. 对比：[手动或自动对比]
7. 记录：截图保存差异

响应式测试模板：
针对每个视口 [mobile, tablet, desktop]：
  1. 调整尺寸：browser_resize 设置为 {viewport dimensions}
  2. 导航：browser_navigate 访问 {URL}
  3. 等待：browser_wait_for 等待页面稳定
  4. 快照：browser_snapshot
  5. 截图：browser_take_screenshot "{page}-{viewport}.png"
  6. 验证：检查布局完整性

表单测试模板：
1. 导航：browser_navigate 访问 {form URL}
2. 快照：browser_snapshot 获取引用
3. 填充：browser_fill_form 填充测试数据
4. 截图："form-filled.png"
5. 提交：browser_click 点击提交按钮
6. 等待：browser_wait_for 等待结果
7. 验证：快照与截图验证结果
8. 检查：browser_network_requests 验证提交

Strategy 2: Automated Screenshot Organization

策略2：自动化截图组织

Organize screenshots systematically:

organization

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
}

系统地组织截图：

organization

项目结构：
tests/
  visual/
    baselines/        // 参考截图
    results/          // 当前测试截图
    diffs/            // 差异图片
    reports/          // 包含对比的HTML报告

命名规范：
{test-name}_{viewport}_{state}_{date}.png

示例：
login_desktop_default_20251017.png
cart_mobile_empty_20251017.png
checkout_tablet_error_20251017.png

元数据文件：
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
}

Strategy 3: Parallel Multi-Browser Testing

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

Test across browsers efficiently:

strategy

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

高效地跨浏览器测试：

strategy

浏览器矩阵：
- Chromium（最新版）
- Firefox（最新版）
- WebKit（最新版）

并行执行：
1. 定义测试套件
2. 配置每个浏览器
3. 并行运行测试
4. 收集结果
5. 跨浏览器对比
6. 生成跨浏览器报告

结果组织：
screenshots/
  chromium/
    homepage.png
    login.png
  firefox/
    homepage.png
    login.png
  webkit/
    homepage.png
    login.png
  comparison/
    homepage-browsers.html
    login-browsers.html

Strategy 4: Visual Regression Automation

策略4：视觉回归自动化

Automate visual comparison workflow:

automation

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

自动化视觉对比工作流：

automation

1. 捕获基准版本（一次性）：
   - 导航至每个页面
   - 截取参考截图
   - 存储在 baselines/

2. 运行视觉测试：
   - 导航至每个页面
   - 截取当前截图
   - 存储在 results/

3. 对比图片：
   - 逐像素对比
   - 高亮差异
   - 生成差异图片
   - 计算相似度得分

4. 生成报告：
   - 列出所有对比
   - 显示并排视图
   - 高亮失败项
   - 包含指标

5. 评审与更新：
   - 评审失败项
   - 接受有意的变更
   - 更新基准版本
   - 修复回归问题

Strategy 5: Component Library Testing

策略5：组件库测试

Test design system components:

strategy

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

测试设计系统组件：

strategy

组件测试套件：
针对每个组件：
  1. 导航至组件页面
  2. 快照获取结构
  3. 测试每个变体：
     - 默认
     - 悬停
     - 激活
     - 禁用
     - 错误
  4. 截取每个状态的截图
  5. 验证可访问性
  6. 检查响应式行为

文档生成：
1. 捕获所有组件状态
2. 按组件组织
3. 生成视觉目录
4. 包含代码示例
5. 记录使用指南

示例：
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

Troubleshooting

故障排除

Common Issues

常见问题

Screenshot appears blank

Wait for page to load: browser_wait_for
Check if element is visible: browser_snapshot
Ensure page has rendered: Add delay
Verify URL is correct

Element not found for interaction

Take fresh snapshot: browser_snapshot
Check element ref is current
Wait for element to appear: browser_wait_for
Verify element exists in snapshot

Browser not launching

Run browser_install
Check MCP server configuration
Verify browser binary path
Check system permissions

Screenshot differs from expected

Check viewport size: browser_resize
Wait for animations: browser_wait_for
Ensure font loading complete
Disable dynamic content (timestamps, ads)

Form submission fails

Verify all required fields filled
Check validation errors: browser_snapshot
Wait for submit button to be enabled
Check console for JavaScript errors: browser_console_messages

Network requests not captured

Call browser_network_requests after action
Ensure page has completed requests
Check for request failures
Verify request timing

Dialog not handled

Set up browser_handle_dialog before triggering
Accept or dismiss appropriately
Provide promptText for prompt dialogs
Test dialog in advance

截图显示空白

等待页面加载：使用browser_wait_for
检查元素是否可见：使用browser_snapshot
确保页面已渲染：添加延迟
验证URL正确

交互时找不到元素

捕获新快照：使用browser_snapshot
检查元素引用是否为最新
等待元素出现：使用browser_wait_for
验证元素在快照中存在

浏览器无法启动

运行browser_install
检查MCP Server配置
验证浏览器二进制文件路径
检查系统权限

截图与预期不符

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

表单提交失败

验证所有必填字段已填充
检查验证错误：使用browser_snapshot
等待提交按钮启用
检查控制台JavaScript错误：使用browser_console_messages

未捕获到网络请求

操作后调用browser_network_requests
确保页面请求已完成
检查请求是否失败
验证请求计时

未处理对话框

触发前设置browser_handle_dialog
正确接受或关闭
为提示框提供promptText
提前测试对话框

Debugging Workflow

调试工作流

Capture Current State

workflow

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

Isolate Issue

workflow

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

Document Problem

workflow

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

捕获当前状态

workflow

1. browser_snapshot - 查看页面结构
2. browser_take_screenshot - 查看视觉状态
3. browser_console_messages onlyErrors: true - 检查错误
4. browser_network_requests - 查看网络活动

隔离问题

workflow

1. 将测试简化为最小复现步骤
2. 在单个浏览器中测试
3. 禁用动态内容
4. 移除可变元素
5. 逐步测试

记录问题

workflow

1. 问题出现前截图
2. 失败点截图
3. 捕获控制台消息
4. 保存网络请求
5. 记录预期与实际行为
6. 包含复现步骤

Practical Examples

实用示例

Example 1: Homepage Visual Regression

示例1：主页视觉回归测试

Test homepage hasn't visually changed:

test

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

测试主页视觉效果未变更：

test

1. 导航
   browser_navigate
   url: "https://example.com"

2. 等待页面加载
   browser_wait_for
   textGone: "Loading..."

3. 捕获基准版本
   browser_take_screenshot
   filename: "homepage-baseline.png"
   fullPage: true

4. [代码变更后重复步骤1-3]

5. 捕获当前版本
   browser_take_screenshot
   filename: "homepage-current.png"
   fullPage: true

6. 手动或使用工具对比图片
7. 记录差异

Example 2: Login Form Testing

示例2：登录表单测试

Test login form functionality:

test

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: "test@example.com"
     },
     {
       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

测试登录表单功能：

test

1. 导航至登录页
   browser_navigate
   url: "https://example.com/login"

2. 获取表单结构
   browser_snapshot

3. 填充表单
   browser_fill_form
   fields: [
     {
       name: "Email",
       type: "textbox",
       ref: "123",
       value: "test@example.com"
     },
     {
       name: "Password",
       type: "textbox",
       ref: "456",
       value: "password123"
     }
   ]

4. 截取已填充表单的截图
   browser_take_screenshot
   filename: "login-filled.png"

5. 提交
   browser_click
   element: "Sign In button"
   ref: "789"

6. 等待重定向
   browser_wait_for
   text: "Welcome back"

7. 截取成功状态截图
   browser_take_screenshot
   filename: "login-success.png"

8. 验证网络请求
   browser_network_requests

Example 3: Responsive Design Check

示例3：响应式设计检查

Test responsive layout:

test

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

测试响应式布局：

test

移动端：
1. 调整为移动端尺寸
   browser_resize
   width: 375
   height: 667

2. 导航
   browser_navigate
   url: "https://example.com"

3. 等待
   browser_wait_for
   time: 2

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

平板端：
5. 调整为平板端尺寸
   browser_resize
   width: 768
   height: 1024

6. 导航
   browser_navigate
   url: "https://example.com"

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

桌面端：
8. 调整为桌面端尺寸
   browser_resize
   width: 1920
   height: 1080

9. 导航
   browser_navigate
   url: "https://example.com"

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

Example 4: Component State Testing

示例4：组件状态测试

Test button states:

test

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

测试按钮状态：

test

1. 导航至组件库
   browser_navigate
   url: "https://example.com/components/button"

2. 获取页面结构
   browser_snapshot

3. 默认状态
   browser_take_screenshot
   filename: "button-default.png"
   element: "Primary button"
   ref: "123"

4. 悬停状态
   browser_hover
   element: "Primary button"
   ref: "123"

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

5. 激活状态
   browser_click
   element: "Primary button"
   ref: "123"

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

6. 快照验证
   browser_snapshot

Example 5: E2E Checkout Flow

示例5：端到端结账流程

Test complete checkout process:

test

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

测试完整结账流程：

test

1. 导航至商品页
   browser_navigate
   url: "https://example.com/products/item-123"

2. 添加至购物车
   browser_snapshot

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

   browser_wait_for
   text: "Added to cart"

3. 进入购物车
   browser_click
   element: "Cart icon"
   ref: "789"

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

4. 继续结账
   browser_click
   element: "Checkout button"
   ref: "101"

5. 填写配送信息
   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. 截取结账页面截图
   browser_take_screenshot
   filename: "checkout-filled.png"
   fullPage: true

7. 完成订单
   browser_click
   element: "Place Order button"
   ref: "555"

   browser_wait_for
   text: "Order confirmed"

8. 截取确认页面截图
   browser_take_screenshot
   filename: "order-confirmed.png"
   fullPage: true

9. 验证网络请求
   browser_network_requests

Example 6: Accessibility Testing

示例6：可访问性测试

Test keyboard navigation and structure:

test

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"

测试键盘导航与结构：

test

1. 导航至页面
   browser_navigate
   url: "https://example.com/form"

2. 捕获语义结构
   browser_snapshot

3. 验证标题层级
   - 检查h1 → h2 → h3顺序
   - 确保只有一个h1
   - 验证逻辑结构

4. 测试键盘导航
   browser_press_key
   key: "Tab"

   browser_snapshot

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

5. 继续切换焦点
   browser_press_key
   key: "Tab"

   browser_snapshot

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

6. 验证所有交互元素可被访问
   - 按钮
   - 链接
   - 表单字段
   - 自定义组件

7. 检查ARIA标签
   - 表单标签存在
   - 按钮描述性标签
   - 错误消息可被播报
   - 状态更新为实时区域

8. 截取可访问性树截图
   browser_take_screenshot
   filename: "accessibility-structure.png"

Example 7: Network Debugging

示例7：网络调试

Debug failed API calls:

test

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

调试失败的API调用：

test

1. 导航至页面
   browser_navigate
   url: "https://example.com/dashboard"

2. 等待页面加载
   browser_wait_for
   time: 3

3. 检查控制台错误
   browser_console_messages
   onlyErrors: true

4. 检查网络请求
   browser_network_requests

5. 找到失败的请求
   - 状态码：4xx 或 5xx
   - 超时错误
   - CORS问题

6. 截取错误状态截图
   browser_take_screenshot
   filename: "api-error-state.png"

7. 重试操作
   browser_click
   element: "Refresh button"
   ref: "123"

8. 监控新请求
   browser_network_requests

9. 记录发现
   - 失败的端点
   - 错误消息
   - 请求/响应数据
   - 截图

Example 8: Dialog Handling

示例8：对话框处理

Test confirmation dialogs:

test

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"

测试确认对话框：

test

1. 导航至页面
   browser_navigate
   url: "https://example.com/settings"

2. 触发删除操作
   browser_snapshot

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

3. 处理确认框
   browser_handle_dialog
   accept: false  // 第一次取消

4. 验证仍在当前页面
   browser_snapshot

5. 再次尝试
   browser_click
   element: "Delete Account button"
   ref: "123"

6. 本次接受
   browser_handle_dialog
   accept: true

7. 等待结果
   browser_wait_for
   text: "Account deleted"

8. 截取确认页面截图
   browser_take_screenshot
   filename: "account-deleted.png"

Example 9: Tab Management

示例9：标签页管理

Test multi-tab workflow:

test

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"

测试多标签页工作流：

test

1. 列出当前标签页
   browser_tabs
   action: "list"

2. 在新标签页打开链接
   browser_click
   element: "Privacy Policy link"
   ref: "123"
   modifiers: ["ControlOrMeta"]

3. 切换至新标签页
   browser_tabs
   action: "select"
   index: 1

4. 截取新标签页截图
   browser_take_screenshot
   filename: "privacy-policy.png"

5. 切换回原标签页
   browser_tabs
   action: "select"
   index: 0

6. 关闭额外标签页
   browser_tabs
   action: "close"
   index: 1

7. 验证仅存在单个标签页
   browser_tabs
   action: "list"

Example 10: Animation Testing

示例10：动画测试

Test loading animations:

test

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

测试加载动画：

test

1. 导航至页面
   browser_navigate
   url: "https://example.com/data-heavy"

2. 截取加载状态截图
   browser_take_screenshot
   filename: "loading-spinner.png"

3. 等待加载完成
   browser_wait_for
   textGone: "Loading..."

4. 等待动画完成
   browser_wait_for
   time: 1

5. 截取最终状态截图
   browser_take_screenshot
   filename: "content-loaded.png"
   fullPage: true

6. 验证页面稳定
   browser_wait_for
   time: 2

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

7. 对比截图
   - loading-spinner.png
   - content-loaded.png
   - stable-state.png

Quick Reference

快速参考

Essential Commands

核心命令

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

导航:
  browser_navigate url: "{URL}"

快照:
  browser_snapshot

截图:
  browser_take_screenshot filename: "{name}.png"

全页面截图:
  browser_take_screenshot filename: "{name}.png", fullPage: true

元素截图:
  browser_take_screenshot filename: "{name}.png", element: "{description}", ref: "{ref}"

点击:
  browser_click element: "{description}", ref: "{ref}"

输入:
  browser_type element: "{description}", ref: "{ref}", text: "{text}"

填充表单:
  browser_fill_form fields: [{name, type, ref, value}, ...]

等待:
  browser_wait_for text: "{text}"
  browser_wait_for textGone: "{text}"
  browser_wait_for time: {seconds}

调整尺寸:
  browser_resize width: {width}, height: {height}

控制台:
  browser_console_messages onlyErrors: true

网络:
  browser_network_requests

Common Viewport Sizes

常见视口尺寸

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)

移动端:
  375 x 667   (iPhone SE)
  390 x 844   (iPhone 12/13/14)
  414 x 896   (iPhone 11 Pro Max)
  360 x 640   (Android 小屏)
  412 x 915   (Android 大屏)

平板端:
  768 x 1024  (iPad 竖屏)
  1024 x 768  (iPad 横屏)
  810 x 1080  (Android 平板)

桌面端:
  1280 x 720  (HD)
  1366 x 768  (笔记本)
  1920 x 1080 (全高清)
  2560 x 1440 (2K)
  3840 x 2160 (4K)

Test Organization Template

测试组织模板

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

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

Resources

资源

Skill Version: 1.0.0 Last Updated: October 2025 Skill Category: Browser Automation, Visual Testing, Quality Assurance Compatible With: Playwright MCP Server, Chromium, Firefox, WebKit

技能版本: 1.0.0 最后更新: 2025年10月 技能分类: 浏览器自动化、视觉测试、质量保证 兼容环境: Playwright MCP Server、Chromium、Firefox、WebKit