伝播 (Propagation)

このスキルは Allium 仕様からテストを生成します。伝播は植物が親から挿し木で繁殖するのと同じしくみです。仕様が親であり、テストが子孫です。

決定論的なツールは完全性を保証します(すべての仕様コンストラクトがテスト義務にマップされます)。実装ブリッジを処理します。仕様コンストラクトをコードと相関させ、プロジェクトの規則に従ったテストを生成します。

前提条件

テストを伝播させる前に以下が必要です。

1. Allium 仕様 — システムの動作を説明する .allium ファイル
2. ターゲットコードベース — テスト対象の実装
3. テスト義務 — allium plan <spec> から取得 (必要なすべてのテストをリストアップした JSON)
4. ドメインモデル — allium model <spec> から取得 (エンティティ形状、制約、ステートマシンを説明する JSON)

CLI ツールが利用できない場合は、references/test-generation.md のテスト生成タクソノミーを使用して、仕様から手動でテスト義務を導き出してください。

モード

サーフェスモード

サーフェス宣言から境界テストを生成します。API、UI コントラクト、または統合境界をテストしたい場合に使用します。

仕様内の各サーフェスについて:

1. 露出テスト — exposes 内の各アイテムが指定されたアクターにアクセス可能であることを確認します。コレクション上の for イテレーションを含みます
2. 提供テスト — 操作が when 条件が真の場合に表示され、そうでない場合に隠れていることを確認します。対応するルールの requires 句が満たされていない場合を含みます
3. アクター制限テスト — サーフェスが他のアクタータイプにアクセス不可であることを確認します
4. アクター識別テスト — アクターの identified_by 述語に一致するエンティティのみがインタラクションできることを確認します。within を使用するアクターについては、インタラクションが宣言されたコンテキストにスコープされていることを確認します
5. コンテキストスコーピングテスト — context 述語に一致するエンティティがない場合、サーフェスインスタンスが存在しないことを確認します
6. 契約義務テスト — demands がカウンターパートで満たされ、fulfils がこのサーフェスで提供されていることを確認します。すべての型指定署名を含みます
7. 保証テスト — @guarantee アノテーションが境界全体で成立することを確認します
8. タイムアウトテスト — 参照される時間的ルールがサーフェスのコンテキスト内で発火することを確認します
9. 関連ナビゲーションテスト — 関連サーフェスへのナビゲーションが正しいコンテキストエンティティに解決されることを確認します

仕様モード

完全なテスト義務ドキュメント全体を走査します。仕様全体に対する包括的なテストカバレッジが必要な場合に使用します。

テスト生成タクソノミーからのカテゴリ:

