如何在 Cypress 中处理文件上传和下载？

在现代 Web 应用测试中，文件上传和下载是常见场景，尤其涉及文档管理、媒体处理或数据交换功能。Cypress 作为流行的端到端测试框架，提供了强大的 API 来模拟浏览器行为，但其文件操作需特殊处理以避免常见陷阱。本文将深入解析如何在 Cypress 中高效处理文件上传与下载，结合真实测试场景和代码示例，确保测试覆盖率和可靠性。文件操作不当可能导致测试失败或环境不一致，因此掌握核心方法对自动化测试至关重要。

上传文件处理

1. 使用 `cy.selectFile()` 方法模拟上传

Cypress 的 cy.selectFile() 是核心 API，用于模拟文件输入。它支持单文件或多文件上传，并自动处理文件路径和类型。

基本用法：直接指定文件路径或使用 fixture。

javascript
// 上传单个文件（推荐使用 fixture 路径）
cy.get('#file-upload').selectFile('cypress/fixtures/test.pdf');

// 上传多个文件（数组格式）
cy.get('#file-upload').selectFile(['cypress/fixtures/file1.jpg', 'cypress/fixtures/file2.mp4']);

关键参数：
- fixture：使用 cy.fixture() 加载二进制数据，适合处理大型文件或敏感数据。
- contentType：指定 MIME 类型，例如 cy.selectFile('test.txt', { contentType: 'text/plain' })。
- force：强制覆盖现有文件（默认为 false）。

注意：路径必须是绝对路径或相对路径，Cypress 自动处理文件系统。对于跨平台测试，建议使用 cypress/fixtures 目录存储测试文件。

2. 处理大型文件和二进制数据

当上传大文件（如视频）时，需避免阻塞测试执行。Cypress 提供 cy.readFile() 验证文件内容，但需配合 cy.wait() 确保异步操作完成。

步骤：
1. 上传文件：cy.get('#upload-btn').selectFile('large-video.mp4');
2. 等待上传完成：cy.get('#upload-status').should('contain', 'Processing');
3. 验证文件：cy.readFile('cypress/fixtures/processed-video.mp4', 'base64').should('include', 'video/mp4');
实践建议：
- 对于 >10MB 文件，使用 cy.fixture() 避免内存泄漏。
- 通过 cy.wait() 监听 xhr 或 http 请求，确保服务器响应。

3. 常见问题与解决方案

问题：上传后未触发事件：可能因文件输入未正确聚焦。解决：cy.get('#file-input').focus().selectFile(...)。
问题：跨浏览器兼容性：Safari 限制文件上传。解决：使用 cy.get().invoke('attr', 'accept', 'image/*') 设置 MIME 类型。
问题：安全沙箱限制：Chrome 的安全策略阻止本地文件。解决：使用 cy.writeFile() 生成临时文件。

下载文件处理

1. 监听下载事件

Cypress 的 cy.on('file:download', callback) 用于捕获下载行为。它监听浏览器的 download 事件，适用于验证下载触发和文件路径。

基础监听：

javascript
// 注册下载事件监听器
cy.on('file:download', (event) => {
  const filePath = event.filePath;
  // 验证文件路径
  expect(filePath).to.include('downloads/');
});

// 触发下载（示例：点击下载按钮）
cy.get('#download-btn').click();

关键参数：
- event.filePath：下载文件的绝对路径（需跨平台处理）。
- event.blob：文件数据（仅限二进制验证）。

注意：Cypress 4.0+ 支持 file:download 事件，但需启用 --disable-download 参数以避免真实下载。测试时建议禁用下载以加速执行。

2. 验证下载内容

下载后验证文件内容需结合文件系统操作。Cypress 通过 cy.readFile() 检查文件是否存在或内容匹配。

步骤：
1. 触发下载：cy.get('#download-btn').click();
2. 验证文件存在：cy.readFile('downloads/test.txt').should('be.a.string');
3. 验证内容：cy.readFile('downloads/test.txt', 'utf-8').should('include', 'Hello');
实践建议：
- 使用 cy.get('body').then(($body) => $body.find('#download-status').should('contain', 'Completed')) 等待状态更新。
- 对于二进制文件，使用 cy.readFile() 与 base64 格式比对：cy.readFile('file.mp4', 'base64').should('include', 'mp4');

3. 处理浏览器特定行为

Chrome：默认使用 downloads 目录，路径为 ~/Downloads。需通过 cy.window().then(win => win.chrome.downloads) 获取路径。
Safari：下载路径为 ~/Downloads，但需处理 file:download 事件。
解决方法：在测试前设置 CYPRESS_DOWNLOAD_FOLDER 环境变量，例如 CYPRESS_DOWNLOAD_FOLDER='cypress/downloads'。

常见问题与解决方案

1. 上传文件后页面未刷新

原因：文件上传是异步操作，测试未等待事件触发。
解决方案：使用 cy.wait() 监听特定请求：

javascript
cy.get('#upload-btn').selectFile('test.pdf');
cy.wait('@upload-request').its('response.statusCode').should('eq', 200);

2. 下载文件路径不一致

原因：浏览器下载目录因 OS 和设置不同。
解决方案：在测试前配置 Cypress：

javascript
// cypress.config.js
module.exports = {
  e2e: {
    setupNodeEvents(on, config) {
      on('before:run', () => {
        config.env.DOWNLOAD_FOLDER = 'cypress/downloads';
      });
    }
  }
};

3. 安全策略导致上传失败

原因：CSP 或同源策略阻止文件访问。
解决方案：在测试中禁用安全策略：

javascript
cy.visit('https://example.com', { onBeforeLoad: win => win.document.write('<script>document.domain = "example.com"</script>') });

结论

在 Cypress 中处理文件上传和下载，关键在于正确使用其 API 并处理浏览器差异。上传时优先使用 cy.selectFile() 与 fixture，确保文件路径和类型准确；下载时通过 cy.on('file:download') 监听事件，并结合 cy.readFile() 验证内容。务必注意测试环境配置（如 CYPRESS_DOWNLOAD_FOLDER）和异步等待，以避免测试失败。建议在测试套件中添加文件清理步骤（如 cy.deleteFile()），保持测试环境干净。掌握这些技巧，可显著提升文件操作测试的可靠性，为复杂 Web 应用提供坚实保障。记住：文件处理是自动化测试的常见痛点，但通过 Cypress 的专业支持，可轻松克服。

实践建议

测试设计：为文件操作创建独立测试模块（如 cypress/integration/files.spec.js），隔离逻辑。
性能优化：对大文件使用 cy.fixture() 避免阻塞，优先测试核心流程。
安全提示：永远不要在测试中上传真实敏感数据；使用 mock 服务或 fixture。
扩展阅读：Cypress 官方文档详细说明 file handling。

重要提示：Cypress 8.0+ 引入 cy.readFile() 优化，建议升级框架以获取最新功能。始终验证测试结果，避免依赖浏览器默认行为。文件操作是自动化测试的基石，正确实施可大幅提升测试覆盖率和准确性。