Back

Playwright UI 测试入门指南

OpenReplay Team OpenReplay Team

Jun 13, 2025 · 3 min read

Playwright UI 测试入门指南

UI 测试是前端开发的关键环节，确保您的 Web 应用程序从用户角度正常工作。Playwright 是微软开源的自动化框架，已成为 UI 测试的强大工具，既对开发者友好又功能强大。如果您听说过 Playwright 但尚未尝试，本指南将向您展示它的工作原理以及是否适合您当前的工作流程。

核心要点

  • Playwright 通过单一 API 为 Chrome、Firefox 和 Safari 提供跨浏览器测试
  • 自动等待和隔离测试环境减少了不稳定的测试
  • 内置调试工具如 Inspector 和 Trace Viewer 简化了故障排除
  • 支持响应式设计测试、视觉比较和组件测试
  • 轻松集成 CI/CD 流水线实现自动化测试

什么是 Playwright，为什么要用它进行 UI 测试？

Playwright 是一个端到端测试框架，让您能够编写在所有现代浏览器（Chrome、Firefox、Safari）上运行的测试，使用单一 API。与其他测试工具不同，Playwright 专门为现代 Web 应用程序设计，具有使 UI 测试更可靠、更稳定的特性。

UI 测试的主要优势包括：

  • 自动等待：Playwright 在执行操作前自动等待元素变为可操作状态
  • 隔离性：每个测试在全新的浏览器上下文中运行，防止测试间相互干扰
  • 跨浏览器支持：编写一次，使用相同代码在所有浏览器上测试
  • 现代 Web 功能：处理 Shadow DOM、iframe 和现代 Web 组件
  • 强大工具：内置调试工具如 Playwright Inspector 和 Trace Viewer

为 UI 测试设置 Playwright

开始使用 Playwright 很简单。您需要安装 Node.js，然后可以设置新项目：

# 为您的项目创建新目录
mkdir playwright-ui-testing
cd playwright-ui-testing

# 初始化新的 Playwright 项目
npm init playwright@latest

在设置过程中，系统会提示您几个问题。对于 UI 测试，您可以选择 TypeScript，添加 GitHub Actions 工作流，并在提示时安装浏览器。

安装会创建基本的项目结构：

  • playwright.config.ts：测试配置文件
  • tests 目录：测试文件存放位置
  • .github 目录：如果您选择了 GitHub Actions，则包含 CI 配置

编写您的第一个 UI 测试

让我们编写一个简单的 UI 测试，验证电商网站上的产品卡片是否正确显示。在 tests 目录中创建名为 product-ui.spec.ts 的新文件：

import { test, expect } from '@playwright/test';

test('product card displays correctly', async ({ page }) => {
  // 导航到页面
  await page.goto('https://demo-store.playwright.dev');
  
  // 查找产品卡片
  const productCard = page.locator('.product-card').first();
  
  // 验证产品卡片可见
  await expect(productCard).toBeVisible();
  
  // 验证包含预期元素
  await expect(productCard.locator('.product-title')).toBeVisible();
  await expect(productCard.locator('.product-price')).toBeVisible();
  await expect(productCard.locator('button.add-to-cart')).toBeEnabled();
  
  // 提取并验证产品信息
  const title = await productCard.locator('.product-title').textContent();
  console.log(`Found product: ${title}`);
});

此测试：

  1. 打开演示商店网站
  2. 定位产品卡片
  3. 验证关键元素可见且可用
  4. 提取产品标题（展示如何获取信息）

运行 UI 测试

使用 Playwright CLI 运行测试：

npx playwright test product-ui.spec.ts

默认情况下，Playwright 在无头模式下运行测试。要查看浏览器操作：

npx playwright test product-ui.spec.ts --headed

在特定浏览器中运行测试：

npx playwright test product-ui.spec.ts --project=chromium

Playwright 高级 UI 测试

测试响应式设计

Playwright 让跨不同屏幕尺寸测试 UI 变得简单：

test('product card is responsive', async ({ page }) => {
  // 在移动端视口测试
  await page.setViewportSize({ width: 375, height: 667 });
  await page.goto('https://demo-store.playwright.dev');
  
  // 验证移动端布局
  await expect(page.locator('.mobile-menu-button')).toBeVisible();
  
  // 在桌面端视口测试
  await page.setViewportSize({ width: 1280, height: 800 });
  
  // 验证桌面端布局
  await expect(page.locator('.desktop-navigation')).toBeVisible();
});

视觉测试

Playwright 支持视觉比较以捕获意外的 UI 变化：

