Cypress：避坑必备

▌ 技术引导
Cypress是前端自动化测试中最锋利的武器之一，它用异步方式处理DOM操作，让你不用再写一堆await和done，直接写代码就行。但它的锋利也带来了暗礁，比如和Vue3 + Vite的整合需要特别注意，否则会卡死在setup阶段。我见过太多人因为没配置好electron的启动参数导致测试无法运行，记住在cypress.config.js里必须写electronConfig: { chromePath: 'node_modules/.bin/electron' }。还有很多人误以为Cypress只适合UI测试，其实它也能做API测试，只需要用cy.request()，但要小心拦截器和mock的依赖关系。另外，Cypress的录制功能是真的香，但是每次启动会把所有测试结果写入同一个文件，这样日志就乱了，得手动配置 outputPath 和 recordingFolder。最后，别再用beforeEach和afterEach了，Cypress自带的test isolation已经够用。

▌ 技术参考

一
Cypress是一个基于Node.js的前端测试框架，它通过直接操作浏览器，提供了一套完整的测试工具链。在2024年，Cypress已经支持Vue3、React18、Angular15等主流框架，但在某些特定组合下，比如Vue3搭配Vite，会出现自动加载失败的问题。这时候需要通过修改Cypress的启动参数来绕过问题，比如在cypress.config.js中设置electronConfig: { chromePath: 'node_modules/.bin/electron' }。同时，Cypress 12版本后引入了Typescript支持，这让测试脚本的类型检查变得更加直观，减少了很多运行时错误。

二
在进行测试前，必须确保项目中的依赖项版本兼容。例如，当使用Cypress 12+时，如果不同时升级到Vite 3以上，可能会遇到模块加载异常。另外，Cypress的测试隔离特性非常强大，每个测试用例都会在独立的浏览器实例中运行，这可以在cypress.config.js中配置testIsolation: false来关闭。但关闭后可能会导致测试执行时间变长，同时增加内存占用。如果是运行集成测试，建议保持默认设置，而单元测试可以考虑关闭隔离。此外，Cypress的录制功能会自动抓取所有测试的录像，但默认情况下会覆盖原有文件，可以通过设置video: false来禁用视频录制，或者在配置文件中指定recordingFolder和outputPath来分开存储。

三
Cypress的异步处理机制是它最核心的优势，但也是最容易出错的地方。在测试中，如果你直接调用cy.get()，它会自动等待元素加载完成，但如果你使用cy.request()获取数据，必须手动处理响应结果，否则会因为异步延迟而报错。例如，cy.request('GET', '/api/data').then(res => { expect(res.body).to.have.property('status') })。另外，Cypress的等待机制可以通过设置wait: 5000来调整，但在多层嵌套的测试中，建议使用cy.wait()而不是全局设置，这样能更精准地控制等待时间。如果你用的是Cypress 13，可以考虑使用cy.intercept()来拦截HTTP请求，这样能更快地定位测试失败的原因。

四
使用Cypress时最常见的错误是测试卡死在setup阶段。这通常是因为浏览器没有正确启动，或者环境变量未配置。例如，在某个项目中，当使用Vue3和Vite时，Cypress会因为找不到正确的入口文件而卡死，这时候需要在cypress.config.js中手动指定entryPoint，如entryPoint: 'dist/index.html'。另外，在某些情况下，Cypress会因为依赖项冲突而无法启动，比如和jest或者webpack的版本不匹配，这时候可以通过在cypress.json中添加excludeSpecPattern来排除部分测试文件，或者使用cypress package的--no-verify参数跳过验证。这些操作在实际项目中非常常见，但很多新人没有意识到，导致测试一直无法运行。

五
Cypress的自动化爬虫功能在2025年得到明显增强，特别是在处理动态加载的内容时，可以通过cy.wait()或者cy.intercept()来控制加载进度。例如，当测试一个需要加载第三方资源的页面时，可以使用cy.intercept('GET', '/some-api-path').as('apiCall')，然后在测试中使用cy.wait('@apiCall').then(() => { ... })来等待API调用完成。不过要注意，这种拦截方式可能会改变真实请求的顺序，导致测试结果与实际不符。在某些项目中，我见过因为拦截API导致测试用例失败，尤其是涉及身份验证或状态码判断的场景。这时需要结合mock数据和实际请求进行判断，避免误判。

六
Cypress的mock功能在2026年已经非常成熟，尤其是在处理第三方库时，可以通过cy.stub()或者cy.spy()来模拟函数行为。比如，当你测试一个依赖axios的组件时，可以使用cy.stub(axios, 'get').resolves({ data: 'mocked' })来模拟API调用，确保测试不依赖真实网络。但有些开发者会误以为mock数据就是直接替换响应结果，其实mock还需要考虑请求头、请求参数、状态码等细节，否则测试结果会不准确。例如，cy.request('GET', '/api/data', { headers: { 'Authorization': 'Bearer token' } }).as('authCall')，然后在后续测试中检查headers是否正确，避免因为没设置正确导致mock失效。

七
Cypress的UI测试中，定位元素通常依赖于选择器和等待机制，但有时候会因为页面加载顺序问题导致元素找不到。这时候可以使用cy.get().should('be.visible')来确保元素可见后再进行操作。另外，Cypress的自动等待机制有时候会显得不够灵活，尤其是在处理复杂的动态页面时，比如滚动加载更多数据，这时需要手动调用cy.scrollTo()来触发页面加载。我在一个电商项目中就遇到过这种情况，页面里的商品列表是分页加载的，如果不手动滚动，cy.get()根本无法找到后续的数据，这时候就得在测试脚本中加入cy.scrollTo('bottom')。同时，Cypress的retry机制可以设置，如retries: { open: 2, request: 3, script: 4 }，这样能自动重试几次，避免因为网络波动导致测试失败。

