自动化测试 / 系统课时
处理文件下载
处理文件下载
本课解决自动化测试中无法准确验证下载行为的问题。你将学习如何提前监听下载事件、保存下载文件,并检查文件名称和实际内容。通过一个完整的 CSV 下载测试,确认从点击下载到文件校验的整个过程符合预期。
学习目标
- 掌握 Playwright 下载事件的监听方式与正确执行顺序。
- 学会将下载文件保存到指定位置。
- 能验证文件名称、下载状态和实际内容。
等待下载事件
下载通常由点击行为触发,因此需要提前创建 download 监听。Playwright 提供 page.waitForEvent('download'),用于等待当前页面发起下载并获取对应的 Download 对象。
正确的执行顺序是:
- 调用
page.waitForEvent('download')创建等待 Promise,但暂时不等待它完成。 - 执行点击操作,触发浏览器下载。
- 等待下载事件并获取
Download对象。 - 读取建议文件名,保存文件并进行验证。
必须先注册监听,再执行点击。如果先点击再监听,下载事件可能已经触发,测试就会一直等待后续事件,最终超时。
还要区分下载开始与下载完成:download 事件在下载开始时触发,并不代表整个文件已经写入完毕。调用 download.saveAs() 可以等待下载完成并将文件保存到指定位置。

保存与验证文件
可以使用 download.path() 获取临时文件路径,再读取文件内容进行进一步校验。不过,临时文件通常会在所属浏览器上下文关闭后被删除,而且远程连接 Playwright 时,download.path() 可能抛出异常。
更通用的方式是使用 download.saveAs(),将文件保存到测试产物目录。Playwright Test 提供 testInfo.outputPath(),能够为当前测试生成独立的输出路径,避免并行测试相互覆盖文件。
下面编写一个完整示例,保存为 tests/download.spec.ts。示例使用 page.setContent() 创建包含下载链接的测试页面,不依赖外部网站。下载链接通过 download 属性指定文件名,CSV 内容包含表头与一条数据。
import { test, expect } from '@playwright/test';
import { readFile } from 'node:fs/promises';
test('download file', async ({ page }, testInfo) => {
// 构造自包含的下载页面,避免依赖外部服务
await page.setContent(
'<a download="report.csv" href="data:text/csv,id%2Cname%0A1%2CAda%0A">Download</a>'
);
// 必须先注册监听,再触发下载操作
const downloadPromise = page.waitForEvent('download');
await page.getByRole('link', { name: 'Download' }).click();
const download = await downloadPromise;
expect(download.suggestedFilename()).toBe('report.csv');
// 保存到当前测试的独立输出目录
const savedPath = testInfo.outputPath('report.csv');
await download.saveAs(savedPath);
// 验证真实文件内容以及最终下载状态
const content = await readFile(savedPath, 'utf8');
expect(content).toBe('id,name\n1,Ada\n');
expect(await download.failure()).toBeNull();
});预期结果:在已经安装 Playwright 浏览器运行环境的项目中,执行 npx playwright test tests/download.spec.ts,测试通过,并在当前测试的输出目录中生成 report.csv。如果项目配置了多个浏览器测试项目,测试会按配置分别执行。
保存文件的预期内容为:
id,name
1,Ada这里进行了三项验证:
suggestedFilename()检查浏览器建议的文件名是否为report.csv。readFile()读取保存后的实际文件,检查 CSV 表头、数据和换行内容是否正确。download.failure()在下载成功时返回null,用于确认下载没有失败或被取消。
使用 saveAs() 后,测试不需要依赖临时下载目录的具体位置。实际输出目录由 Playwright 配置和测试标识决定,测试运行前也不需要手工创建目标文件。
下载失败时检查什么
仅检查 suggestedFilename() 并不能证明文件下载成功,因为下载事件触发时,传输可能还没有结束。如果网络中断、服务器异常或下载被取消,saveAs() 可能抛出异常。排查时应检查下载请求、响应状态以及 download.failure() 返回的失败原因。
如果点击后没有触发 download 事件,需要确认页面是否真的启动了浏览器下载。例如,点击 PDF 链接后可能直接打开预览页面,而不是下载附件。这种情况应验证页面导航或响应行为,不能简单地延长下载等待时间。
不同文件类型也需要采用不同的内容验证方式。CSV、TXT 等文本文件适合使用 readFile(path, 'utf8') 检查关键内容;PDF、ZIP、图片等二进制文件则应检查文件头、文件结构、关键数据或校验和,避免将二进制内容直接当作 UTF-8 文本比较。