Playwright浏览器自动化

技能文档

---
name: playwright-automation
title: Playwright浏览器自动化
category: 开发工具
description: 基于Playwright的浏览器自动化测试与网页交互工具。支持页面导航、表单填写、截图、数据抓取、E2E测试、网络拦截、多浏览器兼容等。当用户需要浏览器自动化、网页测试、自动填表、网页截图、数据爬取、Playwright脚本编写时触发。
---

# Playwright浏览器自动化

基于Playwright的专业浏览器自动化与E2E测试工具。

## 技能工作流

### 步骤1：明确自动化目标

向用户确认：
- **任务类型**：E2E测试 / 数据抓取 / 自动填表 / 截图 / 性能监控
- **目标网站**：URL和页面结构
- **浏览器选择**：Chromium / Firefox / WebKit
- **运行模式**：有头模式(调试) / 无头模式(生产)

### 步骤2：环境配置

**安装依赖：**
```bash
# Node.js 项目
npm init -y
npm install playwright
npx playwright install

# Python 项目
pip install playwright
playwright install
```

**项目结构：**
```
e2e-tests/
├── playwright.config.ts    # 配置文件
├── tests/                  # 测试用例
│   ├── login.spec.ts
│   └── checkout.spec.ts
├── pages/                  # Page Object
│   └── LoginPage.ts
├── utils/                  # 工具函数
│   └── helpers.ts
└── reports/                # 测试报告
```

### 步骤3：脚本编写

**基础页面操作：**
```typescript
import { test, expect } from '@playwright/test';

test('示例测试', async ({ page }) => {
  // 导航
  await page.goto('https://example.com');

  // 等待元素出现
  await page.waitForSelector('.content');

  // 点击
  await page.click('button#submit');

  // 填写表单
  await page.fill('input[name="username"]', 'testuser');
  await page.fill('input[name="password"]', 'password123');

  // 选择下拉框
  await page.selectOption('select#city', 'beijing');

  // 勾选复选框
  await page.check('input[type="checkbox"]');

  // 获取文本
  const title = await page.textContent('h1');
  expect(title).toBe('欢迎');

  // 截图
  await page.screenshot({ path: 'screenshot.png', fullPage: true });
});
```

**高级功能：**

网络拦截：
```typescript
await page.route('**/*.png', route => route.abort()); // 拦截图片
await page.route('**/api/**', route => {              // Mock API
  route.fulfill({
    status: 200,
    contentType: 'application/json',
    body: JSON.stringify({ data: 'mocked' })
  });
});
```

多页面处理：
```typescript
const [newPage] = await Promise.all([
  page.context().waitForEvent('page'),
  page.click('a[target="_blank"]')
]);
await newPage.waitForLoadState();
```

文件上传：
```typescript
await page.setInputFiles('input[type="file"]', 'path/to/file.pdf');
```

### 步骤4：Page Object模式

```typescript
// pages/LoginPage.ts
export class LoginPage {
  constructor(private page: Page) {}

  async goto() {
    await this.page.goto('/login');
  }

  async login(username: string, password: string) {
    await this.page.fill('[data-testid="username"]', username);
    await this.page.fill('[data-testid="password"]', password);
    await this.page.click('[data-testid="submit"]');
  }

  async expectError(message: string) {
    await expect(this.page.locator('.error-msg')).toContainText(message);
  }
}
```

### 步骤5：配置与运行

**playwright.config.ts：**
```typescript
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  timeout: 30000,
  retries: 2,
  use: {
    baseURL: 'https://example.com',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
    trace: 'on-first-retry',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'mobile', use: { ...devices['iPhone 14'] } },
  ],
  reporter: [['html'], ['allure-playwright']],
});
```

**运行命令：**
```bash
npx playwright test                    # 运行全部测试
npx playwright test --project=chromium # 指定浏览器
npx playwright test --headed           # 有头模式
npx playwright test --debug            # 调试模式
npx playwright show-report             # 查看报告
npx playwright codegen URL             # 录制生成代码
```

## 最佳实践

- 使用 `data-testid` 属性定位元素，避免依赖CSS类名
- 优先使用 Playwright 内置的 auto-waiting 机制
- 避免使用 `waitForTimeout`，改用 `waitForSelector`
- 并行执行测试提升效率
- CI环境使用 Docker 镜像保证一致性

## 错误处理
- 元素超时：检查选择器是否正确，增加等待策略
- 网络错误：配置重试机制和超时时间
- 浏览器崩溃：检查内存使用，限制并发数
- 登录态丢失：使用 storageState 保存和恢复会话

## 禁止事项
- 不用于爬取受版权保护的内容
- 不绕过网站的安全验证机制
- 不在未经授权的情况下自动化操作他人账户
- 不忽略 robots.txt 规则

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。