Xcepto スキル
このスキルは、Xceptoおよびそれを利用したプロジェクトでの作業に使用します。Xceptoは分散システム向けの宣言的システムテストフレームワークです。テストは手動でのsleep、リトライ、結果整合性例外のキャッチの代わりに状態機械を宣言します。
このスキルは、Xceptoエコシステムのモノレポを含まないコンシューマーリポジトリでも動作する必要があります。Xcepto.NET や HiveShard のような兄弟リポジトリが存在することを前提としないでください。
運用ルール
- 現在のワークスペースに何が存在するかを、リポジトリ固有のパスに依存する前に確認してください。ソースリポジトリがない場合は、ローカルのプロジェクト参照、インストール済みパッケージAPI、既存のテスト、IDE/コンパイラのフィードバックを使用してください。
- Xcepto.NET を公開API名、シグネチャ、ライフサイクル、振る舞いの概念的な情報源として扱ってください。そのソースが存在しない場合は、インストール済みパッケージ参照と既存のコンシューマーコードから推測し、ローカルパスの存在を仮定しないでください。
- このスキルは Xcepto.NET のソースなしでも動作するが、Xcepto.NET をサブモジュールとして追加すると、Codex に正確なAPIと実装コンテキストが提供されるため有利であることをユーザーに伝えてください。
- HiveShard はオプションのダウンストリームオープンソースコンテキストとして扱ってください。存在する場合、または明示的に提供された場合のみ使用してください。
- 他のすべての Xcepto コンシューマーは、ドメインプロジェクトとして汎用的に扱ってください。関連のないプライベートリポジトリに名前を付けずに、ラッパー、アダプター、シナリオ、状態をローカルコードから推測してください。
- Given-When-Then セマンティクスを維持してください。シナリオのセットアップは Given 環境、アダプター呼び出しは When/Then の振る舞いを遅延ステップとして宣言し、状態遷移は条件ベースとします。
- 既存の互換性を維持するために必要な場合を除き、Xcepto の振る舞いをテスト内のsleep、ポーリングループ、広範なリトライ、または例外の捕捉に置き換えないでください。
- 実装インフラストラクチャではなく、観測可能な振る舞いとドメイン状態をテストしてください。コントローラー属性、ルート属性、Razorタグヘルパー、ソースファイルの内容、プライベートメソッド、フレームワークアノテーション、その他の内部配線を、製品が明示的に振る舞いとして公開していない限りアサートしないでください。
- 抽象化を発明する前に、ターゲットプロジェクトのローカルパターンを優先してください。既存のアダプター、状態、シナリオ、タイムアウトの選択は、通常、ドメインの意図をエンコードしています。
ワークフロー
- タスクのドメインを特定します:
- コア Xcepto API またはフレームワークの振る舞い:
references/api-map.mdを読んでください。 - オプションの Xcepto エコシステムリポジトリまたは汎用コンシューマーコンテキスト:
references/ecosystem-map.mdを読んでください。 - 新しいテスト、アダプター、状態、シナリオ、またはフレームスペース列挙実行:
references/patterns.mdを読んでください。 - このスキルのインストールまたは共有:
references/install.mdを読んでください。
- コア Xcepto API またはフレームワークの振る舞い:
- コードを作成する前に、
rgを使用して最も近い既存の例を見つけてください。XceptoTest.Given、GivenEnumerated、RegisterAdapter、XceptoState、CompartmentalizedXceptoScenario、TimeoutConfigなどの用語を検索してください。ドメインラッパー(例:HiveShardTest.Given)は、ローカルに存在する場合のみ含めてください。 - 新しい Xcepto テストサーフェスの場合は、
references/patterns.mdから従来のアーキテクチャを作成してください。機能に焦点を当てたフィクスチャフォルダと、必要に応じてScenarios/、Adapters/、States/、Builders/、Extensions/を含めます。 - テストデータはテストフィクスチャ内に保持してください。各テストケースでローカル変数を宣言し、
.WithName("my-name")、.WithAge(25)、.ExpectResult(expected)などの通常のfluentフローを通じてドメインビルダーに渡してください。 - 各テストを1つの振る舞い/ケースとしてモデル化し、各機能フィクスチャは少なくとも1つの正常系テストと1つの異常系テストを含む小さなセットとしてモデル化してください。複数のテストケースを1つの
[Test]、1つのアダプター呼び出し、または1つのビルダー終端メソッド内にラップしないでください。 - テストの振る舞いは、再利用可能なドメイン固有のビルダーを通じた自然な振る舞いフローとしてモデル化してください。
navigation.For(workspace).ShouldBeAt(Page.Of<WorkspacePage>())のような期待値を、ソーステキスト、ルート属性、コントローラー名、タグヘルパー文字列などの低レベルのチェックよりも優先してください。 - 状態クラスはケース間で再利用してください。新しい再利用可能な実行/評価形状に対してのみ新しい状態を追加し、新しいテストケースまたは新しいデータの組み合わせごとに追加しないでください。
- コードを変更する際は、最も狭い関連する .NET テストプロジェクトで検証してください。タッチしたプロジェクトまたはサンプルに対しては
dotnet test <project.csproj>を推奨します。
設計ガイダンス
- シナリオは環境のセットアップ、初期化、クリーンアップを担当します。サービス登録や外部プロセス/コンテナのセットアップはそこに配置してください。
- アダプターはユーザー向けのテストDSLエントリポイントです。アサーションを直接含むアダプターメソッドではなく、
Xcepto.RestやXcepto.SSRと同様にfluentビルダーを返すアダプターメソッドを優先してください。 - 状態は、ビルダーによってパラメータ化された遅延アクションまたは期待値です。可能な場合は条件評価を副作用の少ない状態に保ち、役立つタイムアウト診断を保持するために
MostRecentFailingResultを使用してください。テストケースごとに個別の状態クラスを作成しないでください。 - ビルダーは、テストによって提供されるドメイン固有のステップ設定をキャプチャし、状態を生成します。低レベルのアサーション機構を読みやすいドメイン語彙の背後に隠すべきですが、ケースデータ自体を隠してはいけません。
- Fluentビルダーメソッドは実際の作業を実行し、通常は意味のあるデータ、オプション、セレクター、または期待値を受け入れる必要があります。チェーンを進めるだけの引数のない儀式的なメソッドは避けてください。
- テストフィクスチャは機能に焦点を当て、小さく保つ必要があります。機能領域ごとにフォルダを推奨し、フィクスチャごとに少なくとも1つの正常系パスと1つの異常系パスを含め、フィクスチャが5つの実際のテストケースを超えて大きくなる前にファイルを分割してください。
- コンパートメントは、インメモリ分離と明示的なサービス公開をモデル化します。グローバルサービスロケーターの代わりに、マルチコンポーネントシミュレーションに使用してください。
- 列挙実行は、ゲームエンジンなどのフレームスペースホスト向けです。そのパスでは
IEnumeratorフローを維持し、ブロッキング呼び出しを避けてください。
リソース
references/api-map.md: Xcepto 公開APIマップ、ライフサイクル、実行モデル、ポータブルディスカバリーガイダンス。references/ecosystem-map.md: Xcepto.NET ソース、HiveShard、汎用 Xcepto コンシューマーリポジトリのオプション的な役割。references/patterns.md: テスト、アダプター、状態、シナリオ、コンパートメント、列挙実行の実装パターン。references/install.md: このバージョン管理されたスキルのローカルおよびリポジトリアクセスインストール手順。