n8n:reproduce-bug

Bug 复现框架

根据 Linear 工单上下文（$ARGUMENTS），系统地复现 Bug， 并编写一个失败的回归测试。

第 1 步：解析线索

从提供的工单上下文中提取以下信息：

• 错误消息／堆栈跟踪（如果提供）
• 复现步骤（如果提供）
• 工作流 JSON（如果附上）
• 受影响区域（节点、执行引擎、编辑器、API、配置等）
• 出现问题的版本／最后一个正常工作的版本

第 2 步：选择测试策略

根据受影响区域，选择测试层级和模式：

区域	测试层级	模式	关键位置
节点操作	Vitest 单元测试	NodeTestHarness + nock	packages/nodes-base/nodes/*/test/
节点凭据	Vitest 单元测试	vitest-mock-extended	packages/nodes-base/nodes/*/test/
触发器 Webhook	Vitest 单元测试	mock IHookFunctions + vi.mock GenericFunctions	packages/nodes-base/nodes/*/test/
二进制数据	Vitest 单元测试	NodeTestHarness assertBinaryData	packages/core/nodes-testing/
执行引擎	Vitest 集成测试	WorkflowRunner + DI 容器	packages/cli/src/__tests__/
CLI／API	Vitest 集成测试	setupTestServer + supertest	packages/cli/test/integration/
配置	Vitest 单元测试	GlobalConfig + Container	packages/@n8n/config/src/configs/__tests__/
编辑器 UI	Vitest	Vue Test Utils + Pinia	packages/frontend/editor-ui/src/**/__tests__/
E2E／画布	Playwright	测试容器 + 组合式函数	packages/quality/testing/playwright/

第 3 步：定位源文件

查找受影响区域的源代码：

1. 搜索工单中提到的节点／服务／组件
2. 找到 GenericFunctions 文件（节点常见的 Bug 位置）
3. 检查同一区域是否已有测试文件
4. 查看受影响文件近期的 Git 历史（git log --oneline -10 -- <path>）

第 4 步：追踪代码路径

阅读源代码并追踪触发 Bug 的执行路径：

• 从入口点沿调用链追踪到故障处
• 找出 Bug 出现的具体代码行
• 记录 Bug 周边的错误处理（或缺失的错误处理）

第 5 步：提出假设

明确提出可测试的假设：

• “当 [输入／条件] 时，代码会执行 [错误操作]，因为 [根本原因]”
• 指出需要修改的确切代码行
• 预测测试输出会显示什么

第 6 步：查找测试模式

查找同一区域的现有测试：

1. 检查受影响代码附近的 test/ 目录
2. 找出它们使用的 Mock／设置模式
3. 使用相同模式以保持一致
4. 如果没有现有测试，找出最接近的类似节点／服务测试作为模板

第 7 步：编写失败测试

编写一个回归测试，要求：

• 使用第 6 步中找到的模式
• 针对第 5 步提出的具体假设
• 包含引用工单 ID 的注释
• 断言正确行为（当前代码下测试会失败）
• 还要包含一个“正常路径”测试，以证明测试设置有效

运行测试前，先完成 /AGENTS.md 中的测试安全检查：

• 追踪导入、构造函数、钩子和 Mock 分支产生的副作用
• 将文件系统访问限制在测试专用临时目录中
• 在导入会解析 N8N_USER_FOLDER 的模块前设置该变量
• 当 Mock 改变状态检查结果时，检查并隔离因此激活的分支

步骤 8：运行并评分

从软件包目录运行测试（例如，cd packages/nodes-base && pnpm test <file>）。

对结果进行分类：

置信度	标准	输出
CONFIRMED	测试持续失败，且失败与假设相符	复现报告
LIKELY	测试失败，但失败模式略有不同	报告 + 注意事项
UNCONFIRMED	无法触发故障	报告：已尝试的内容
SKIPPED	遇到硬性中止条件	报告：跳过原因
ALREADY_FIXED	当前代码已无法复现该错误	报告：修复时间

步骤 9：迭代或中止

如果首次尝试后结果为 UNCONFIRMED：

• 重新审视假设——重新阅读代码路径
• 尝试不同的测试方法或层级
• 最多尝试 3 次，然后再判定为 UNCONFIRMED

硬性中止条件（立即停止）：

• 需要真实的第三方 API 凭据
• 存在竞态条件／依赖时序
• 需要特定的云端／企业基础设施
• 需要无法通过脚本执行的手动 UI 交互

输出：复现报告

按以下格式呈现调查结果：

---

工单： [ID] — [标题] 置信度： [CONFIRMED | LIKELY | UNCONFIRMED | SKIPPED | ALREADY_FIXED]

根本原因

[用 1-2 句话说明错误的成因]

位置

文件	行号	问题
path/to/file.ts	XX-YY	问题描述

失败的测试

path/to/test/file.test.ts — X/Y 个测试失败：

1. test name — [失败说明]

修复提示

[伪代码或修复方案说明]

---

重要事项

• 不要修复错误——只需通过失败的测试复现错误
• 保留测试文件作为证据（除非有人要求，否则不要提交）
• 从软件包目录运行测试（例如，pushd packages/nodes-base && pnpm test <file> && popd）
• 始终重定向构建输出：pnpm build > build.log 2>&1
• 不要查看现有的修复 PR——目标是仅凭线索复现错误