八
Cypress的测试报告系统在2025年进行了优化，支持更详细的失败日志和截图保存。默认情况下，Cypress会在测试失败时自动保存截图和视频，但有时候用户会因为配置错误导致这些功能失效。例如，在cypress.json中设置video: true，或者在测试脚本中调用cy.saveScreenshot()来保存特定测试的截图。同时，Cypress的报告工具也可以集成到CI/CD系统中，比如Jenkins或GitLab CI，这样可以实现自动化测试报告的生成和发送。不过要注意，有些CI系统本身的缓存机制可能会导致测试执行不一致，这时候需要在cypress.config.js中配置retries: 0，避免因缓存问题导致结果偏差。

九
Cypress的并行执行能力在2024年得到了显著提升，支持多浏览器和多设备同时运行测试。这可以通过在cypress.config.js中设置parallel: true，并配置CI环境的并行参数来实现。比如，在GitHub Actions中，可以使用cypress parallel runner来分批次执行测试，但要注意，某些测试用例可能因为依赖关系导致失败，这时需要手动设置testIsolation: false，让测试在同一个上下文中运行。此外，Cypress的并行执行会占用更多资源，建议在本地测试时关闭，并行只在CI环境中开启，否则可能因为内存不足导致进程崩溃。

十
在处理复杂的测试场景时，Cypress的命令式API提供了比传统测试框架更灵活的方式。比如，当你需要在同一个测试中切换多个页面时，可以使用cy.visit()来重新加载页面，或者使用cy.get('a').click()来跳转，但要注意，每次cy.visit()会重新初始化测试上下文，导致之前的数据被清空。这时候可以使用cy.go()来回到上一个页面，避免重复访问。但有些开发者的习惯是使用cy.reload()，这其实和cy.visit()类似，只是会重用当前上下文，可能导致状态未正确重置。因此，在测试中需要根据具体情况选择合适的页面跳转方式，避免状态残留导致逻辑错误。

十一
Cypress的测试覆盖范围在2025年有了新的扩展，支持Mocking Node.js模块。例如，如果你在测试中使用了某些本地模块，可以通过cy.stub()或者cy.mock()来模拟其行为，避免依赖文件系统的实际路径。此外，Cypress的mock还可以用于本地开发环境，比如在开发时mock某些API请求，让前端组件可以正常运行。但有些开发者会误以为mock只是替换响应数据，其实mock还需要考虑请求的参数、返回的结构，甚至请求次数。比如，当测试一个需要多次调用的API时，可以使用cy.intercept('POST', '/api/endpoint').as('api')，然后在测试中多次调用cy.wait('@api')，确保请求次数正确。这些都是真实踩过的坑，而且修复起来需要仔细排查。

十二
Cypress的测试脚本结构在2024年有了新的变化，尤其是在使用Typescript时，需要额外配置tsconfig.json。例如，在tsconfig中要设置module: 'ESNext'和target: 'ESNext'，否则编译时会出现模块找不到的错误。同时，Cypress的测试文件需要放在特定的目录下，比如cypress/e2e，否则会无法识别。如果使用了Jest或Vitest，需要注意测试环境的隔离，避免Cypress和Jest的上下文冲突。在实际项目中，我见过有人因为没正确设置tsconfig导致测试脚本编译失败，最终发现是缺少必要的模块声明，这时候需要手动添加@types/cypress-type definitions。

十三
Cypress的UI测试中，事件模拟是一个高频操作。比如，点击按钮、填写表单、拖拽元素等，都需要通过cy.trigger()或者cy.type()来完成。但要注意，一些复杂的交互，比如点击某个区域后弹出菜单，需要先定位到父元素再触发事件。例如，cy.get('#menu').click()，然后再定位到子元素触发后续操作。此外，Cypress的键盘事件模拟需要注意键盘状态，比如按住Shift键输入时，需要使用cy.type('Shift+{backspace}')，否则可能输入不了特殊字符。这也是很多新手容易忽略的地方，导致测试结果不一致。

十四
Cypress的测试脚本中，断言是必不可少的部分。但有时候断言会因为等待时间不够而失败。比如，使用cy.contains()来查找元素时，如果元素加载时间较长，可能会找不到。这时需要在cy.contains()后加上.wait()或者使用cy.get().should('have.text', 'expected text')来增强等待机制。另外，在处理异步数据时，需要注意断言的时机。例如，在一个React组件中，数据加载是异步的，这时候需要确保组件渲染完成后再进行断言。可以通过cy.wait(5000)或者cy.get('.data-container').should('exist')来控制测试流程，避免过早断言导致错误。

十五
Cypress的测试脚本虽然功能强大，但在某些情况下会因为配置问题导致执行异常。例如，当使用Cypress 13时，如果项目中的某些依赖项版本过低，可能会导致构建失败。这时候需要手动更新这些依赖项，或者使用npm install --save-dev cypress@13来指定版本。此外，在使用Cypress CLI时，需要注意命令的参数顺序，比如cypress run --env config='test-config.json'，如果参数顺序不对，可能无法正确加载环境配置。这些都是实际工作中踩过的坑，修复时需要结合日志和配置文件进行排查，确保所有参数都正确无误。