Playwright Test Projects 完全指南：用 projects 配置多浏览器、多环境与测试依赖-平芜编程栈

Playwright Test Projects 完全指南：用 projects 配置多浏览器、多环境与测试依赖

【免费下载链接】playwrightPlaywright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.项目地址: https://gitcode.com/GitHub_Trending/pl/playwright

Playwright 的projects（测试项目）是测试框架中最重要的组织单元之一：它允许你在同一个playwright.config.ts中声明多组测试配置——不同浏览器、不同设备、不同环境、不同超时与重试策略，甚至带依赖关系的 setup/teardown 流程。读完本篇，你将能够完整配置多浏览器/移动端/品牌浏览器项目矩阵，理解--project、--no-deps等 CLI 参数的实际行为，并从 Playwright 源码层面弄清项目依赖闭包、循环依赖检测与按项目分片的文件收集逻辑。

什么是 Project

Project 是以相同配置运行的一组测试的逻辑分组。典型用途：

在 Chromium、Firefox、WebKit 以及 Google Chrome、Microsoft Edge 等品牌浏览器上运行同一套测试；
在模拟的平板、移动设备（如 Pixel 5、iPhone 12）上运行测试；
用不同配置运行同一批测试，例如已登录/未登录两种状态；
对不同测试分组施加不同的timeout、retries；
把同一组测试分别跑在 staging 和 production 环境；
按 package 或功能模块切分测试。

所有 projects 都配置在playwright.config.ts文件的projects数组中。从类型定义看，TestProject封装了单个项目的全部配置，且顶层TestConfig中的所有属性同样可以在项目级使用——顶层配置作为所有项目的共享默认值，项目级配置按需覆盖。这一点在 packages/playwright/types/test.d.ts 的TestProject接口文档中有明确说明。

配置多浏览器项目

使用 projects 可以覆盖三大引擎浏览器与品牌浏览器。设备参数（viewport、userAgent、deviceScaleFactor、isMobile 等）集中维护在设备注册表 deviceDescriptorsSource.json 中，配置里通过devices['设备名']展开引入。下面是覆盖桌面、移动端与品牌浏览器的完整配置示例：

