cypress 默认无法感知浏览器外部触发的文件下载行为，导致测试卡在点击下载按钮后无限等待；本文详解如何通过 `cy.intercept()` 拦截请求、捕获响应体并用 `cy.writefile()` 保存文件，实现稳定可靠的下载流程验证。
在 Cypress 测试中，当点击“导出”按钮触发后台文件下载（如 CSV、Excel）时，常见误区是误用 cy.wait() 或强行延长超时时间——这不仅无效，还会掩盖根本问题。原因在于：Cypress 的命令链基于 DOM 状态与网络请求生命周期，而浏览器原生文件下载不触发页面跳转或 DOM 变更，Cypress 无法自动感知其完成。
✅ 正确解法是主动拦截下载请求，将异步下载转化为可断言、可控制的命令流。核心步骤如下：
- 精准定位下载接口：使用浏览器开发者工具（Network → XHR/Fetch）确认导出按钮实际发起的请求方法（通常是 GET 或 POST）和 URL 路径（如 /api/customers/export?format=csv）；
- 用 cy.intercept() 拦截并别名：在触发下载前注册拦截器，为后续等待提供可靠锚点；
- 触发 UI 操作：正常点击下拉菜单与导出链接；
- cy.wait() 等待拦截响应：确保服务端已返回文件内容；
- 保存文件并验证（可选）：使用 cy.writeFile() 存储二进制响应体，并可通过 cy.readFile() 进行内容校验。
以下是优化后的完整示例代码：
Miller CSV TSV JSON 数据处理器
下载
Miller (mlr) 是一个命令行工具，用于查询、整形和重新格式化名称索引数据，如 CSV、TSV、JSON 和 JSON Lines。它将 awk、sed、cut、join 和 sort 的功能整合到一个专为结构化数据处理而构建的单一工具中。
/// <reference types="cypress" />
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 对下载的“失明”，还能获得对文件格式、状态码、内容的完整控制力，让导出类用例真正具备可重复性与可调试性。
