mcpField
N
n8n:reproduce-bug

n8n:reproduce-bug

github.com/n8n-ioテスト・品質209.1k242 回インストール今日更新
リポジトリ

n8n:reproduce-bug について

n8n開発向けのバグ再現スキルです。Linearチケットの情報からテスト層を選び、失敗する回帰テストを作成して再現度を報告します。バグ自体は修正しません。

主な機能

  1. 01チケット情報から手掛かりを抽出
  2. 02影響範囲に応じたテスト戦略の選択
  3. 03コード経路の追跡と仮説の作成
  4. 04失敗する回帰テストの作成
  5. 05結果の分類と調査内容の報告

活用シーン

  1. 01報告されたn8nのバグ再現
  2. 02影響範囲に合うテスト層の選定
  3. 03バグが現在も再現するかの確認
  4. 04再現度と根拠の記録

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/n8n-io/n8n --skill n8n:reproduce-bug

インストール後、Claude Code で/n8n:reproduce-bugを入力して読み込まれたか確認します。

詳細

バグ再現フレームワーク

Linear チケットのコンテキスト（$ARGUMENTS）をもとに、失敗する回帰テストでバグを体系的に再現します。

ステップ 1：シグナルを解析する

提供されたチケットのコンテキストから、以下を抽出します。

  • エラーメッセージ／スタックトレース（提供されている場合）
  • 再現手順（提供されている場合）
  • ワークフロー JSON（添付されている場合）
  • 影響を受ける領域（ノード、実行エンジン、エディター、API、設定など）
  • 不具合が発生したバージョン／最後に正常動作したバージョン

ステップ 2：テスト戦略を選択する

影響を受ける領域に応じて、テストレイヤーとパターンを選択します。

領域テストレイヤーパターン主な場所
ノード操作Vitest 単体テストNodeTestHarness + nockpackages/nodes-base/nodes/*/test/
ノード認証情報Vitest 単体テストvitest-mock-extendedpackages/nodes-base/nodes/*/test/
トリガー WebhookVitest 単体テストmock IHookFunctions + vi.mock GenericFunctionspackages/nodes-base/nodes/*/test/
バイナリデータVitest 単体テストNodeTestHarness assertBinaryDatapackages/core/nodes-testing/
実行エンジンVitest 統合テストWorkflowRunner + DI containerpackages/cli/src/__tests__/
CLI／APIVitest 統合テストsetupTestServer + supertestpackages/cli/test/integration/
設定Vitest 単体テストGlobalConfig + Containerpackages/@n8n/config/src/configs/__tests__/
エディター UIVitestVue Test Utils + Piniapackages/frontend/editor-ui/src/**/__tests__/
E2E／CanvasPlaywrightテストコンテナー + composablespackages/quality/testing/playwright/

ステップ 3：ソースファイルを特定する

影響を受ける領域のソースコードを探します。

  1. チケットに記載されたノード／サービス／コンポーネントを検索します
  2. GenericFunctions ファイルを探します（ノードでよくあるバグの場所です）
  3. 同じ領域に既存のテストファイルがあるか確認します
  4. 影響を受けるファイルの最近の git 履歴を確認します（git log --oneline -10 -- <path>）

ステップ 4：コードパスを追跡する

ソースコードを読み、バグを引き起こす実行パスを追跡します。

  • エントリーポイントから障害発生箇所まで、呼び出しチェーンをたどります
  • バグが顕在化する具体的な行を特定します
  • バグ周辺のエラーハンドリングの有無を確認します

ステップ 5：仮説を立てる

明確で検証可能な仮説を示します。

  • 「[入力／条件] の場合、[根本原因] により、コードは [誤った動作] をします」
  • 変更が必要な具体的な行を特定します
  • テスト結果に何が表示されるか予測します

ステップ 6：テストパターンを見つける

同じ領域にある既存のテストを調べます。

  1. 影響を受けるコードの近くにある test/ ディレクトリを確認します
  2. 使用されているモック／セットアップのパターンを特定します
  3. 一貫性を保つため、同じパターンを使用します
  4. テストがない場合は、最も近い類似のノード／サービスのテストをテンプレートとして探します

ステップ 7：失敗するテストを書く

次の条件を満たす回帰テストを書きます。

  • ステップ 6 で確認したパターンを使用する
  • ステップ 5 で立てた具体的な仮説を検証する
  • チケット ID を参照するコメントを含める
  • 正しい動作をアサートする（現行コードではテストが失敗します）
  • セットアップが正しく機能することを証明する「正常系」のテストも含める

テストを実行する前に、/AGENTS.md に記載されているテスト安全性ゲートを完了してください。

  • インポート、コンストラクター、フック、モックされた分岐による副作用を追跡します
  • ファイルシステムへのアクセスは、テスト専用の一時ディレクトリ内に限定します
  • モジュールが N8N_USER_FOLDER を解決する前に設定します
  • モックによって状態チェックが変わる場合は、モックが有効にする分岐を調べ、分離します

ステップ 8：実行して判定する

パッケージディレクトリからテストを実行します（例：cd packages/nodes-base && pnpm test <file>）。

結果を分類します。

確信度基準出力
CONFIRMEDテストが一貫して失敗し、失敗内容が仮説と一致する再現レポート
LIKELYテストは失敗するが、失敗の内容が少し異なるレポート＋注記
UNCONFIRMED失敗を再現できないレポート：試した内容
SKIPPED即時中止条件に該当したレポート：スキップした理由
ALREADY_FIXED現在のコードではバグを再現できないレポート：修正された時期

ステップ 9：再試行するか中止する

最初の試行で UNCONFIRMED となった場合：

  • 仮説を見直す — コードパスを再読する
  • 別のテスト方法やレイヤーを試す
  • UNCONFIRMED と判定するまでの試行は最大 3 回

即時中止条件（直ちに停止）：

  • 実際のサードパーティ API 認証情報が必要
  • 競合状態／タイミングに依存する
  • 特定のクラウド／エンタープライズインフラが必要
  • スクリプト化できない手動の UI 操作が必要

出力：再現レポート

次の形式で調査結果を提示します。

チケット： [ID] — [title] 確信度： [CONFIRMED | LIKELY | UNCONFIRMED | SKIPPED | ALREADY_FIXED]

根本原因

[バグの仕組みを説明する 1～2 文]

場所
ファイル行問題
path/to/file.tsXX-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 を見ないでください — 手がかりだけから再現することが目的です

コメント

Markdown 対応