camunda-process-test

Camunda Process Test

ワークフロースキル：セグメントを計画し、シナリオを作成し、Maven テストコマンドを実行して、カバレッジの不足を解消します。

次の用途には使用しないでください：

BPMN、DMN、FEEL、フォームの作成、本番クラスターへのデプロイ、UI 動作のテストには、このスキルを使用しないでください。これらのタスクは camunda-bpmn、camunda-dmn、camunda-feel、camunda-forms、camunda-process-mgmt、または該当する UI テストフレームワークに振り分けてください。

Camunda 8.8 以降を対象に、最小限のテストセグメント数で BPMN 要素のカバレッジ 100％ を達成する Camunda Process Test スイートを作成し、実行します。テストのアサーションは到達可能性とルーティングに限定されます。CPT では、エンジンが正しい要素を通過することを検証します。サービス タスクや外部システムが生成するデータ値は検証しません。

前提条件

• Java 21 以降、Maven（または ./mvnw）、Docker ランタイム（OrbStack、Docker Desktop、または Rancher Desktop）。references/setup.md を参照してください。
• Java のフォールバックスイートでは、テストクラスパスに camunda-process-test-spring 8.8 以降が必要です。命令ベースの .test.json 形式と 8.9 専用 API には 8.9 以降が必要です。
• 動作する BPMN ファイル（lint がクリーンであること。camunda-bpmn を参照してください）。BPMN が参照する DMN ファイルとフォームファイルも用意する必要があります。

Node.js レイアウトの場合は、NODE_RESOURCE_DIR を設定し、references/setup.md に記載されているとおり、生成された test/ ディレクトリから Maven を実行してください。以下の Maven コマンドはシェルに依存しません。Node.js の POM は環境変数を読み取りますが、標準的な Java レイアウトでは環境変数は不要です。

関連項目

• camunda-bpmn：シナリオを作成する前に、テスト対象のプロセスに対して c8ctl bpmn lint を実行してください。lint エラーがあると、デプロイ時に @TestDeployment の失敗として表面化します。
• camunda-feel：ゲートウェイ条件または DMN エントリが不明確な場合に使用してください。FEEL のセマンティクスによって、各セグメントがどの分岐に進むかが決まります。
• camunda-dmn：DMN 判定がテスト対象の場合に使用してください。CPT では、呼び出し元のビジネスルールタスクを介して判定を実行します。構造チェックには npx dmnlint を併用してください。
• camunda-job-workers：サービスタスクを処理するハンドラーコード自体がテスト対象の場合に使用してください。CPT では BPMN の到達可能性を検証し、ワーカーユニットテストではハンドラーの動作を検証します。
• camunda-connectors-development：カスタムコネクターがテスト対象の場合に使用してください。CPT では BPMN 側からコネクターを実行し、SDK 側のテストではコネクタークラスを直接検証します。
• camunda-ai-agents：AI Agent Sub-process のテストに使用してください。COMPLETE_JOB_AD_HOC_SUB_PROCESS と context.when().then() が制御する BPMN シェイプを実行します。
• camunda-process-mgmt：CPT は埋め込み型の Zeebe エンジンに対して実行され、c8ctl が管理するクラスターやプロファイルは使用しません。c8ctl の呼び出しによってテスト対象のプロセスがデプロイされることはありません。

対象範囲の境界

• 対象範囲内：BPMN の到達可能性（すべての要素を少なくとも 1 回訪問すること）、ゲートウェイの分岐選択、DMN ルールの選択、エラー境界イベントの発火、タイマー／エスカレーション境界イベントの発火、終了イベントの選択。
• 対象範囲外：サービスタスクが生成するデータ値、外部システムのペイロード、UI の動作、エージェント／LLM の出力のアサーション。テストする下流ゲートウェイの FEEL 入力となる変数でない限り、サービスタスクの出力に対する ASSERT_VARIABLE 命令は記述しないでください。

ワークフロー

1. 検出

テスト対象の BPMN を、次の優先順位で探します。

1. src/main/resources/processes/
2. src/main/resources/bpmn/
3. プロジェクトのビルドで宣言されているリソースディレクトリ（たとえば、Node.js プロジェクトでは resources/ に配置され、テストハーネスは test/ に配置されている場合があります）。

target/、node_modules/、.git/、build/ は除外します。一致するファイルが複数ある場合は、それらを一覧表示して、どれを対象にするか確認してください。

