原理与核心概念

⚡ TypeScript 的性能优势

TypeScript 版 Playwright 运行在 Node.js 中，与 Playwright Core 同进程调用，无需 Python 版的跨语言 IPC 通信，延迟更低、启动更快。

🔒 为何更稳？

Playwright 使用浏览器原生调试协议，能接收精确事件（网络请求完成、DOM 变更），从而实现可靠的自动等待，避免竞态条件。

Browser

代表一个浏览器实例。通过 launch() 启动或 connect() 连接远程浏览器。

import { chromium } from 'playwright';

const browser = await chromium.launch({
  headless: false,
  slowMo: 100,  // 慢速模式
});

BrowserContext

独立的浏览器会话，类似隐身窗口。拥有独立的 Cookie、Storage、Session。

const context = await browser.newContext({
  viewport: { width: 1280, height: 720 },
  locale: 'zh-CN',
  timezoneId: 'Asia/Shanghai',
});

Page

代表一个标签页，所有操作（导航、点击、输入等）通过 Page 完成。

const page = await context.newPage();
await page.goto('https://example.com');
await page.getByText('登录').click();
await page.getByLabel('用户名').fill('admin');

Locator

Playwright 推荐的元素定位方式。每次操作时重新查找，天然防止陈旧引用。

// 推荐：语义化定位
page.getByRole('button', { name: '提交' });
page.getByLabel('邮箱');
page.getByTestId('submit-btn');

// CSS / XPath
page.locator('button.primary');
page.locator('xpath=//div[@id="app"]');

Test Fixtures

Playwright Test 的依赖注入系统。page、context、browser 都是内置 Fixture。

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

// page 自动注入，每个测试独立
test('my test', async ({ page }) => {
  await page.goto('/');
});

// 自定义 fixture
const myTest = test.extend<{ adminPage: Page }>({
  adminPage: async ({ browser }, use) => {
    const ctx = await browser.newContext({
      storageState: 'admin-auth.json'
    });
    await use(await ctx.newPage());
    await ctx.close();
  },
});

Auto-waiting

所有操作自动等待元素满足条件：可见、稳定、已启用、可接收事件。无需手动 sleep。

// 自动等待按钮可点击
await page.getByRole('button', { name: 'Submit' }).click();

// 自动等待输入框可编辑
await page.getByLabel('Email').fill('[email protected]');

// 显式等待
await page.waitForURL('**/dashboard');

🔧 Playwright Test Runner

TypeScript 版独有的测试运行器，功能远超 Python 的 pytest 集成：

• 完全并行执行 + Worker 进程隔离
• 内置 HTML Reporter
• 测试分片（Sharding）适配 CI
• Test Fixture 依赖注入
• 内置截图对比（Visual Comparisons）
• UI Mode 交互式运行

🎨 完整的类型系统

// 编辑器智能提示 + 编译期类型检查
const locator: Locator = page.getByRole('button');

// API 响应也有类型
interface User { name: string; email: string; }
const res = await page.waitForResponse('**/api/user');
const user = await res.json() as User;

TypeScript 的类型推导让 API 探索变得简单，减少查文档频率。

📷 视觉回归内置

// 截图对比 — Playwright Test 内置
await expect(page).toHaveScreenshot('home.png');
await expect(page.locator('.chart'))
  .toHaveScreenshot('chart.png', {
    maxDiffPixelRatio: 0.01,
  });

🛠 开发者工具

• UI Mode — 交互式测试运行器
• Codegen — 录制操作生成 TS 代码
• Trace Viewer — 时间线回放调试
• VS Code 插件 — 原生编辑器集成
• HTML Reporter — 美观的测试报告

✅ E2E 测试

TypeScript 版的核心场景。Playwright Test 提供完整的测试基础设施：并行执行、重试、分片、报告。

💻 组件测试

实验性支持 React、Vue、Svelte 组件测试，在真实浏览器中测试独立组件。

📸 视觉回归

内置 toHaveScreenshot() 截图对比断言，无需第三方工具即可实现像素级 UI 验证。

📊 API 测试

通过 request fixture 直接发送 HTTP 请求，适合 API 集成测试和合同测试。

🔐 安全测试

拦截网络请求、模拟认证流程，测试 XSS/CSRF 防护。

🚀 性能测试

利用 CDP 访问 Performance API，收集 Web Vitals 指标。

Playwright vs Cypress（重点对比）

在 JS/TS 生态中这是最常见的选型对比。

选 Playwright：

• 需要真正的多浏览器测试
• 需要多标签页、iframe、文件下载
• 需要免费的并行执行方案
• 需要同时支持 Python 等其他语言
• 复杂测试场景（认证、多用户交互）

选 Cypress：

• 团队更熟悉 Cypress 生态
• 需要组件测试（更成熟）
• 偏好其交互式 UI 和开发体验

Playwright TS vs Python 版对比

选 TypeScript 版：

• 前端项目的 E2E 测试（天然亲和）
• 需要 Playwright Test Runner 的完整能力
• 需要内置截图对比、HTML 报告
• 需要 UI Mode 交互调试
• API 更新最快（TypeScript 是第一公民）

选 Python 版：

• 团队以 Python 为主
• 数据采集 / RPA 自动化场景
• 需要与 Python 数据科学生态集成