Back to Details

reproduce-bug

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Bug Reproduction Framework

Bug复现框架

Given a Linear ticket context ($ARGUMENTS), systematically reproduce the bug with a failing regression test.
给定Linear工单上下文（$ARGUMENTS），通过失败的回归测试系统性地复现Bug。

Step 1: Parse Signals

步骤1：解析关键信息

Extract the following from the provided ticket context:
  • Error message / stack trace (if provided)
  • Reproduction steps (if provided)
  • Workflow JSON (if attached)
  • Affected area (node, execution engine, editor, API, config, etc.)
  • Version where it broke / last working version
从提供的工单上下文中提取以下内容：
  • 错误信息/堆栈跟踪（如果有提供）
  • 复现步骤（如果有提供）
  • Workflow JSON（如果有附件）
  • 影响区域（node、执行引擎、编辑器、API、配置等）
  • Bug出现的版本/最后正常工作的版本

Step 2: Route to Test Strategy

步骤2：选择测试策略

Based on the affected area, pick the test layer and pattern:
AreaTest LayerPatternKey Location
Node operationJest unitNodeTestHarness + nock
packages/nodes-base/nodes/*/test/
Node credentialJest unitjest-mock-extended
packages/nodes-base/nodes/*/test/
Trigger webhookJest unitmock IHookFunctions + jest.mock GenericFunctions
packages/nodes-base/nodes/*/test/
Binary dataJest unitNodeTestHarness assertBinaryData
packages/core/nodes-testing/
Execution engineJest integrationWorkflowRunner + DI container
packages/cli/src/__tests__/
CLI / APIJest integrationsetupTestServer + supertest
packages/cli/test/integration/
ConfigJest unitGlobalConfig + Container
packages/@n8n/config/src/__tests__/
Editor UIVitestVue Test Utils + Pinia
packages/frontend/editor-ui/src/**/__tests__/
E2E / CanvasPlaywrightTest containers + composables
packages/testing/playwright/
根据影响区域，选择对应的测试层级和模式：
影响区域测试层级测试模式关键路径
Node操作Jest单元测试NodeTestHarness + nock
packages/nodes-base/nodes/*/test/
Node凭证Jest单元测试jest-mock-extended
packages/nodes-base/nodes/*/test/
Trigger WebhookJest单元测试mock IHookFunctions + jest.mock GenericFunctions
packages/nodes-base/nodes/*/test/
二进制数据Jest单元测试NodeTestHarness assertBinaryData
packages/core/nodes-testing/
执行引擎Jest集成测试WorkflowRunner + DI容器
packages/cli/src/__tests__/
CLI / APIJest集成测试setupTestServer + supertest
packages/cli/test/integration/
配置Jest单元测试GlobalConfig + Container
packages/@n8n/config/src/__tests__/
编辑器UIVitestVue Test Utils + Pinia
packages/frontend/editor-ui/src/**/__tests__/
E2E / 画布PlaywrightTest containers + composables
packages/testing/playwright/

Step 3: Locate Source Files

步骤3：定位源代码文件

Find the source code for the affected area:
  1. Search for the node/service/component mentioned in the ticket
  2. Find the GenericFunctions file (common bug location for nodes)
  3. Check for existing test files in the same area
  4. Look at recent git history on affected files (
    git log --oneline -10 -- <path>
    )
找到受影响区域的源代码：
  1. 搜索工单中提到的node/服务/组件
  2. 找到GenericFunctions文件（node的常见Bug位置）
  3. 检查同一区域的现有测试文件
  4. 查看受影响文件的近期Git提交记录（
    git log --oneline -10 -- <path>
    ）

Step 4: Trace the Code Path

步骤4：追踪代码路径

Read the source code and trace the execution path that triggers the bug:
  • Follow the call chain from entry point to the failure
  • Identify the specific line(s) where the bug manifests
  • Note any error handling (or lack thereof) around the bug
阅读源代码并追踪触发Bug的执行路径：
  • 从入口点到失败位置的调用链
  • 确定Bug出现的具体代码行
  • 记录Bug相关的错误处理（或缺失的错误处理）

Step 5: Form Hypothesis

步骤5：提出假设

State a clear, testable hypothesis:
  • "When [input/condition], the code does [wrong thing] because [root cause]"
  • Identify the exact line(s) that need to change
  • Predict what the test output will show
明确可验证的假设：
  • “当[输入/条件]时，代码会[执行错误操作]，原因是[根本原因]”
  • 确定需要修改的具体代码行
  • 预测测试输出结果

Step 6: Find Test Patterns

步骤6：查找测试模式

