cypress-example-recipes

cypress-example-recipes 深度解析：一本“可执行”的 Cypress 测试菜谱

项目背景与痛点

Cypress 的官方文档写得足够好，但它是 API 参考，并非问题解法。当开发者面对真实需求时，这些文档提供的信息往往不够具体：

• 登录流程带 CSRF token，如何在测试里稳定复用登录态？
• 文件上传、文件拖拽、浏览器通知、iframe 里的元素，cy.get 到底能不能选中？
• 后端接口还没好，前端要先把用例写完，桩数据写在哪一层最不容易失效？
• 一个断言需要读取磁盘文件、连接数据库、清理测试数据，纯浏览器环境做不到怎么办？

这些问题在社区里被反复提问，答案散落在 issue、博客和 StackOverflow 中，质量参差不齐。cypress-example-recipes 的定位非常明确：为“常见测试场景”提供官方背书的、可运行的最小实现。它不试图成为框架，而是一本菜谱：每个目录对应一个问题，打开就能跑，跑通就能抄。

核心技术揭秘

目录约定：用文件系统组织结构

这个仓库最关键的技术决策不是代码，而是结构约定：一个目录就是一个独立可运行的 npm 项目。

• 每个菜谱自带 package.json、cypress.config（旧目录中是 cypress.json）和 cypress/e2e 规范文件；
• 自带 README，先讲“问题是什么”，再讲“怎么解”；
• 自带被测应用或 mock server，不依赖仓库根目录的任何共享代码。

这意味着刻意的重复：十几个菜谱里会看到几乎一样的 cy.intercept 写法。它牺牲了 DRY，换来了两个更重要的性质：菜谱之间零耦合，任何一条被删除、被改写都不会波及他人；读者复制单个目录即可闭环，不需要先理解一套抽象层。

根目录的 CI 脚本则是这套约定的“执行者”：扫描包含 package.json 的子目录，逐个安装依赖并运行，把整本菜谱变成一份活文档。任何一次 Cypress 大版本升级，都会在这里暴露全部破坏性变更，而不是等到用户踩坑。

运行时数据流：三层架构下的分工

理解菜谱为什么这样写，需要理解 Cypress 的运行时结构：浏览器里的测试代码并不直接访问 Node，中间隔着一层由 Cypress 启动的代理进程。

这张图解释了菜谱中三类典型写法的来源：

1. 网络层桩数据：请求经过代理进程，所以 cy.intercept 能看见页面发出的所有 XHR/fetch，并在响应返回浏览器之前改写状态码与 body。菜谱里大量“先拦截、再访问页面、最后断言”的写法，本质是在控制代理层的路由表。
2. Node 能力桥接：cy.task 把浏览器里的调用序列化后交给 Node 进程执行，再把结果回传。凡是涉及文件系统、数据库、SMTP 的场景（下载校验、数据播种、邮件确认链接），菜谱一律走这条通道，而不是试图在浏览器里绕路。
3. 应用侧准备：需要真实后端行为的菜谱会起一个本地服务（如 json-server 或 Node 脚本），让测试有“可信的对端”，而不是全程 mock。

功能亮点与差异

其一，覆盖面而非深度。 同类项目通常二选一：要么给你一个完整示例应用（如 real-world-app），要么给你一组零散的 gist。这个仓库选择的是“场景矩阵”——鉴权、网络、DOM 交互（拖拽、悬停、滚动）、跨域与 iframe、文件、时间控制、框架集成（React/Vue/Angular）、Docker 与 CI 运行方式。它更像一本索引，你要做的是按图索骥。

其二，官方维护带来的版本可信度。 菜谱跟着 Cypress 主线升级，cy.route/cy.server 这类旧 API 会被替换成 cy.intercept。社区博客做不到这一点，而“照抄三年前的博客导致用例莫名其妙失败”才是真实痛点。

其三，反框架的克制。 没有自定义命令库、没有页面对象层、没有断言封装。它传递的隐性观点是：先写清楚一条用例，再考虑抽象。这一点对刚接触 Cypress 的团队尤其重要——过早引入 Page Object 往往是维护成本的来源。

应用场景与落地建议

适合：技术选型阶段验证 Cypress 能否覆盖某个具体场景（“我们有个 iframe 支付页，能不能测”）；团队建立内部测试规范时作为写法基线；新人培训时的练习素材。

需要注意：

• 不要整体引入。正确用法是“挑一个目录，读 README，复制思路，改写成自己项目的代码”。整目录拷贝会带入一堆无关依赖。
• 区分“示例”与“生产约定”。菜谱为了讲清一个点，常常省略错误处理、重试策略、数据隔离。生产环境要补的是：测试数据如何唯一化、失败重试与 flaky 治理、跨用例状态污染。
• 关注版本漂移。仓库里各菜谱的依赖版本不完全同步，落地前先确认所用 Cypress 版本与 API 是否匹配。
• CI 成本。几十个独立项目各自 npm install 的耗时不小，自建类似结构时应做依赖缓存与并行调度。

综合评价

优点：官方权威、场景覆盖广、每一条都能跑、结构约定清晰、对 Cypress 运行时（代理层与 Node 桥接）的教学价值远超其代码量本身。它把“测试怎么写”这个模糊问题，降解成了“你的场景属于哪一格”。

缺点：碎片化严重，缺少一条从零到一的渐进路径；部分菜谱停留在“能演示”的层面，工程严谨度不足以直接照搬；对复杂业务系统的整体测试策略（分层、契约测试、E2E 与单测的边界）几乎没有涉及——这本来也不是它的职责范围。

一句话总结：它是 Cypress 生态里最值得反复翻阅的参考资料，但只是“字典”，并非“教材”。用它查词，别指望它教你写文章。