• エンティティと値の型テスト — フィールド、型、オプション (?) null ハンドリング、when 句の状態依存存在、関連、結合ルックアップ、等価性
• 列挙型テスト — 名前付き列挙型全体の比較可能性、メンバーシップテスト、インライン列挙型分離
• 合計型テスト — 変種フィールド、型ガード、完全性、変種名による作成、基本 .created トリガーナローイング
• 派生値とプロジェクションテスト — 計算、フィルタリング、-> field 抽出、パラメータ化された派生値、now の揮発性、コレクション操作
• デフォルトインスタンステスト — 無条件存在、フィールド値、デフォルト間の相互参照
• 設定テスト — デフォルト、オーバーライド、必須パラメータ、表現形式のデフォルト、修飾参照、設定チェーン
• 不変条件テスト — ルール後の検証、エッジケース、含意ロジック、エンティティレベルの不変条件
• ルールテスト — 成功/失敗/エッジケース、条件付き (if ガードが結果状態を読み取ることの確認)、エンティティ作成、削除、一括更新、ルールレベルの for イテレーション、let バインディング、チェーンされたトリガー
• 状態遷移テスト — 有効/無効な遷移、終端状態、transitions_to vs becomes セマンティクス
• 時間的テスト — 期限境界、再発火防止、オプションフィールド null 動作
• サーフェステスト — 露出、利用可能性、within スコーピングを伴うアクター識別、コンテキストスコーピング、関連ナビゲーション
• 契約テスト — 署名充足、@invariant 尊重、demands/fulfils 方向
• クロスモジュールテスト — 修飾エンティティ参照、外部トリガー応答、型プレースホルダ置換
• クロスルールインタラクションテスト — 重複作成ガード、提供利用可能性
• 遷移グラフテスト — すべての宣言されたエッジがそれを証言するルール経由で到達可能、宣言されていない遷移が拒否される、終端状態に出力ルールなし、非終端状態に少なくとも1つの終了がある、列挙値とグラフエッジ間の正確な対応
• 状態依存フィールドテスト — 適格な状態にある場合の存在、外にある場合の不存在、when セットに入る時の存在義務、離れる時の不存在義務、内または外で移動する場合の義務なし、収束遷移がすべてフィールドを設定、when 修飾フィールドにアクセスするために必要なガード、入力交差経由の派生値 when 推論
• シナリオテスト — ハッピーパス、エッジケース、順序独立性
• データフローチェーンテスト — サーフェスキャプチャからルールを通じてダウンストリームルール前提条件への完全なチェーンを実行します。各チェーン (サーフェス提供トリガー → ルールが確認するフィールド → ダウンストリームルールが必要とするフィールド) について、サーフェス経由でデータを送信し、ダウンストリーム前提条件に到達することを確認する統合テストを生成します。
• 到達可能性テスト — 各初期状態 (.created() 経由) から各終端状態へ、遷移グラフを通じた有効なパスに従って走査します。各テストは完全なライフサイクルを実行します。
• デッドロックシナリオテスト — allium analyse が潜在的なデッドロックを識別する状態について、エンティティを行き止まり状態に置き、それが進行できるかどうかを確認するテストを生成します。
• クロスエンティティプロセステスト — 複数のエンティティにまたがるプロセスについて、すべての参加エンティティにわたって開始から終端状態まで完全なプロセスを実行する統合テストを生成します。

allium analyse が利用可能な場合、その発見結果を使用してテスト生成を優先順位付けします。missing_producer または dead_transition の発見は、テストで実行する価値のあるギャップを示します。deadlock の発見は、エンティティが行き止まり状態を脱出できないことを記録するテストを生成します。発見タイプタクソノミーについては、発見への対応 を参照してください。

テスト出力形式

1. アサーションベースのテスト

決定論的な義務の場合: フィールド存在、列挙型メンバーシップ、遷移有効性、サーフェス露出、状態依存フィールド存在と不存在。これらは標準的なユニット/統合テストです。

2. プロパティベースのテスト

不変条件とルールプロパティの場合。各式を持つ不変条件は PBT プロパティになります:

• ジェネレータ仕様を使用して有効なエンティティ状態を生成します
• ルールのシーケンスを適用します (遷移グラフが宣言されている場合はそれに従い、そうでない場合はルールのみから有効なシーケンスを導き出します)
• 各ステップで不変条件が成立することを確認します

プロジェクトの PBT フレームワークを使用します:

言語	フレームワーク	検出
TypeScript	fast-check	package.json
Python	Hypothesis	pyproject.toml
Rust	proptest	Cargo.toml
Go	rapid	go.mod
Elixir	StreamData	mix.exs

PBT フレームワークが存在しない場合はアサーションベースのテストにフォールバックします。

3. ステートマシンテスト

ステータス列挙型を持つエンティティの場合。遷移グラフが宣言されている場合、グラフを通じたすべてのパスを走査します。グラフが宣言されていない場合、ルールから有効な遷移を導き出します。

• 遷移がルールを証言することで成功することを確認します
• 拒否された遷移が失敗することを確認します
• 状態依存フィールドが各状態で when 句ごとに存在または不存在であることを確認します
• 不変条件が各状態で成立することを確認します

ステートマシンテストには アクションマップ が必要です。遷移エッジごとに、ソース状態のエンティティを取得し、実際の実装コードを呼び出してターゲット状態に戻すエンティティを生成する関数です。このマップなしでは、テストフレームワークはグラフを通じた有効なパスを説明できますが、それらを実行できません。

アクションマップを構築するには:

1. 遷移グラフの各エッジについて、仕様内の証言するルールを見つけます
2. そのルールを実装するコードを見つけます (実装ブリッジ)
3. 前提条件 (requires 句) を設定し、コードを呼び出し、エンティティをターゲット状態で返すテストアクションを記述します
4. (from_state, to_state) キーの下にアクションを登録します

