自动化测试 / 系统课时
理解测试项目结构
理解测试项目结构
本课分析 Playwright 项目的主要文件,让你知道测试代码、配置和运行结果分别存放在哪里。我们会以一个最小 JavaScript 项目为例,运行一条测试,并确认配置文件、HTML 报告和调试产物各自的作用与位置。
学习目标
- 认识 Playwright 项目目录,区分源码文件与运行产物。
- 理解配置文件如何控制测试发现、超时和报告输出。
- 能运行一个最小测试,并找到报告和调试文件。
基础目录结构
一个常见的 Playwright JavaScript 项目以 playwright-demo/ 为根目录。测试脚本、配置文件和依赖声明属于项目源码,测试结果与报告则通常在执行后生成。
| 文件或目录 | 主要作用 |
|---|---|
tests/example.spec.js |
编写测试用例与断言 |
playwright.config.js |
管理测试目录、浏览器、超时和报告配置 |
package.json |
声明项目依赖、模块类型和 npm 脚本 |
test-results/ |
保存测试执行过程中的附件等产物 |
playwright-report/ |
保存 HTML 测试报告 |

实际项目还可能包含 node_modules/、package-lock.json、tests-examples/ 等内容。其中 node_modules/ 存放安装的依赖,锁文件用于记录依赖版本;这些文件不需要直接编写测试逻辑。
配置文件作用
playwright.config.js 用于统一管理测试配置,例如浏览器、超时时间和报告方式。测试运行器会读取该文件,让项目中的多个测试用例使用一致的运行规则。
下面沿用原来的 defineConfig 写法,在 30 秒超时设置上补充测试目录和输出位置。示例使用 ES Module,项目的 package.json 应设置 "type": "module",并已安装 @playwright/test。
import { defineConfig } from '@playwright/test';
// 明确测试发现范围和两类运行产物的配置
export default defineConfig({
testDir: './tests',
timeout: 30000,
reporter: 'html',
outputDir: 'test-results',
});这几个配置项分别控制不同的行为:
testDir:从项目根目录下的tests/寻找测试文件。timeout:单个测试的超时上限为 30000 毫秒,即 30 秒。reporter:使用 HTML 报告器展示测试结果。outputDir:指定测试附件等运行产物的保存目录。
需要区分 outputDir 和 HTML 报告目录。这里的 outputDir 指向 test-results/,但 HTML 报告默认保存在独立的 playwright-report/ 中。若要修改 HTML 报告位置,需要配置 HTML 报告器的 outputFolder,而不是只修改 outputDir。
配置文件通常由项目统一维护。新增测试时,只要将文件放在匹配的测试目录中,就不需要为每个用例重复编写这些设置。
运行一个最小测试
为了确认项目结构可以实际工作,在 tests/ 目录下创建 example.spec.js。下面的测试直接设置页面内容,不依赖外部网站,适合验证目录与配置是否正确。
import { test, expect } from '@playwright/test';
test('首页标题可见', async ({ page }) => {
// 使用本地页面内容,排除外部网络波动
await page.setContent('<h1>Playwright Demo</h1>');
await expect(page.getByRole('heading', { name: 'Playwright Demo' })).toBeVisible();
});测试文件中的 test() 定义用例,expect() 负责验证页面结果。Playwright 会按照配置中的 testDir 发现该文件,并使用浏览器执行测试。
确保已经安装 Playwright Test 依赖及所需浏览器后,在项目根目录执行:
npx playwright test预期输出(关键行):
Running 1 test using 1 worker
1 passed (<TIME>)<TIME> 表示实际运行耗时,输出中的进度、文件名和耗时可能因环境不同而变化。这里最重要的验证结果是发现了 1 个测试,并显示 1 passed。
如果出现 No tests found,应首先检查当前工作目录是否为项目根目录、配置中的 testDir 是否正确,以及文件名是否以 .spec.js 等受支持的测试后缀结尾。
测试产物与验证
执行测试后,报告、截图和录像等调试信息会根据配置保存到相应位置,帮助定位失败原因。不同类型的产物并不会自动全部生成,需要结合测试结果和录制选项判断。
在本例中,HTML 报告器会生成 playwright-report/,其中的 index.html 是报告入口。可以在项目根目录执行以下命令打开报告:
npx playwright show-report预期结果:浏览器打开 Playwright HTML 报告页面,显示刚执行的测试及其通过状态。实际访问地址由本地报告服务决定,不需要固定端口。
test-results/ 则用于保存运行过程中的测试附件。是否存在截图、录像或 Trace 文件,取决于测试是否调用了相关 API,以及 use.screenshot、use.video、use.trace 等录制选项的设置。不能假定每次成功执行都会生成这些文件。
可以按照以下顺序验证项目结构是否符合预期:
- 检查
tests/example.spec.js是否存在,确认测试文件位于配置指定的目录。 - 运行测试,确认终端显示
1 passed。 - 检查
playwright-report/index.html是否生成,并打开报告查看测试状态。 - 查看
test-results/,理解其中的内容由测试执行和附件配置决定。
如果终端显示测试通过,但没有截图或录像,不代表项目配置失效;先检查是否启用了对应的录制选项。如果 HTML 报告没有生成,则检查 reporter 配置,并确认测试命令是否已完成执行。
掌握这些路径后,新增用例主要修改 tests/,调整执行规则主要修改 playwright.config.js,排查测试失败则查看报告和运行产物。这样就能避免把测试源码、运行配置与临时调试文件混在一起。