pom.xml（または test/pom.xml）で camunda-process-test-spring を確認します。ない場合は、手順 2 に進みます。

シナリオがすでにある場合は、テストを編集する前にドリフトチェックを実行します。

git diff <base-branch>...HEAD -- <bpmn-path>

PR のベースブランチまたはリポジトリのデフォルトブランチを <base-branch> として使用します（多くの場合は main です）。

次に、現在のテストスイートの不足点を分類します。

• 壊れている：シナリオが、存在しなくなった elementId または processDefinitionId を参照しています。
• 古くなっている：ID は存在しますが、分岐を決める変数や前提が、ゲートウェイ／DMN の動作と一致していません。
• 不足している：新しい分岐、境界イベント、または終了イベントに対するセグメントのカバレッジがありません。

次の順番で修正します：壊れている → 古くなっている → 不足している。その後、mvn test を実行し、カバレッジの検証に進みます。

2. セットアップ（不足している場合のみ）

references/setup.md に従います。準備状況の事前確認（Java、Maven／ラッパー、Docker）を実行し、CPT の依存関係を追加し、CPT 8.9 以降では src/test/java/io/camunda/tests/ProcessTest.java と src/test/resources/scenarios/ を作成します。CPT 8.8 の場合は Java フォールバックを使用します。mvn test-compile で確認します。

3. セグメントを計画する（要素ごとではなく、セットカバー方式）

作成を始める前に、セグメント数が最小になるよう計画します。references/coverage-strategy.md を適用します。

1. BPMN を解析します：processId、要素 ID と型、ゲートウェイの出力フローと条件、エラー／タイマー／エスカレーションの境界、終了イベント、呼び出される DMN の判定（<zeebe:calledDecision decisionId="…">）、およびその中の DMN ルール。
2. 候補セグメントを列挙します。 すべてのゲートウェイ分岐、DMN ルール、境界イベント、代替終了イベントについて、直近の上流の判定ポイントを起点とする最小の候補セグメントを 1 つ定義します。各候補について、起点から対象の分岐を経由して次の再結合地点または終了イベントまで BPMN をたどり、訪問する要素とシーケンスフローの完全なセットを静的に予測します。
3. 貪欲なセットカバー。 まだカバーされていない ID を予測セットで最も多くカバーする候補を、繰り返し選びます。同数の場合は、経路が最短の候補（作成コストが最も低い候補）を優先します。すべての ID が網羅されるまで続けます。
4. 診断の切り分けを優先する上書き（任意）。 選択した 2 つのセグメントが同じ起点を共有していても、異なる失敗モード（例：一方は境界イベントを発生させ、もう一方はユーザータスクを正常に完了する）を試す場合は、失敗の原因を明確に特定できるよう両方を残します。ユーザーが特定の領域をデバッグしている場合にのみ適用します。デフォルトでは通常のセットカバーを使用します。
5. セグメント計画を表として出力します：segment name | root | predicted ids covered | end condition。作成時にはこの一覧をそのまま実装し、後で重複として削除される可能性のある推測的なシナリオは追加しません。

例： approved と rejected のフローを持つゲートウェイの場合、各フローにつき 1 つのセグメントを計画し、次の結合点までに訪問する ID を予測します。そのうえで、両方の分岐と共有される終了経路をカバーする最小限のセグメントを残します。

4. 作成

CPT 8.9 以降では、references/authoring.md を使用して、src/test/resources/scenarios/<processId>.test.json 内にエントリーを 1 つ記述します。CPT 8.8 では、.test.json の代わりに、同リファレンスで説明されている Java の代替方法を使用します。命名規則："<who/what> — <outcome>"。アサーション：セグメントが訪問する必要のある要素には ASSERT_ELEMENT_INSTANCES を使用し、セグメントが終了イベントまで実行される場合にのみ ASSERT_PROCESS_INSTANCE を使用します。

CPT 8.9 以降では、セグメントで Spring Bean のモック、パラメーター化されたデータテーブル、非決定的なランタイム競合（context.when().then() (8.9+)）、または JSON の命令セットでは対応できない、より高度なアサーションが必要な場合にのみ、Java の代替方法を使用します。CPT 8.8 では、命令ベースの形式が利用できないため、Java テストが必須です。references/test-context.md を参照してください。Java テストは Web Modeler には表示されません。

5. 実行

関連する pom.xml があるディレクトリから Maven を実行します。Node.js の構成の場合は、生成された test/ ディレクトリを使用し、references/setup.md の説明に従って、このコマンドとすべての再試行で NODE_RESOURCE_DIR に解決済みのリソースディレクトリを設定したままにします。

