Playwright 安装配置文件详解

Playwright 安装&配置文件详解

环境准备

Node.js 14.0+（推荐 LTS 版本）
npm（推荐使用最新版）
支持 Windows、macOS、Linux

一步到位的官方推荐安装方式

1. 进入你的项目目录

# Windows
cd 路径\到\你的项目
# macOS/Linux
cd /path/to/your/project

2. 初始化 Playwright 项目

npm init playwright@latest

操作提示：
在出现选项时，请用键盘的上下方向键选择你想要的内容，然后按**回车（Enter）**键确认。

执行后会进入交互式引导，每个选项说明如下：

选项1：Do you want to use TypeScript or JavaScript?

TypeScript：推荐（如果你的项目文件是 .ts 结尾，选这个）
JavaScript：如果你只用 .js 文件可以选这个

选项2：Where to put your end-to-end tests?

输入测试用例目录名，建议用 tests 或 e2e（如果已有同名目录会复用）

选项3：Add a GitHub Actions workflow? (y/N)

y：生成 GitHub Actions 工作流文件，方便 CI 自动化
n：不生成（本地开发可选 n）

选项4：Install Playwright browsers? (Y/n)

Y：自动下载 Chromium、Firefox、Webkit 三大主流浏览器（推荐）
n：跳过，后续可手动 npx playwright install

3. 运行初始化命令后的效果

Playwright 会自动：

初始化 npm 项目（如无 package.json 会自动创建）
安装 Playwright 及相关依赖
下载主流浏览器
生成测试配置和示例代码

生成的目录结构示例

playwright/
├── playwright.config.ts           # Playwright 测试配置文件
├── package.json                   # 项目依赖与脚本
├── package-lock.json              # 依赖锁定
├── node_modules/                  # 依赖包
├── tests/                         # 主测试目录
│   └── example.spec.ts            # 官方示例测试
├── tests-examples/                # 额外官方示例
│   └── demo-todo-app.spec.ts      # TodoMVC 端到端测试
├── .gitignore                     # 忽略文件
└── README.md                      # 项目说明

详细文件与目录说明

playwright.config.ts

Playwright 的主配置文件。
作用：配置测试目录、并发、重试、报告、支持的浏览器（Chromium/Firefox/Webkit）等。

详细配置说明：

import { defineConfig, devices } from '@playwright/test';export default defineConfig({// 测试目录配置testDir: './tests',                    // 测试文件目录testMatch: '**/*.spec.ts',             // 测试文件匹配模式timeout: 30000,                        // 单个测试超时时间（毫秒）// 全局设置globalTimeout: 600000,                 // 所有测试总超时时间expect: {timeout: 5000,                       // expect 断言超时时间toHaveScreenshot: { maxDiffPixels: 100 }, // 截图对比配置},// 并发配置workers: process.env.CI ? 1 : undefined, // CI 环境单进程，本地多进程fullyParallel: true,                   // 是否完全并行运行测试// 重试配置retries: process.env.CI ? 2 : 0,       // CI 环境失败重试 2 次// 报告配置reporter: [['html'],                            // HTML 报告['list']                             // 命令行报告],// 浏览器配置use: {// 基础配置baseURL: 'http://localhost:3000',    // 基础 URLtrace: 'on-first-retry',             // 失败时记录追踪screenshot: 'only-on-failure',       // 失败时截图// 浏览器配置viewport: { width: 1280, height: 720 }, // 视窗大小ignoreHTTPSErrors: true,             // 忽略 HTTPS 错误video: 'on-first-retry',             // 失败时录制视频// 上下文配置locale: 'zh-CN',                     // 浏览器语言timezoneId: 'Asia/Shanghai',         // 时区geolocation: { longitude: 116.3, latitude: 39.9 }, // 地理位置permissions: ['geolocation'],        // 权限设置},// 多浏览器配置projects: [{name: 'chromium',use: { ...devices['Desktop Chrome'] },},{name: 'firefox',use: { ...devices['Desktop Firefox'] },},{name: 'webkit',use: { ...devices['Desktop Safari'] },},// 移动设备配置{name: 'Mobile Chrome',use: { ...devices['Pixel 5'] },},{name: 'Mobile Safari',use: { ...devices['iPhone 12'] },},],// 输出配置outputDir: 'test-results/',            // 测试结果输出目录// 其他配置preserveOutput: 'always',              // 保留输出文件forbidOnly: !!process.env.CI,          // CI 环境禁止 .onlyquiet: false,                          // 是否静默输出
});

