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/playwrightPlaywright 的projects测试项目是测试框架中最重要的组织单元之一它允许你在同一个playwright.config.ts中声明多组测试配置——不同浏览器、不同设备、不同环境、不同超时与重试策略甚至带依赖关系的 setup/teardown 流程。读完本篇你将能够完整配置多浏览器/移动端/品牌浏览器项目矩阵理解--project、--no-deps等 CLI 参数的实际行为并从 Playwright 源码层面弄清项目依赖闭包、循环依赖检测与按项目分片的文件收集逻辑。什么是 ProjectProject 是以相同配置运行的一组测试的逻辑分组。典型用途在 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 5deviceDescriptorsSource.json 第 2132 行附近带有isMobile: true与移动 UA而Desktop Chrome第 2694 行附近是纯桌面配置。品牌浏览器需要额外的channel字段msedge对应 Microsoft Edgechrome对应 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 --projectfirefox Running 1 test using 1 worker ✓ [firefox] › example.spec.ts:3:1 › basic test (2s)从源码看CLI 的--project选项定义在 program.tsOnly 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 --projectproduction即可单独验证生产环境。用过滤器把测试切分到不同项目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/**可忽略整个目录。项目依赖Dependenciesdependencies是一个需要先运行的项目名列表。它非常适合把全局 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接口单个项目可用的核心参数如下参数类型说明namestring项目名显示在报告与运行输出中用于--project过滤与依赖引用useUseOptions该项目的测试选项browserName、baseURL、devices[...]展开等dependenciesstring[]需先运行的项目名列表配合--no-deps可忽略teardownstring本项目及依赖者全部结束后运行的清理项目名testDirstring递归扫描测试文件的目录默认配置文件所在目录每个项目可用不同目录testMatchstring\|RegExp\|Array只运行匹配的文件默认 glob 为**/*.(spec|test).?(c|m)[jt]s?(x)testIgnorestring\|RegExp\|Array忽略匹配的文件字符串按 glob 处理优先于testMatchtimeoutnumber每个测试的超时毫秒默认 30 秒retriesnumber失败测试的最大重试次数repeatEachnumber每个测试重复运行的次数用于排查 flaky 测试workersnumber\|string该项目可用的最大并发 worker 数可为逻辑 CPU 核数的百分比如50%受全局workers上限约束fullyParallelboolean让项目内所有文件的所有测试并发运行默认按文件并行、文件内串行grep/grepInvertRegExp\|Array按标题过滤运行/排除测试等效--grep/--grep-invert的项目级配置ignoreSnapshotsboolean跳过toMatchSnapshot()、toHaveScreenshot()等快照断言例如只对 chromium 项目做截图断言outputDirstring运行产物目录默认package.json 所在目录/test-resultssnapshotDir/snapshotPathTemplatestring快照目录与快照路径模板模板支持{projectName}、{testFilePath}等 tokenrespectGitIgnoreboolean搜索测试文件时是否遵循.gitignoremetadataMetadata直接写入测试报告的 JSON 元数据expectobject项目级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.tsCLI 选项定义在 program.ts完整参数与文档注释在 test.d.ts 的TestProject接口中设备参数查 deviceDescriptorsSource.json。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考