Look for existing tests in the same area:
  1. Check 
    test/
    directories near the affected code
  2. Identify which mock/setup patterns they use
  3. Use the same patterns for consistency
  4. If no tests exist, find the closest similar node/service tests as a template
查看同一区域的现有测试：
  1. 检查受影响代码附近的
    test/
    目录
  2. 识别它们使用的模拟/初始化模式
  3. 为保持一致性，使用相同的模式
  4. 如果没有现有测试，找最相似的node/服务测试作为模板

Step 7: Write Failing Test

步骤7：编写失败的测试用例

Write a regression test that:
  • Uses the patterns found in Step 6
  • Targets the specific hypothesis from Step 5
  • Includes a comment referencing the ticket ID
  • Asserts the CORRECT behavior (test will fail on current code)
  • Also includes a "happy path" test to prove the setup works
编写回归测试用例，要求：
  • 使用步骤6中找到的模式
  • 针对步骤5中的假设
  • 包含引用工单ID的注释
  • 断言正确的行为（当前代码下测试会失败）
  • 同时包含“正常流程”测试，验证测试环境配置有效

Step 8: Run and Score

步骤8：运行测试并评估结果

Run the test from the package directory (e.g., 
cd packages/nodes-base && pnpm test <file>
).
Classify the result:
ConfidenceCriteriaOutput
CONFIRMEDTest fails consistently, failure matches hypothesisReproduction Report
LIKELYTest fails but failure mode differs slightlyReport + caveat
UNCONFIRMEDCannot trigger the failureReport: what was tried
SKIPPEDHit a hard bailout triggerReport: why skipped
ALREADY_FIXEDBug no longer reproduces on current codeReport: when fixed
从包目录运行测试（例如：
cd packages/nodes-base && pnpm test <file>
）。
对结果进行分类：
置信度判定标准输出
已确认测试持续失败，失败情况与假设一致复现报告
大概率测试失败，但失败模式略有不同报告 + 说明
未确认无法触发失败报告：尝试过的操作
已跳过遇到强制终止触发条件报告：跳过原因
已修复当前代码中Bug无法复现报告：修复时间

Step 9: Iterate or Bail

步骤9：迭代尝试或终止

If UNCONFIRMED after first attempt:
  • Revisit hypothesis — re-read the code path
  • Try a different test approach or layer
  • Maximum 3 attempts before declaring UNCONFIRMED
Hard bailout triggers (stop immediately):
  • Requires real third-party API credentials
  • Race condition / timing-dependent
  • Requires specific cloud/enterprise infrastructure
  • Requires manual UI interaction that can't be scripted
如果第一次尝试后结果为未确认：
  • 重新审视假设——重新阅读代码路径
  • 尝试不同的测试方法或层级
  • 最多尝试3次，之后判定为未确认
强制终止触发条件（立即停止）：
  • 需要真实的第三方API凭证
  • 竞争条件/依赖时序
  • 需要特定的云/企业基础设施
  • 需要无法脚本化的手动UI交互

Output: Reproduction Report

输出：复现报告

Present findings in this format:
Ticket: [ID] — [title] Confidence: [CONFIRMED | LIKELY | UNCONFIRMED | SKIPPED | ALREADY_FIXED]
按以下格式呈现结果：
工单： [ID] — [标题] 置信度： [已确认 | 大概率 | 未确认 | 已跳过 | 已修复]

Root Cause

根本原因

[1-2 sentences explaining the bug mechanism]
[1-2句话解释Bug的机制]

Location

位置

FileLinesIssue
path/to/file.ts
XX-YYDescription of the problem
文件行号问题描述
path/to/file.ts
XX-YY问题说明

Failing Test

失败的测试用例

path/to/test/file.test.ts
— X/Y tests fail:
  1. test name
    — [failure description]
path/to/test/file.test.ts
— X/Y个测试失败：
  1. 测试名称
    — [失败描述]

Fix Hint

修复提示

[Pseudocode or description of the fix approach]
[伪代码或修复方法说明]

Important

注意事项

  • DO NOT fix the bug — only reproduce it with a failing test
  • Leave test files in place as evidence (don't commit unless asked)
  • Run tests from the package directory (e.g., 
    pushd packages/nodes-base && pnpm test <file> && popd
    )
  • Always redirect build output: 
    pnpm build > build.log 2>&1
  • DO NOT look at existing fix PRs — the goal is to reproduce from signals alone
  • 不要修复Bug — 仅通过失败的测试复现Bug
  • 保留测试文件作为证据（除非要求，否则不要提交）
  • 从包目录运行测试（例如：
    pushd packages/nodes-base && pnpm test <file> && popd
    ）
  • 始终重定向构建输出：
    pnpm build > build.log 2>&1
  • 不要查看已有的修复PR — 目标是仅通过现有信息复现Bug