本文详解如何在 Cypress 中可靠地对 React 应用中跨文件定义、被多组件共用的函数进行监听（spy），解决因模块实例隔离导致的 spy 失效问题，并提供基于 window 注入与 onBeforeLoad 的标准实践方案。
本文详解如何在 cypress 中可靠地对 react 应用中跨文件定义、被多组件共用的函数进行监听（spy），解决因模块实例隔离导致的 spy 失效问题，并提供基于 `window` 注入与 `onbeforeload` 的标准实践方案。
在 Cypress 端直接对导入的模块对象（如 import { func } from '../../src/test'）调用 cy.spy(func, 'call') 通常不会生效——根本原因在于：测试代码和 React 应用代码分别运行在不同的 JavaScript 执行上下文（甚至不同模块图）中，func 在测试文件中是一个独立导入的副本，而组件实际调用的是其自身模块解析出的另一个 func 实例。二者内存地址不同，对前者设 spy 对后者毫无影响。
✅ 正确解法是：让 Cypress 测试与 React 应用共享同一个函数引用。业界公认、Cypress 官方推荐的方式是通过全局 window 对象桥接：
步骤一：在 React 应用中暴露函数到 window
在应用启动入口（如 App.js、index.js 或根组件 useEffect 中）安全注入，仅在 Cypress 运行时生效，避免污染生产环境：
// src/App.js
import React from 'react';
import { func } from '../../src/test';
// ✅ 仅当 Cypress 存在时挂载，确保开发/生产不受影响
if (typeof window !== 'undefined' && window.Cypress) {
window.appFuncs = { ...window.appFuncs, func }; // 推荐命名空间化，避免污染
}
function App() {
return <div>My App</div>;
}
export default App;⚠️ 注意：不要直接赋值 window.func = func（易与原生 API 冲突），使用命名空间如 window.appFuncs 更健壮。
步骤二：在 Cypress 测试中提前设置 spy
关键点在于 cy.spy() 必须在应用代码执行前完成，否则函数调用已发生，spy 来不及捕获。必须使用 cy.visit() 的 onBeforeLoad 钩子：
// cypress/e2e/spec.cy.js
describe('Function Call Spy Test', () => {
it('verifies func.call is invoked by component', () => {
cy.visit('/', {
onBeforeLoad: (win) => {
// ✅ 在页面任何脚本执行前，对 window 上暴露的函数设 spy
cy.spy(win.appFuncs.func, 'call').as('funcCall');
}
});
// 触发组件行为（如点击按钮、输入表单等）
cy.get('[data-testid="trigger-button"]').click();
// ✅ 使用别名断言，推荐链式写法
cy.get('@funcCall').should('have.been.calledOnce');
// 或更严格：检查参数
cy.get('@funcCall').should('have.been.calledWith', 'expected-event-data');
});
});为什么 onBeforeLoad 不可替代？
- cy.visit() 后 DOM 加载完成才执行回调，此时组件可能早已完成初始化并调用过目标函数；
- onBeforeLoad 在 <script> 标签解析执行前注入 spy，确保所有后续调用均被拦截。</script>
补充：对接网络层 Mock（呼应原始需求）
你提到需验证 REST/socket.io 流量且需离线运行。除函数 spy 外，可组合以下策略：
-
Fetch 拦截增强：使用 cy.intercept() 捕获请求后，通过 req.continue() 重写响应体，支持 FormData 解析：
cy.intercept('POST', '/api/data', (req) => { // 手动解析 FormData（需服务端配合或 mock 工具） const formData = new FormData(); req.body.forEach((value, key) => formData.append(key, value)); req.reply({ status: 200, body: { success: true } }); }); - Socket.IO 模拟：利用 cy.stub() 替换 io() 工厂函数，返回可控 socket 实例（需在 onBeforeLoad 中 stub window.io）。
总结
| 错误做法 | 正确做法 |
|---|---|
| cy.spy(importedFunc, 'call') | cy.spy(window.appFuncs.func, 'call') |
| cy.visit().then(() => spy) | cy.visit({ onBeforeLoad }) |
| 直接挂载 window.func | 命名空间化 window.appFuncs |
此模式不仅适用于普通工具函数，也广泛用于监控 SDK 调用（如 Sentry、Analytics）、自定义 Hook 内部逻辑及第三方库适配器行为，是 Cypress 与现代前端框架深度集成的核心技巧之一。
