Playwright 项目结构

成功初始化 Playwright 项目后，你的项目目录中会生成一系列文件和文件夹，本章详细解读每个部分的用途。

初始化的项目结构一览

运行 npm init playwright@latest 后，项目目录中会生成以下结构：

your-project/
├── playwright.config.ts      # Playwright 配置文件
├── package.json              # 项目依赖与脚本
├── package-lock.json         # 依赖锁定文件
├── tests/                    # 测试文件目录
│   └── example.spec.ts       # 示例测试文件
├── tests-examples/           # 更多示例测试（可选）
│   └── demo-todo-app.spec.ts
├── .github/                  # GitHub Actions 配置（可选）
│   └── workflows/
│       └── playwright.yml
└── node_modules/             # npm 依赖包

playwright.config.ts —— 配置文件

这是 Playwright 的核心配置文件，控制测试运行的所有方面。

实例

// 文件路径：playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
// 测试文件目录，相对于此配置文件的路径
testDir: './tests',

// 完全并行运行所有测试
fullyParallel: true,

// 如果源码中遗留了 test.only，在 CI 上则构建失败
forbidOnly: !!process.env.CI,

// CI 环境下失败后重试 2 次，本地不重试
retries: process.env.CI ? 2 : 0,

// CI 环境下使用单线程，本地使用默认多线程
workers: process.env.CI ? 1 : undefined,

// 使用 HTML 报告器
reporter: 'html',

// 所有测试共享的配置
use: {
// 基础 URL，测试中使用相对路径即可
baseURL: 'http://localhost:3000',

// 失败重试时收集 Trace
trace: 'on-first-retry',
},

// 多浏览器/多设备项目配置
projects: [
{
name: 'chromium',
use: { ...devices['Desktop Chrome'] },
},
{
name: 'firefox',
use: { ...devices['Desktop Firefox'] },
},
{
name: 'webkit',
use: { ...devices['Desktop Safari'] },
},
],

// 在测试开始前启动本地开发服务器（可选）
// webServer: {
// command: 'npm run start',
// url: 'http://localhost:3000',
// reuseExistingServer: !process.env.CI,
// },
});

playwright.config.ts 是控制 Playwright 行为的核心入口，第 15 篇会对每个配置项做详细说明。

package.json —— 依赖与脚本

初始化后，package.json 中会新增 Playwright 相关的内容：

实例

{
"devDependencies": {
"@playwright/test": "^1.52.0" // Playwright Test 作为开发依赖
},
"scripts": {
"test": "playwright test" // 可直接运行 npm test
}
}

你也可以添加更多自定义脚本：

实例

{
"scripts": {
"test": "playwright test",
"test:ui": "playwright test --ui",
"test:headed": "playwright test --headed",
"test:chromium": "playwright test --project=chromium",
"test:debug": "playwright test --debug",
"codegen": "playwright codegen"
}
}

tests/ 目录 —— 测试文件

tests/ 目录是默认的测试文件存放位置（由 testDir 配置指定）。

初始化的示例测试文件内容如下：

实例

// 文件路径：tests/example.spec.ts
import { test, expect } from '@playwright/test';

test('has title', async ({ page }) => {
// 导航到 Playwright 官网
await page.goto('https://playwright.dev/');

// 断言页面标题包含 "Playwright"
await expect(page).toHaveTitle(/Playwright/);
});

test('get started link', async ({ page }) => {
// 导航到 Playwright 官网
await page.goto('https://playwright.dev/');

// 点击 "Get started" 链接
await page.getByRole('link', { name: 'Get started' }).click();

// 断言页面上出现了 "Installation" 标题
await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

测试文件命名建议：使用 .spec.ts（TypeScript）或 .spec.js（JavaScript）后缀。

tests-examples/ 目录 —— 更多示例

如果你在初始化时选择了包含示例测试，tests-examples/ 目录中会有一个更完整的测试示例：

demo-todo-app.spec.ts 演示了真实 Todo 应用的完整测试场景，包括添加任务、完成状态切换、过滤功能等。

这是一个很好的学习参考，你可以运行来看看效果：

npx playwright test tests-examples/

.github/workflows/ —— CI 配置

如果你在初始化时选择了添加 GitHub Actions，.github/workflows/playwright.yml 文件会被自动生成。

这个工作流会在每次推送代码或创建 PR 时自动运行 Playwright 测试。

浏览器存放位置

Playwright 安装的浏览器二进制文件不在项目目录中，而是存放在操作系统缓存目录：

操作系统	浏览器存放路径
macOS	~/Library/Caches/ms-playwright/
Windows	%USERPROFILE%\AppData\Local\ms-playwright\
Linux	~/.cache/ms-playwright/

你也可以设置自定义存放路径：

# 设置浏览器安装路径
export PLAYWRIGHT_BROWSERS_PATH=/your/custom/path
npx playwright install

node_modules/ —— 依赖包

Playwright 的核心依赖 @playwright/test 安装在 node_modules/ 中。

依赖内部包含了 Playwright 的完整运行时，包括与浏览器通信的协议层。

除了通过 npm 安装的 Node.js 包外，Playwright 还依赖浏览器二进制文件（存放在系统缓存中），两者缺一不可。

返回顶部

菜鸟教程