利用Playwright实现文件上传与下载的完成判断全指南

在使用 Playwright 进行自动化测试或网页操作时，文件上传（File Upload） 和 文件下载（File Download） 是两个常见但需要特别注意的场景。本文将为你提供一份 完整的指南，包括：

✅ 文件上传的实现与验证
✅ 文件下载的实现与完成判断
✅ 常见问题与最佳实践

一、文件上传（File Upload）

1. 基本实现方式

在 Web 页面中，文件上传通常通过 <input type="file"> 元素实现。使用 Playwright 上传文件非常简单，只需使用 input.type() 或更推荐的 input.setInputFiles() 方法。

示例代码（上传单个文件）：

const { test, expect } = require('@playwright/test');

test('upload a file', async ({ page }) => {
  await page.goto('https://example.com/upload');

  // 定位文件输入框
  const fileInput = await page.locator('input[type="file"]');

  // 设置要上传的文件路径（绝对路径）
  await fileInput.setInputFiles('/path/to/your/file.txt');

  // 可选：点击上传按钮并等待上传完成
  await page.click('text=Upload');
  await page.waitForSelector('.upload-success'); // 根据页面反馈元素判断
});

📌 注意：

setInputFiles() 支持单个文件路径字符串，或多个文件路径的数组。

推荐使用 绝对路径，可以使用 path.resolve(__dirname, 'file.txt') 来构建跨平台兼容的路径。

上传多个文件：

await fileInput.setInputFiles([
  '/path/to/file1.txt',
  '/path/to/file2.jpg'
]);

2. 上传完成判断

文件上传是否成功，一般依赖页面上的反馈信息，例如：

显示 “上传成功” 的提示信息（如 class 为 .success 的元素出现）
文件列表中出现刚上传的文件
某个按钮状态改变，或页面跳转

常用判断方式：

// 等待某个成功提示出现
await page.waitForSelector('.upload-success', { state: 'attached' });

// 或者等待文件出现在列表中
await page.waitForSelector('.file-item:has-text("file.txt")');

✅ 最佳实践：不要依赖隐式等待，而是显式地等待上传成功的 UI 反馈，这样更可靠。

二、文件下载（File Download）

文件下载相比上传更为复杂，因为：

下载是由浏览器触发的后台行为，Playwright 无法直接控制浏览器的下载管理器
我们需要 监听下载事件，并 判断文件是否已经完全下载到指定目录

Playwright 提供了强大的 下载 API，可以拦截下载行为，并获取下载的文件路径。

1. 启用下载功能 & 监听下载事件

在使用 Playwright 进行下载测试前，你需要：

配置浏览器上下文（BrowserContext）以允许下载
获取下载事件对象，从而可以访问下载的文件路径和状态

示例：监听并处理文件下载

const { test, expect } = require('@playwright/test');
const path = require('path');
const fs = require('fs/promises');

test('download a file and verify completion', async ({ page, context }) => {
  // 设置下载路径（可选，如果不设置则使用默认下载目录）
  const downloadPath = path.join(__dirname, 'downloads');
  await fs.mkdir(downloadPath, { recursive: true });

  // 监听下载事件
  let downloadPromise = new Promise((resolve) => {
    context.on('download', (download) => {
      console.log(`开始下载: ${download.url()}`);
      downloadPromise = new Promise((res) => {
        download.on('done', async (artifact) => {
          console.log(`下载完成: ${artifact.path()}`);
          res(artifact); // 返回 artifact 对象，包含下载的临时文件路径
        });
      });
    });
  });

  // 导航到包含下载链接的页面
  await page.goto('https://example.com/download');

  // 点击下载按钮（比如一个 <a download> 或按钮触发下载）
  await page.click('text=Download File');

  // 等待下载完成
  const artifact = await downloadPromise;

  // 可选：将下载的临时文件移动到指定位置
  const finalFilePath = path.join(downloadPath, 'myfile.pdf'); // 假设是 PDF
  await artifact.saveAs(finalFilePath);

  // 判断文件是否真的存在，作为下载完成的最终确认
  try {
    await fs.access(finalFilePath);
    console.log(`文件已保存至：${finalFilePath}`);
  } catch (err) {
    console.error('文件保存失败', err);
  }

  // 或者你也可以直接判断 artifact 是否已完成下载
  const downloadedPath = await artifact.path(); // 临时路径
  console.log(`临时下载路径：${downloadedPath}`);
});

⚠️ 注意：

artifact.path() 返回的是一个 临时路径，该文件在浏览器会话结束后可能会被删除，建议使用 artifact.saveAs(filePath) 将其保存到指定位置。

通过 artifact.state() 可以获取下载状态（如 ‘in-progress’、’completed’、’cancelled’）