import { defineConfig, devices } from '@playwright/test'; export default defineConfig({ 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'] }, }, /* 测试品牌浏览器。 */ { name: 'Microsoft Edge', use: { ...devices['Desktop Edge'], channel: 'msedge' }, }, { name: 'Google Chrome', use: { ...devices['Desktop Chrome'], channel: 'chrome' }, }, ], });

要点：

devices对象按设备名索引，配置中...devices['Desktop Chrome']展开后自动设置browserName、视口、UA 等参数。例如注册表中"Pixel 5"（deviceDescriptorsSource.json 第 2132 行附近）带有isMobile: true与移动 UA，而"Desktop Chrome"（第 2694 行附近）是纯桌面配置。
品牌浏览器需要额外的channel字段：msedge对应 Microsoft Edge，chrome对应 Google Chrome；引擎浏览器（chromium/firefox/webkit）则不需要。
项目名（name）会显示在测试报告与运行输出中，是后续--project过滤和依赖引用的标识。

运行 projects

默认行为：运行所有项目。

npx playwright test Running 7 tests using 5 workers ✓ [chromium] › example.spec.ts:3:1 › basic test (2s) ✓ [firefox] › example.spec.ts:3:1 › basic test (2s) ✓ [webkit] › example.spec.ts:3:1 › basic test (2s) ✓ [Mobile Chrome] › example.spec.ts:3:1 › basic test (2s) ✓ [Mobile Safari] › example.spec.ts:3:1 › basic test (2s) ✓ [Microsoft Edge] › example.spec.ts:3:1 › basic test (2s) ✓ [Google Chrome] › example.spec.ts:3:1 › basic test (2s)

使用--project命令行选项只运行指定项目：

npx playwright test --project=firefox Running 1 test using 1 worker ✓ [firefox] › example.spec.ts:3:1 › basic test (2s)

从源码看，CLI 的--project选项定义在 program.ts：Only run tests from the specified list of projects, supports '*' wildcard (default: run all projects)——即该选项可传多个项目名，并支持*通配符。匹配逻辑在 projectUtils.ts 的filterProjects中：项目名做小写化后精确匹配；带*的参数会被转换为正则（wildcardPatternToRegExp）做模式匹配；若没有任何项目命中，会抛出Project(s) ... not found. Available projects: ...并列出所有可用项目名，方便排错。

在 VS Code 测试运行器中，测试默认运行在 Chrome 浏览器上；可以从测试侧边栏播放按钮的下拉菜单中选择其他 profile，或通过Select Default Profile修改默认要运行的浏览器组合。

配置多环境项目

除了浏览器维度，projects 还可以表达环境维度：同一批测试分别针对 staging（允许 2 次重试）与 production（不重试）运行，并通过baseURL指向不同环境：

import { defineConfig } from '@playwright/test'; export default defineConfig({ timeout: 60000, // 超时在所有测试间共享。 projects: [ { name: 'staging', use: { baseURL: 'staging.example.com', }, retries: 2, }, { name: 'production', use: { baseURL: 'production.example.com', }, retries: 0, }, ], });

这里的模式值得注意：顶层timeout被两个项目共享，而retries按环境差异化——staging 环境波动大可以重试，production 验证则要求一次通过。运行npx playwright test --project=production即可单独验证生产环境。

用过滤器把测试切分到不同项目

testMatch/testIgnore可以按文件名把测试切分到不同项目。下面的示例定义了一个共享超时和两个项目："Smoke" 项目运行一小撮测试且不做重试，"Default" 项目运行其余所有测试并允许 2 次重试：

import { defineConfig } from '@playwright/test'; export default defineConfig({ timeout: 60000, // 超时在所有测试间共享。 projects: [ { name: 'Smoke', testMatch: /.*smoke.spec.ts/, retries: 0, }, { name: 'Default', testIgnore: /.*smoke.spec.ts/, retries: 2, }, ], });

从实现看，文件收集逻辑在 projectUtils.ts 的collectFilesForProject中：对每个项目，Playwright 先扫描其testDir（支持.js/.ts/.mjs/.mts/.cjs/.cts/.jsx/.tsx等扩展名），再用createFileMatcher(project.project.testMatch)与createFileMatcher(project.project.testIgnore)分别做匹配与排除，isTest = !testIgnore(file) && testMatch(file)。也就是说testIgnore 优先于 testMatch：先排除、再匹配。此外，testMatch/testIgnore接受字符串（按 glob 解释）或正则；字符串 glob 是相对绝对路径做匹配的（见testIgnore: '**/test-assets/**'可忽略整个目录）。

项目依赖（Dependencies）

dependencies是一个需要先运行的项目名列表。它非常适合把全局 setup 动作写成真正的测试：一个项目依赖某个 setup 项目先跑完。使用项目依赖后，测试报告器会展示 setup 测试，Trace Viewer会记录 setup 的 trace（可以用 inspector 查看 setup 的 DOM 快照），并且可以在 setup 里使用 fixtures。

在下面的示例中，chromium、firefox、webkit 三个项目都依赖 setup 项目：

import { defineConfig, devices } from '@playwright/test'; export default defineConfig({ projects: [ { name: 'setup', testMatch: '**/*.setup.ts', }, { name: 'chromium', use: { ...devices['Desktop Chrome'] }, dependencies: ['setup'], }, { name: 'firefox', use: { ...devices['Desktop Firefox'] }, dependencies: ['setup'], }, { name: 'webkit', use: { ...devices['Desktop Safari'] }, dependencies: ['setup'], }, ], });

运行顺序

依赖项总是先运行，当依赖项目中所有测试通过后，依赖它的项目才开始运行：

setup项目的测试运行；全部通过后，chromium / webkit / firefox 的测试开始；
这三个项目并行运行（受最大 worker 数限制，参见并行测试指南）。

如果存在多个依赖，这些依赖项目会并行先运行；只要任一依赖项目的测试失败，所有依赖它的项目都不会运行。例如 'e2e tests' 同时依赖 'Browser Login' 和 'DataBase'，当 'DataBase' 失败时，'e2e tests' 被整体跳过。

源码印证：projectUtils.ts 中的buildProjectsClosure通过深度优先遍历project.deps与project.teardown构建完整的项目闭包，并把每个项目标记为top-level（直接被选中的项目）或dependency（被依赖拉入的项目）；findTopLevelProjects只返回闭包中的顶层项目，buildDependentProjects则构建反向依赖表以计算"选中某项目时需要连带运行的所有项目"。两个函数都在遍历深度超过 100 时抛出Circular dependency detected between projects.——项目依赖不允许成环，配置出错时会直接报错而不是死循环。

Teardown（反向清理）

在 setup 项目上添加teardown属性即可声明清理项目：teardown 会在所有依赖它的项目运行完毕之后运行，常用于释放 setup 获取的资源（数据库、服务、账号状态等）。teardown与--no-deps的关系在 packages/playwright/types/test.d.ts 中有说明：传入--no-deps时teardown同样被忽略，视同未指定。典型 setup/teardown 配对模式：

import { defineConfig, devices } from '@playwright/test'; export default defineConfig({ projects: [ { name: 'setup', testMatch: /global.setup\.ts/, teardown: 'teardown', }, { name: 'teardown', testMatch: /global.teardown\.ts/, }, { name: 'chromium', use: { ...devices['Desktop Chrome'] }, dependencies: ['setup'], }, // firefox / webkit 同理…… ], });

测试过滤与依赖的关系

所有测试过滤手段——--grep/--grep-invert、--shard、命令行直接按文件位置过滤、test.only()——选择的都是主测试；若这些测试属于带依赖的项目，则依赖项目的所有测试也会运行。要忽略所有依赖与 teardown、只运行直接选中的项目，可传--no-deps选项。该选项在 CLI 中定义于 program.ts：--no-deps—Do not run project dependencies。

Project 可用参数速查

结合 packages/playwright/types/test.d.ts 中的TestProject接口，单个项目可用的核心参数如下：

参数	类型	说明
`name`	`string`	项目名，显示在报告与运行输出中，用于`--project`过滤与依赖引用
`use`	`UseOptions`	该项目的测试选项（`browserName`、`baseURL`、`devices[...]`展开等）
`dependencies`	`string[]`	需先运行的项目名列表，配合`--no-deps`可忽略
`teardown`	`string`	本项目及依赖者全部结束后运行的清理项目名
`testDir`	`string`	递归扫描测试文件的目录，默认配置文件所在目录；每个项目可用不同目录
`testMatch`	`string\\|RegExp\\|Array`	只运行匹配的文件；默认 glob 为`*/.@(spec\|test).?(c\|m)[jt]s?(x)`
`testIgnore`	`string\\|RegExp\\|Array`	忽略匹配的文件，字符串按 glob 处理，优先于`testMatch`
`timeout`	`number`	每个测试的超时（毫秒），默认 30 秒
`retries`	`number`	失败测试的最大重试次数
`repeatEach`	`number`	每个测试重复运行的次数，用于排查 flaky 测试
`workers`	`number\\|string`	该项目可用的最大并发 worker 数，可为逻辑 CPU 核数的百分比（如`'50%'`）；受全局`workers`上限约束
`fullyParallel`	`boolean`	让项目内所有文件的所有测试并发运行（默认按文件并行、文件内串行）
`grep`/`grepInvert`	`RegExp\\|Array`	按标题过滤运行/排除测试，等效`--grep`/`--grep-invert`的项目级配置
`ignoreSnapshots`	`boolean`	跳过`toMatchSnapshot()`、`toHaveScreenshot()`等快照断言，例如只对 chromium 项目做截图断言
`outputDir`	`string`	运行产物目录，默认`<package.json 所在目录>/test-results`
`snapshotDir`/`snapshotPathTemplate`	`string`	快照目录与快照路径模板（模板支持`{projectName}`、`{testFilePath}`等 token）
`respectGitIgnore`	`boolean`	搜索测试文件时是否遵循`.gitignore`
`metadata`	`Metadata`	直接写入测试报告的 JSON 元数据
`expect`	`object`	项目级`expect`断言库配置（超时、截图对比阈值等）

两个实战要点：

workers限流共享资源：当某个项目的所有测试共享单一资源（如一个测试账号）时，可给该项目设置workers: 1防止并发争用，同时全局workers仍约束总并发数：

import { defineConfig } from '@playwright/test'; export default defineConfig({ workers: 10, // 总 worker 上限 projects: [ { name: 'runs in parallel' }, { name: 'one at a time', workers: 1 }, // 本项目串行 ], });

testDir按目录切分：例如 smoke 测试放./smoke-tests，让三个浏览器项目都只扫 smoke 目录，而 "Chrome Stable" 项目扫描整个仓库根目录并指定channel: 'chrome'，从而用一份配置表达"核心子集多引擎 + 全量测试跑稳定 Chrome"的分层策略（见 test.d.ts 中testDir的完整示例）。

参数化项目

Projects 还可以用来参数化测试——通过项目级自定义配置给测试注入不同参数（例如不同的数据源、功能开关组合）。完整做法参见 test-parameterize-js.md 中的 Parameterized Projects 一节：自定义参数声明在use中并写入类型，即可在测试 fixture 里按项目取值。

小结

projects是 Playwright Test 中"按配置切分测试集合"的核心机制：浏览器矩阵、移动设备、品牌浏览器、多环境、Smoke/全量分层、setup/teardown 依赖链，全部由playwright.config.ts中的projects数组表达；
运行层面，--project（支持*通配符与多值）选择项目，--no-deps切断依赖与 teardown，依赖失败会导致依赖方整体跳过；
所有项目级参数都可以在顶层TestConfig中给出共享默认值，项目内按需覆盖；
源码入口：项目过滤与依赖闭包在 projectUtils.ts，CLI 选项定义在 program.ts，完整参数与文档注释在 test.d.ts 的TestProject接口中，设备参数查 deviceDescriptorsSource.json。