Cypress 中正确处理文件下载的完整实践指南

cypress 默认无法感知浏览器外部触发的文件下载行为，导致测试卡在点击下载按钮后无限等待；本文详解如何通过 `cy.intercept()` 拦截请求、捕获响应体并用 `cy.writefile()` 保存文件，实现稳定可靠的下载流程验证。

在 Cypress 测试中，当点击“导出”按钮触发后台文件下载（如 csv、excel）时，常见误区是误用 cy.wait() 或强行延长超时时间——这不仅无效，还会掩盖根本问题。原因在于：Cypress 的命令链基于 dom 状态与网络请求生命周期，而浏览器原生文件下载不触发页面跳转或 DOM 变更，Cypress 无法自动感知其完成。

✅ 正确解法是主动拦截下载请求，将异步下载转化为可断言、可控制的命令流。核心步骤如下：

1. 精准定位下载接口：使用浏览器开发者工具（Network → XHR/Fetch）确认导出按钮实际发起的请求方法（通常是 GET 或 POST）和 URL 路径（如 /api/customers/export?format=csv）；
2. 用 cy.intercept() 拦截并别名：在触发下载前注册拦截器，为后续等待提供可靠锚点；
3. 触发 ui 操作：正常点击下拉菜单与导出链接；
4. cy.wait() 等待拦截响应：确保服务端已返回文件内容；
5. 保存文件并验证（可选）：使用 cy.writeFile() 存储二进制响应体，并可通过 cy.readFile() 进行内容校验。

以下是优化后的完整示例代码：

///   describe('Test the export customers list functionality', () => {   before('LoginFunction', () => {     cy.LoginFunction().wait(1000);   });    it('Export customers list', () => {     cy.contains('.sidebar li', 'CustomersListingPage').then((specificElement) => {       if (specificElement.length > 0) {         cy.wrap(specificElement).find('a').click();         cy.wait(2000);          // ✅ 关键：提前拦截导出请求（替换为真实 endpoint）         cy.intercept('GET', '/api/customers/export**').as('exportRequest');          // 触发 UI 下载动作         cy.get('a').filter('.dropdown-toggle').eq(1).click({ force: true });         cy.get('.export_file_link').click({ force: true });          // ✅ 等待拦截完成，获取响应体         cy.wait('@exportRequest').then((interception) => {           expect(interception.response.statusCode).to.eq(200);           expect(interception.response.headers['content-type']).to.include('text/csv');            // ✅ 保存文件（binary 模式适配 Excel/CSV 等二进制格式）           cy.writeFile('cypress/downloads/customers_export.csv', interception.response.body, 'binary');         });          cy.log('✅ Export file downloaded and saved successfully');       }     });   }); });

⚠️ 重要注意事项：

• cy.intercept() 必须在 UI 操作之前声明，否则可能错过首次请求；
• 若导出为 POST 请求，请同步修改 cy.intercept(‘POST’, …) 并注意请求体匹配（必要时使用 { body: { format: ‘csv’ } }）；
• cy.writeFile() 的路径为 Cypress 项目内相对路径（推荐统一存至 cypress/downloads/ 目录），该目录需提前创建且不会被 CI 环境自动清理，生产环境建议配合 beforeEach 清空；
• 避免使用 cy.wait(5000) 等硬编码等待——它不可靠且降低测试可维护性；
• 如需验证文件内容（如首行字段），可在 cy.readFile() 后添加断言：

  cy.readFile('cypress/downloads/customers_export.csv', { timeout: 10000 }).should('include', 'customer_id,name,email')

通过拦截 + 响应驱动的方式，你不仅能绕过 Cypress 对下载的“失明”，还能获得对文件格式、状态码、内容的完整控制力，让导出类用例真正具备可重复性与可调试性。