test('product page visual test', async ({ page }) => {
  await page.goto('https://demo-store.playwright.dev/product/1');
  
  // 与基准截图比较
  await expect(page).toHaveScreenshot('product-page.png');
});

首次运行此测试时，它会创建基准截图。在后续运行中，它会将当前状态与基准进行比较。

测试动态 UI 元素

现代 Web 应用通常具有动态 UI 元素。Playwright 能很好地处理这些：

test('add product to cart updates counter', async ({ page }) => {
  await page.goto('https://demo-store.playwright.dev');
  
  // 获取初始购物车数量
  const cartCount = page.locator('.cart-count');
  await expect(cartCount).toHaveText('0');
  
  // 将产品添加到购物车
  await page.locator('.product-card button.add-to-cart').first().click();
  
  // 验证购物车数量更新
  await expect(cartCount).toHaveText('1');
});

调试 UI 测试

当测试失败时，Playwright 提供强大的调试工具：

Playwright Inspector

启动可视化检查器来调试测试：

PWDEBUG=1 npx playwright test product-ui.spec.ts

检查器让您能够：

  • 逐步执行测试
  • 检查 DOM
  • 查看控制台日志
  • 探索网络请求

Trace Viewer

跟踪记录测试执行的详细信息：

// 在您的 playwright.config.ts 中
export default defineConfig({
  use: {
    trace: 'on-first-retry', // 在失败测试的首次重试时记录跟踪
  },
});

测试失败后，查看跟踪：

npx playwright show-trace test-results/product-ui-test-chromium/trace.zip

跟踪查看器显示：

  • 每步的截图
  • DOM 快照
  • 网络活动
  • 控制台日志

将 Playwright UI 测试集成到您的工作流程

在 CI 中运行测试

Playwright 与 CI 系统配合良好。对于 GitHub Actions，设置向导会创建一个在推送和拉取请求时运行测试的工作流文件。

对于其他 CI 系统，您可以使用 Playwright Docker 镜像：

# GitLab CI 示例
test:
  image: mcr.microsoft.com/playwright:v1.40.0-focal
  script:
    - npm ci
    - npx playwright test
  artifacts:
    when: always
    paths:
      - playwright-report/
    expire_in: 1 week

组件测试

除了页面级测试，Playwright 还支持 React、Vue 和 Svelte 等框架的组件测试：

// React 组件测试示例
import { test, expect } from '@playwright/experimental-ct-react';
import ProductCard from '../components/ProductCard';

test('ProductCard renders correctly', async ({ mount }) => {
  const component = await mount(
    <ProductCard 
      title="Test Product" 
      price="$19.99" 
      image="/test-image.jpg" 
    />
  );
  
  await expect(component).toContainText('Test Product');
  await expect(component).toContainText('$19.99');
  await expect(component.locator('button')).toBeEnabled();
});

常见问题

Playwright 开箱即用地提供跨浏览器支持，并处理多标签页和窗口，这是 Cypress 的难点。Playwright 在跨域测试时也往往限制更少。但是，Cypress 拥有更成熟的生态系统和更友好的测试运行器界面。

不能。Playwright 专为端到端和集成测试设计。使用 Jest 等框架的单元测试对于独立测试单个函数和组件仍然很有价值。

Playwright 允许您存储身份验证状态并在测试间重用。首先，启动浏览器，导航到登录页面，通过填写用户名和密码字段并提交表单来执行登录步骤。登录后，将浏览器的存储状态保存到文件中，该文件包含身份验证数据。在实际测试中，您可以配置 Playwright 使用此存储的身份验证状态，这样就不需要在每个测试前都登录。这种方法加快了测试运行速度并确保会话间的一致性。

是的，Playwright 具有内置的截图比较功能。对于更高级的视觉测试，您可以与 Percy 或 Applitools 等专业工具集成。

您可以通过并行运行来加速 Playwright UI 测试，这是默认启用的。在开发时，使用 --project 标志仅在特定浏览器上运行测试。重用身份验证状态而不是在每个测试中登录也能减少执行时间。此外，使用组件测试为单个 UI 组件提供更快的反馈。

结论

通过将 Playwright 纳入您的测试策略，您可以构建更可靠的前端应用程序，并确信您的 UI 在各种浏览器和设备上都能正常工作。其自动等待机制、隔离特性和强大的调试工具解决了 UI 测试中的许多常见痛点。无论您是测试响应式设计、视觉外观还是动态交互，Playwright 都提供了与现代开发工作流程无缝集成的综合解决方案。

Listen to your bugs 🧘, with OpenReplay

See how users use your app and resolve issues fast.
Self-Host Try Cloud Free
Loved by thousands of developers

More articles from OpenReplay Blog