配置项详解：
1. 测试目录配置
  - testDir: 指定测试文件所在目录
  - testMatch: 指定测试文件匹配模式
  - timeout: 单个测试用例超时时间
2. 全局设置
  - globalTimeout: 所有测试的总超时时间
  - expect: 断言相关配置
    - timeout: 断言等待超时时间
    - toHaveScreenshot: 截图对比配置
3. 并发配置
  - workers: 并行运行的测试进程数
  - fullyParallel: 是否允许完全并行运行
4. 重试配置
  - retries: 测试失败时的重试次数
  - 建议在 CI 环境设置重试，本地开发可不设置
5. 报告配置
  - reporter: 测试报告格式
  - 支持多种报告格式：html、list、dot、json 等
  - 可同时使用多个报告器
6. 浏览器配置
  - use: 全局浏览器配置
    - baseURL: 基础 URL，所有测试都会基于此 URL
    - trace: 追踪记录配置
    - screenshot: 截图配置
    - viewport: 视窗大小
    - video: 视频录制配置
    - locale: 浏览器语言
    - timezoneId: 时区设置
    - geolocation: 地理位置模拟
    - permissions: 浏览器权限设置
7. 多浏览器配置
  - projects: 定义多个测试项目
  - 每个项目可以配置不同的浏览器和设备
  - 支持桌面端和移动端设备
  - 可以使用预定义的设备配置
8. 输出配置
  - outputDir: 测试结果输出目录
  - preserveOutput: 输出文件保留策略
9. 其他配置
  - forbidOnly: 是否禁止使用 .only
  - quiet: 是否静默输出
  - use: 全局使用配置
最佳实践建议：
1. 根据项目需求选择合适的配置项
2. CI 环境和本地开发环境使用不同配置
3. 合理设置超时时间和重试次数
4. 使用多浏览器配置确保跨浏览器兼容性
5. 配置适当的报告格式便于问题分析
6. 合理使用追踪、截图和视频录制功能

package.json
- Node.js 项目的依赖和脚本清单。
- 作用：记录项目依赖（如 @playwright/test）、脚本命令、项目描述等。
- 主要内容：
  - devDependencies：Playwright 及类型依赖。
  - scripts：可自定义测试命令。
  - description、author、license 等元信息。
package-lock.json
- 依赖锁定文件。
- 作用：确保团队成员安装的依赖版本一致，避免"我的能跑你的不能跑"。
node_modules/
- 依赖包目录。
- 作用：存放所有通过 npm 安装的依赖。
- 注意：此目录通常不需要提交到 git。
tests/
- 主测试目录。
- 作用：存放你的 E2E 测试用例。
- 默认包含 example.spec.ts，内容演示 Playwright 的基本用法。
- 你可以在此目录下添加、组织自己的测试文件。
tests/example.spec.ts
- 官方自动生成的示例测试。
- 作用：帮助你快速了解 Playwright 的基本断言、页面操作等。
- 内容示例：
  - 访问官网，断言标题
  - 点击"Get started"链接，断言页面内容
tests-examples/
- 额外官方示例目录。
- 作用：提供更复杂的端到端测试案例，便于参考和学习。
tests-examples/demo-todo-app.spec.ts
- TodoMVC 应用的完整端到端测试。
- 作用：演示 Playwright 如何测试真实的前端应用，包括增删查改、状态断言等。
- 内容较长，适合进阶学习。

4. 运行你的第一个测试

npx playwright test

会自动运行 tests/ 目录下的所有测试用例
首次运行会自动打开浏览器下载和测试报告

5. 常见问题与建议

TypeScript/JavaScript 选错了怎么办？
- 重新运行 npm init playwright@latest，或手动调整文件后缀和配置
已有测试目录/配置怎么办？
- 初始化时如遇同名文件，Playwright 会提示是否覆盖，谨慎选择
浏览器没装全？
- 可随时运行 npx playwright install 补装
如何自定义配置？
- 修改 playwright.config.ts

6. 参考：自动生成的示例测试内容

tests/example.spec.ts 示例：

import { test, expect } from '@playwright/test';test('has title', async ({ page }) => {await page.goto('https://playwright.dev/');await expect(page).toHaveTitle(/Playwright/);
});test('get started link', async ({ page }) => {await page.goto('https://playwright.dev/');await page.getByRole('link', { name: 'Get started' }).click();await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});