2. 更简洁的写法（推荐）：直接 await download

Playwright 也允许你直接 await 一个 download 对象，这样更直观：

// 点击触发下载
await page.click('text=Download');

// 等待下载事件触发，并获取 download 对象
const [download] = await Promise.all([
  context.waitForEvent('download'),
  page.click('text=Download'), // 触发下载的操作
]);

console.log(`正在下载: ${download.url()}`);

// 等待下载完成
const artifact = await download;
const downloadedPath = await artifact.path(); // 临时路径
console.log(`文件下载到临时位置: ${downloadedPath}`);

// 可选：保存到指定位置
const saveTo = path.join(__dirname, 'downloads', 'myfile.pdf');
await artifact.saveAs(saveTo);

// 判断文件是否存在，确保下载真正完成
await fs.access(saveTo);
console.log(`文件已保存到: ${saveTo}`);

3. 如何判断文件下载“真正完成”

由于下载是由浏览器控制的异步过程，Playwright 通过以下方式帮助我们判断：

方法	说明
`context.on('download', ...)`	监听新的下载任务开始
`download` 对象	表示一个下载任务，有 `state`、`url` 等属性
`await download` 或 `download.done()`	等待下载完成，返回一个 `Artifact` 对象
`artifact.path()`	获取下载的临时文件路径（下载完成后可用）
`artifact.saveAs(path)`	将文件保存到自定义路径（推荐）
`artifact.state()`	获取状态：’in-progress’、’completed’、’cancelled’

🔒 最佳实践：

不要只依赖 artifact.path() 存在就认为下载完成，最好再通过 fs.access() 检查文件可访问，或者使用 artifact.saveAs() 并检查目标路径。
如果你只是想确认文件已经下载到默认目录，可以轮询检查该目录是否有新文件出现（不推荐，尽量用 Playwright 提供的 API）。

三、完整示例：上传 + 下载 + 判断

下面是一个综合示例，展示如何上传文件并触发下载，然后判断下载是否完成：

const { test, expect } = require('@playwright/test');
const path = require('path');
const fs = require('fs/promises');

test('upload and download with verification', async ({ page, context }) => {
  const downloadDir = path.join(__dirname, 'downloads');
  await fs.mkdir(downloadDir, { recursive: true });

  // 1. 文件上传
  await page.goto('https://example.com/upload');
  const fileInput = await page.locator('input[type="file"]');
  await fileInput.setInputFiles(path.join(__dirname, 'testfile.txt'));

  await page.click('text=Upload');
  await page.waitForSelector('.upload-success');

  // 2. 文件下载
  const [download] = await Promise.all([
    context.waitForEvent('download'),
    page.click('text=Download File'), // 假设点击后触发下载
  ]);

  console.log(`开始下载文件: ${download.url()}`);
  const artifact = await download;
  const savedFilePath = path.join(downloadDir, 'downloaded-file.pdf');
  await artifact.saveAs(savedFilePath);

  // 3. 验证下载完成
  try {
    await fs.access(savedFilePath);
    console.log(`✅ 文件已成功下载并保存到: ${savedFilePath}`);
  } catch (err) {
    console.error('❌ 文件下载失败或未找到', err);
  }
});

四、常见问题与注意事项

Q1: 为什么我无法通过 `page.waitForSelector()` 判断下载完成？

下载通常不会直接改变 DOM，所以不能依赖页面元素来判断。应该使用 Playwright 的下载事件机制。

Q2: 下载的文件在哪里？如何找到它？

默认情况下，下载的文件会保存在浏览器的默认下载目录（如 Chrome 的 Downloads 文件夹），但通过 Playwright，我们推荐使用 artifact.saveAs(path) 将其保存到测试项目内的可控目录，便于验证和管理。

Q3: 如何设置浏览器的默认下载路径？

你可以为 BrowserContext 指定下载目录：

const context = await browser.newContext({
  downloadsPath: path.join(__dirname, 'downloads')
});

这样所有下载会自动保存到你指定的目录，但仍建议使用 artifact.saveAs() 进行明确控制。

五、总结

功能	关键 API / 方法	要点
文件上传	`input.setInputFiles(filePath or [files])`	定位 `<input type="file">`，传入文件路径
	`page.click('upload-button')`	触发上传，等待 UI 反馈
	`waitForSelector('.success')`	判断上传是否成功
文件下载	`context.on('download', ...)` 或 `waitForEvent('download')`	监听下载事件
	`download.path()`	获取临时下载路径
	`artifact.saveAs(path)`	保存到指定路径，推荐用于验证
	`fs.access(path)`	判断文件是否真实存在，验证下载完成