mvn test

失敗した場合は、references/troubleshooting.md に従って原因を特定します。テストの問題（変数の誤記、要素 ID の誤り、命令の不足）とプロセスの問題（FEEL 条件の誤り、DMN ルールの誤り、エラーコードの誤り）を区別します。該当する側を修正します。再実行します。進展がないまま修正を 3 サイクル繰り返したら終了します。

実行が終了したら（成功、失敗を問わず）、ただちに手順 6 に進み、カバレッジレポートを開きます。

6. カバレッジの確認 — 終了ゲート（ループを100％達成）

CPT は target/coverage-report/report.html にカバレッジレポートを出力します（プロセスごとの HTML で、ページにはカバレッジデータ全体が window.COVERAGE_DATA の JSON リテラルとして埋め込まれています）。解析します。

python3 - <<'PY'
import re, json
html = open("target/coverage-report/report.html").read()
# Balanced-brace extraction. Walk character by character, but track string
# state so braces inside JSON strings (e.g. inside a description) don't
# unbalance the counter.
m = re.search(r"window\.COVERAGE_DATA\s*=\s*", html)
start = html.index("{", m.end())
depth = 0; in_str = False; esc = False; end = start
for k, ch in enumerate(html[start:], start):
    if in_str:
        if esc: esc = False
        elif ch == "\\": esc = True
        elif ch == '"': in_str = False
    else:
        if ch == '"': in_str = True
        elif ch == "{": depth += 1
        elif ch == "}":
            depth -= 1
            if depth == 0:
                end = k + 1
                break
data = json.loads(html[start:end])
el = set(); flows = set(); total = None
for s in data["suites"]:
    for r in s["runs"]:
        for c in r["coverages"]:
            el.update(c.get("completedElements", []))
            flows.update(c.get("takenSequenceFlows", []))
            total = c.get("totalElementCount", total)
covered = len(el) + len(flows)
print(f"coverage={covered}/{total}={100*covered/total:.2f}%")
print("covered_elements:", sorted(el))
print("covered_flows:", sorted(flows))
PY

BPMN 要素および sequenceFlow の ID 一覧（grep -oE 'id="[A-Za-z0-9_]+"' <bpmn> を使用し、_di、BPMNDiagram、BPMNPlane、Definitions_、ErrorDef_、TimerDef_、Signal_、Message_ を除外）と差分を取ります。

mvn test の終了後、成功・失敗にかかわらず、すぐに HTML レポートのパスをユーザーに提示してください。 エージェントは上記の JSON データからすでにカバレッジを確認しています。HTML レポートはユーザーが確認するためのものです。最終回答には絶対パス（target/coverage-report/report.html）を記載し、ユーザー自身で開けるようにしてください。対話型のローカルセッションでは、代わりに開くことを申し出てもかまいません（macOS では open、Linux では xdg-open、Windows では start）。効果のないサンドボックス環境やリモート環境では、求められていないのに実行しないでください。

予測ミスへのパッチループ — デフォルトの動作。 ステップ 3 の集合被覆計画では、最初のシナリオ作成でカバレッジ100％を達成できるはずです。達成できなかった場合、その差分は予測ミスです。候補の静的なウォークと実行時の動作が一致していません。未カバーの ID ごとに、次の手順を実行します。

1. ミスを分類します。要素の場合は、その要素に直接到達します。シーケンスフローの場合は、そのフローのソースに到達し、さらにそのフローを通る条件分岐も満たす必要があります（通常は、プランナーが割り当てを誤ったゲートウェイ分岐です）。
2. 未カバーの ID に限定して貪欲な集合被覆を再実行します。選ばれた候補（多くの場合は1つ）をシナリオファイルに追加します。
3. タイマー境界イベントの場合：INCREASE_TIME に、タイマー周期より長い ISO 8601 の duration を指定します（例：R/PT24H に対して "PT25H"）。境界イベントが発火し、出力パスのジョブが作成されます。COMPLETE_JOB で完了させます。
4. メッセージ境界イベントの場合：名前と correlationKey が一致する PUBLISH_MESSAGE 命令を使用します。
5. ステップ 5（mvn test）→ ステップ 6 を再実行します。各反復で未カバーの集合が必ず減少する必要があります。減少しない場合は、プランナーのパス予測が誤っています。シナリオを増やして取り繕うのではなく、references/coverage-strategy.md の予測ロジックを修正してください。