マップが構築されたら、PBT フレームワークはランダムな有効なパスを走査できます。任意の非終端状態で開始し、ランダムな出力エッジを選択し、そのアクションを適用し、すべてのエンティティレベルの不変条件をチェック、繰り返します。パス長と開始状態がランダムに生成されます。これは仕様の遷移グラフをテストとして最も完全に表現したものです。

実装ブリッジ

仕様コンストラクトを実装コードと相関させます。これは weed スキルが差異チェック用に相関させるのと同じ方法です。

サーフェステストの場合

サーフェスを実装にマップします:

• API サーフェスはエンドポイント (REST ルート、GraphQL リゾルバー、gRPC サービス) にマップされます
• UI サーフェスはコンポーネントまたはページにマップされます
• 統合サーフェスはメッセージハンドラーまたは SDK メソッドにマップされます

コードベースを読んでマッピングを検出します。命名パターン、ルート定義、ハンドラー登録を探します。

内部テストの場合

仕様内の各ルールについて:

1. ルールを実装するコードを見つけます (サービスメソッド、イベントハンドラー、ステートマシン遷移)
2. 関連するエンティティをインスタンス化する方法を決定します (ファクトリ、ビルダー、フィクスチャ)
3. ルールを呼び出す方法を決定します (API 呼び出し、メソッド呼び出し、イベントディスパッチ)
4. 事後条件をアサートする方法を決定します (データベースクエリ、戻り値、イベントアサーション)

時間的テストの場合

時間的トリガー (期限ベースのルール) は、テストで制御可能な時間ソースを必要とします。実装が壁時計時刻 (Instant.now()、System.currentTimeMillis()) を使用する場合、テストは確実に期限の前、時点、または後に位置することができません。

時間的テストを試みる前に、コンポーネントが注入されたクロックまたは時間パラメータを受け入れるかどうかを確認してください。一般的なパターン: コンストラクタの Clock パラメータ、メソッドのエポックミリ秒引数、TimeProvider インターフェース。シームが存在する場合は、制御可能な時間ソースを注入します。存在しない場合、これをテストインフラストラクチャギャップとしてフラグします: コンポーネントが時間注入をサポートするまで、時間的テストは生成できません。壁時計時刻に対してスリープまたはレースすることで時間的動作をテストしようとしないでください。

クロスモジュールトリガーチェーンの場合

ルールが別の仕様のルールが受け取るトリガーを発行する場合 (例えば、Arbiter が ClerkReceivesEvent を発行し、Clerk がそれを処理する)、チェーンのテストには複数のコンポーネントが配線が必要です。

クロスモジュールテストを生成する前に:

1. プラン出力からトリガー発行グラフをトレースします: どのルールがトリガーを発行し、どのルールが他の仕様でそれらを受け取るか
2. コードベースに参加するコンポーネントを配線する既存の統合テストフィクスチャ (パイプラインテスト、エンドツーエンドテストヘルパー、テストハーネスクラス) があるかどうかを確認します
3. フィクスチャが存在する場合、それを再利用します。クロスモジュールテストは既存の配線を合成すべきであり、それを再構築するべきではありません
4. フィクスチャが存在しないが、コードベース構造が配線を理解するのに十分明確な場合 (サービスコンストラクタ、依存性注入、イベントバス設定)、フィクスチャとテストを生成します
5. 配線が生成する自信なく複雑またはあいまいな場合、コンポーネント配線が必要な場所を示す TODO でテストスケルトンを生成します

クロスモジュールテストは本質的に統合テストです。仕様のトリガーチェーンがコンポーネント境界全体で忠実に実装されていることを確認します。単一コンポーネントテストが成功した後に優先順位付けします。

既存テストの再利用

コードベースを探索するとき、既存のテストでカバーされている仕様義務をメモします。イベント送信からアクノレッジ出力までのハッピーパスを実行する既存の統合テストは、すでに複数の rule_success 義務とエンドツーエンドシナリオをカバーしています。

