cypress 默认无法监听或等待浏览器外部触发的文件下载，直接点击下载链接会导致测试无限等待超时；应改用 cy.intercept() 拦截请求并配合 cy.writefile() 保存文件，实现可控、可断言的下载流程。
在 Cypress 中，点击触发文件下载（如 CSV 导出）是一个常见但易踩坑的操作。由于浏览器原生下载行为脱离 DOM 生命周期，Cypress 的命令链（如 cy.click() 后自动等待页面加载）会误判为“页面跳转未完成”，从而持续等待、最终超时失败——这正是你遇到的“test gets stuck”和 “expected page is not loaded” 错误的根本原因。
✅ 正确解法：不依赖 UI 等待，而是主动拦截网络请求
Cypress 提供了强大的 cy.intercept() API，可在请求发出前/响应返回后进行捕获与处理。针对文件下载，推荐以下四步模式：
- 精准拦截下载请求：通过匹配 URL（支持 glob 或正则）、方法（通常是 GET 或 POST）定位导出接口；
- 触发 UI 操作：正常点击下拉菜单和导出链接；
- 显式等待响应：使用 cy.wait('@alias') 确保请求完成并获取响应体；
- 本地保存文件：将 interception.response.body 写入磁盘（注意二进制格式）。
以下是优化后的完整示例（含健壮性增强）：
/// <reference types="cypress" />
describe('Test the export customers list functionality', () => {
before('LoginFunction', () => {
cy.LoginFunction();
});
it('Export customers list', () => {
cy.contains('.sidebar li', 'CustomersListingPage').should('exist').then(($li) => {
cy.wrap($li).find('a').click();
cy.url().should('include', '/customers'); // 显式校验导航成功
// ✅ 关键：拦截导出请求（请替换为实际 API 路径，如 /api/export/customers）
cy.intercept('GET', '/api/**/export*').as('exportRequest');
// 触发导出操作
cy.get('a.dropdown-toggle').eq(1).click({ force: true });
cy.get('.export_file_link').click({ force: true });
// ✅ 等待响应完成，并保存文件
cy.wait('@exportRequest', { timeout: 30000 }).then((interception) => {
expect(interception.response?.statusCode).to.eq(200);
expect(interception.response?.headers['content-type']).to.include('text/csv');
// 以二进制方式写入文件（适配 CSV/Excel 等）
cy.writeFile('cypress/downloads/customers_export.csv', interception.response.body, 'binary');
});
cy.log('✅ Export file downloaded and saved successfully');
});
});
});⚠️ 重要注意事项：
- 路径匹配要精确：'/api/**/export*' 比泛用 '*' 更安全，避免误拦截其他请求；可通过 Cypress Test Runner 的 Network Tab 查看真实请求路径；
- 响应体格式需匹配：若导出为 Excel（.xlsx），仍用 'binary'；若为 JSON 包裹文件流，需先解析 response.body.data；
- 不要依赖 cy.wait(2000)：硬等待不可靠，应始终用 cy.intercept() + cy.wait('@alias') 替代；
- 文件目录权限：确保 cypress/downloads/ 目录存在且可写（建议在 cypress.config.js 中配置 downloadsFolder: 'cypress/downloads'）；
- CI 环境兼容性：该方案在 GitHub Actions、GitLab CI 等无头环境中完全有效，无需额外配置下载行为。
通过将“下载”从 UI 交互问题转化为网络请求问题，你不仅能彻底规避超时卡死，还能对响应状态码、Content-Type、文件内容等做断言，大幅提升测试的可靠性与可观测性。