ループを終了する重大なブロッカー：

• 2回連続の反復で、同じ ID が未カバーのまま残る場合は、一覧を提示して終了します。
• 未カバーの要素がデッドコード（入力フローがない、または入力条件が満たせない）である場合は、BPMN の不具合としてフラグを立て、camunda-bpmn を示して終了します。
• テストインフラストラクチャの障害（Docker が停止している、デプロイの解析エラーなど）が繰り返し発生する場合は、終了して references/troubleshooting.md に案内します。

未カバーの ID が残っていて、重大なブロッカーにも該当しない場合は、テストスイートの完了を宣言しないでください。

注：初期の 8.9 SNAPSHOT リリースでは、レポートジェネレーターが IllegalStateException: Report resources not found をスローし、HTML 出力をスキップすることがあります。テスト自体は成功します。その場合は、ソースから BPMN とシナリオを確認して、カバレッジを検証してください。

7. 冗長なシナリオが紛れ込んでいないことを確認する

ステップ 3 の集合被覆計画では、構成上、冗長でないテストスイートが生成されるはずです。実行時カバレッジデータを使って、シナリオを1つずつ除外する確認を行います。各シナリオについて、ほかのすべてのシナリオがカバーする ID の和集合を計算します。そのシナリオを除外しても失われる ID がない場合は冗長であり、プランナーに不具合があります。プランナーを修正してから、そのシナリオを削除してください。

また、以下も必ず確認してください（低コストで確認できるため、無条件に実施します）。

• <who/what> — <outcome> に一致しないシナリオ名（例："test1"、"happy"）。
• シナリオ間で重複している説明。
• 下流でゲートウェイや DMN が使用しない変数に対する ASSERT_VARIABLE 命令。データのアサーションは対象外です。

8. レポート

Surefire の結果行、カバレッジ率、セグメント数、および検出された重複を出力します。

Tests run: 6, Failures: 0, Errors: 0, Skipped: 0
Coverage: 100% (24/24 elements)
Segments: 1 happy path + 5 secondary
Duplicates flagged: 0

既存のテストスイートのメンテナンスワークフロー

テストがすでに存在し、ユーザーが新しいテストスイートの作成ではなく、実行、診断、改善を求めている場合は、次の目的に特化したワークフローを使用します。

1. 失敗を実行して診断する — 関連する pom.xml があるディレクトリで mvn test を実行します。Node.js の構成では、初回の実行とすべての再試行で NODE_RESOURCE_DIR に解決済みのリソースディレクトリを設定し、test/ から実行します。各失敗をインフラストラクチャ、テスト、プロセスの問題に分類してから、まとめて修正します。references/troubleshooting.md と references/run-and-diagnose.md を参照してください。
2. 新しいテストを書く前にカバレッジの不足を評価する — 現在のテストスイートのカバレッジをビジネス上の観点から説明し、未カバーの分岐、境界条件、ルールを列挙して、次に実施すべきシナリオの最小セットを提案します。references/evaluation.md を参照してください。
3. テストを CI に組み込む — CPT を確実に実行し、JUnit アーティファクトを公開するように CI を設定します。オプションで、信頼できるブランチに限定した統合プロファイルの実行も設定できます。references/ci.md を参照してください。

これらのワークフローは相互に補完します。まず不足を評価し、新しいシナリオを実装してから、ローカルと CI で実行および診断します。

参考資料

• setup.md — Java、Maven、Docker の前提条件、CPT の依存関係、テストのひな形の構成、Spring Boot 4.x の固定
• coverage-strategy.md — BPMN 要素の種類ごとのセグメント選択ルール（アドホックサブプロセスのツール有効化を含む）
• authoring.md — .test.json スキーマ、8.9 の全命令リファレンス、Java フォールバック
• test-context.md — CamundaProcessTestContext Java API の概要（ジョブ／意思決定／子プロセスのモック、時間制御、条件付き動作）
• connectors-runtime.md — Zeebe と併用する Connectors ランタイムの有効化、WireMock のパターン、インバウンド Webhook
• troubleshooting.md — 失敗の診断表（テストの問題とプロセスの問題）
• run-and-diagnose.md — テスト実行のループと失敗をまとめて修正する戦略
• evaluation.md — カバレッジ不足の評価と推奨のワークフロー
• ci.md — CPT の実行とテストレポートの公開に関する CI パイプラインのパターン