既存のテストが仕様義務をカバーする場合、重複を生成するのではなく、それを参照します。伝播スキルの価値は統合レベルにおいて、カバレッジが仕様の義務リストに対して完全であることを確認し、ギャップを特定し、それらを満たすテストを生成することです。動作する手書きテストを生成されたものに置き換えることには価値がありません。

遅延仕様の場合

遅延仕様は別のファイルで完全に指定されます。ターゲットコードベースが遅延仕様のモジュールを含まない場合、プレースホルダを含むテストスタブを生成します:

// TODO: deferred spec — InterviewerMatching.suggest
// この動作は遅延として指定されています。モックを提供するかスキップしてください。

プロセス

1. 仕様を読む — エンティティ、ルール、サーフェス、不変条件、遷移グラフ、状態依存フィールド、契約、設定、デフォルトを理解します。仕様の評価 を読んで仕様の成熟度を測定します。粗い仕様 (エンティティと遷移グラフだけでルールなし) は制限されたテスト義務を生成します — ほぼ構造テストです。仕様が意味のあるテスト生成に対して粗すぎる場合、テストを伝播させる前に elicit または distill スキルを使用してそれをさらに開発することを提案します。ルールとサーフェスを持つ仕様は、データフローチェーンテストと到達可能性テストを含む完全なテストタクソノミーを有効にします。
2. テスト義務を読む — allium plan 出力または手動導出から
3. ドメインモデルを読む — allium model 出力または手動導出から
4. コードベースを探索する — 既存テスト、テストフレームワーク、エンティティ実装、ルール実装を見つけます
5. コンストラクトをコードにマップする — 仕様エンティティ/ルール/サーフェスを実装クラス/関数/エンドポイントと相関させます
6. テストを生成する — プロジェクトの規則に従ったテストファイルを作成します
7. テストコンパイル/実行を確認する — 生成されたテストが構文的に有効であることを確認します

検出チェックリスト

テストを生成する前に以下を確立します:

• テストフレームワークとランナー (Jest、pytest、cargo test など)
• PBT フレームワーク(存在する場合) (fast-check、Hypothesis、proptest など)
• テストファイル位置の規則 (コロケーション、__tests__/、tests/ など)
• エンティティ/モデル位置とパターン (クラス、インターフェース、構造体)
• テストデータのためのファクトリ/フィクスチャパターン
• 状態遷移の実装方法 (メソッド、イベント、ステートマシン)
• サーフェスの実装方法 (ルート、コントローラー、リゾルバー)
• 既存のテストヘルパーまたはユーティリティ
• コンポーネントが時間的テスト用に注入された時間ソースを受け入れるかどうか
• クロスモジュールトリガーチェーン用に統合テストフィクスチャが存在するかどうか
• どの仕様義務が既存のテストでカバーされているか

ジェネレータの認識

ジェネレータ仕様が利用可能な場合、それを使用して有効なテストデータを生成します:

• フィールド型と制約を尊重します
• 遷移グラフを持つエンティティについて、特定のライフサイクル状態にあるエンティティを生成し、when 句に従って正しいフィールド存在を含みます (例えば、shipped Order は tracking_number と shipped_at が入力されていて、pending Order はされていません)
• 不変条件について、境界条件を実行する状態を生成します
• 設定パラメータについて、オーバーライドをテストしない限り宣言されたデフォルトを使用します

他のツールとのインタラクション

• distill はコードから仕様を生成します。それらの仕様が propagate を供給します。
• weed は整合性をチェックします。テストを伝播させた後、weed は仕様コード一致を確認します。
• tend は仕様を発展させます。仕様変更後、テストを更新するために propagate を再度実行します。
• elicit は会話を通じて仕様を構築します。仕様が準備できたら、propagate がテストを生成します。

制限事項

• 生成されたテストは開始点です。プロジェクト固有のパターンに対して調整が必要な場合があります。
• 実装ブリッジは LLM 仲介です。複雑または異常なコードベースはマッピングについて手動ガイダンスが必要な場合があります。
• クロスモジュールテストはサービス境界全体でのコンポーネント配線の理解を必要とします。コードベース構造が明確な場合、完全なテストが生成できます。配線が不透明な場合、テストはコンポーネント配線が必要な場所を示す TODO でスケルトンとして生成されます。
• ランタイムトレース検証とモデルチェックは別の作業ストリームです。