aspire-integration-testing

.NET Aspire + xUnit による統合テスト

このスキルを使用するタイミング

次の場合にこのスキルを使用してください。

• .NET Aspire アプリケーションの統合テストを作成するとき
• 実際のデータベース接続を使用して ASP.NET Core アプリをテストするとき
• 分散アプリケーションでサービス間通信を検証するとき
• コンテナー内の実際のインフラストラクチャ（SQL Server、Redis、メッセージキュー）を使用してテストするとき
• Aspire がオーケストレーションするサービスと Playwright UI テストを組み合わせるとき
• 適切なサービス検出とネットワークを使用してマイクロサービスをテストするとき

基本原則

1. 実際の依存関係 - モックではなく、Aspire を介して実際のインフラストラクチャ（データベース、キャッシュ）を使用します
2. 動的なポート割り当て - ポートの競合を避けるため、Aspire にポートを動的に割り当てさせます（127.0.0.1:0）
3. フィクスチャのライフサイクル - 適切なテストフィクスチャのセットアップと後処理には IAsyncLifetime を使用します
4. エンドポイントの検出 - URL をハードコードせず、実行時に Aspire からエンドポイントを検出します
5. 並列実行の分離 - xUnit のコレクションを使用して、テストの並列実行を制御します
6. ヘルスチェック - テストを実行する前に、必ずサービスが正常な状態になるまで待機します

テストアーキテクチャの概要

┌─────────────────┐                    ┌──────────────────────┐
│ xUnit test file │──uses────────────►│  AspireFixture       │
└─────────────────┘                    │  (IAsyncLifetime)    │
                                       └──────────────────────┘
                                               │
                                               │ starts
                                               ▼
                                    ┌───────────────────────────┐
                                    │  DistributedApplication   │
                                    │  (from AppHost)           │
                                    └───────────────────────────┘
                                               │ exposes
                                               ▼
                                  ┌──────────────────────────────┐
                                  │   Dynamic HTTP Endpoints     │
                                  └──────────────────────────────┘
                                               │ consumed by
                                               ▼
                                   ┌─────────────────────────┐
                                   │  HttpClient / Playwright│
                                   └─────────────────────────┘

必要な NuGet パッケージ

<ItemGroup>
  <PackageReference Include="Aspire.Hosting.Testing" Version="$(AspireVersion)" />
  <PackageReference Include="xunit" Version="*" />
  <PackageReference Include="xunit.runner.visualstudio" Version="*" />
  <PackageReference Include="Microsoft.NET.Test.Sdk" Version="*" />
</ItemGroup>

重要：統合テストでのファイルウォッチャーの修正

多くの統合テストを実行し、それぞれが IHost を起動する場合、既定の .NET ホストビルダーは構成の再読み込み用にファイルウォッチャーを有効にします。これにより、Linux ではファイルディスクリプターの上限に達します。

テストを実行する前に、テストプロジェクトに次の設定を追加してください。

// TestEnvironmentInitializer.cs
using System.Runtime.CompilerServices;

namespace YourApp.Tests;

internal static class TestEnvironmentInitializer
{
    [ModuleInitializer]
    internal static void Initialize()
    {
        // Disable config file watching in test hosts
        // Prevents file descriptor exhaustion (inotify watch limit) on Linux
        Environment.SetEnvironmentVariable("DOTNET_HOSTBUILDER__RELOADCONFIGONCHANGE", "false");
    }
}

これが重要な理由： [ModuleInitializer] はテストコードの実行前に実行され、テスト中に作成されるすべての IHost インスタンスに対して環境変数をグローバルに設定します。

リファレンスドキュメント

詳細なパターンと例については、次のリファレンスファイルを参照してください。

• テストフィクスチャ - xUnit のテストフィクスチャ、テストクラスの構成、フィクスチャのライフサイクルパターン、データベースのリセット戦略
• テストパターン - 個々のサービス、サービス間通信、実際のデータベース、メッセージブローカー、Playwright UI テストのテスト
• 構成例 - リソースの構成、環境変数の構成、待機戦略

よく使うパターンの概要

パターン	用途
基本的なフィクスチャ	シンプルな HTTP エンドポイントのテスト
エンドポイントの検出	URL のハードコードを回避
データベースのテスト	データアクセス層の検証
Playwright の統合	実際のバックエンドを使用した UI 全体のテスト
構成の上書き	テスト固有の設定
ヘルスチェック	サービスの準備完了を確認
サービス間通信	分散システムの相互作用をテスト
メッセージキューのテスト	非同期メッセージングの検証

注意が必要なヒント

問題	解決策
テストがすぐにタイムアウトする	await _app.StartAsync() を呼び出し、テストを実行する前にサービスが正常な状態になるまで待機します
テスト間でポートが競合する	xUnit の CollectionDefinition を使用してフィクスチャを共有し、複数のインスタンスの起動を避けます
タイミングが原因でテストが不安定になる	Task.Delay() ではなく、適切なヘルスチェックのポーリングを実装します
SQL Server に接続できない	GetConnectionStringAsync() を使用して、接続文字列が動的に取得されることを確認します
並列テストが互いに干渉する	[Collection] 属性を使用して、関連するテストを逐次実行します
Aspire ダッシュボードが競合する	Aspire ダッシュボードは同時に 1 つしか実行できません。テストでは同じダッシュボードインスタンスが再利用されます

CI/CD との統合

GitHub Actions の例

name: Integration Tests

on:
  push:
    branches: [ main, dev ]
  pull_request:
    branches: [ main, dev ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3

    - name: Setup .NET
      uses: actions/setup-dotnet@v3
      with:
        dotnet-version: 9.0.x

    - name: Restore dependencies
      run: dotnet restore

    - name: Build
      run: dotnet build --no-restore -c Release

    - name: Run integration tests
      run: |
        dotnet test tests/YourApp.IntegrationTests \
          --no-build \
          -c Release \
          --logger trx \
          --collect:"XPlat Code Coverage"

    - name: Publish test results
      uses: actions/upload-artifact@v3
      if: always()
      with:
        name: test-results
        path: "**/TestResults/*.trx"

ベストプラクティス

1. IAsyncLifetime を使用する - 非同期の初期化とクリーンアップを適切に行えます
2. コレクションを通じてフィクスチャを共有する - アプリケーションのインスタンスを再利用し、テストの実行時間を短縮できます
3. エンドポイントを動的に検出する - localhost:5000 などをハードコードしないでください
4. ヘルスチェックを待つ - サービスがすぐに利用可能になると決めつけないでください
5. 実際の依存関係を使ってテストする - Aspire を使えば、実際の SQL や Redis などを簡単に利用できます
6. リソースをクリーンアップする - 常に DisposeAsync を適切に実装してください
7. 意味のあるテストデータを使う - データベースに現実的なテストデータをシードしてください
8. 失敗するシナリオをテストする - エラー処理と回復性を検証してください
9. テストを分離する - 各テストは独立し、実行順序に依存しないようにしてください
10. テストの実行時間を監視する - テストが遅い場合は、並列化や最適化を検討してください

Aspire CLI と MCP の統合

Aspire 13.1+ には、Claude Code などの AI コーディングアシスタント向けの MCP（Model Context Protocol）統合が含まれています。これにより、AI ツールはアプリケーションの状態を照会し、ログを表示し、トレースを調査できます。

Aspire CLI のインストール

# Install the Aspire CLI globally
dotnet tool install -g aspire.cli

# Or update existing installation
dotnet tool update -g aspire.cli

Claude Code 向けの MCP の初期化

# Navigate to your Aspire project
cd src/MyApp.AppHost

# Initialize MCP configuration (auto-detects Claude Code)
aspire mcp init

これにより、Claude Code が実行中の Aspire アプリケーションに接続するために必要な設定ファイルが作成されます。

MCP を有効にして実行する

# Run your Aspire app with MCP server
aspire run

# The CLI will output the MCP endpoint URL
# Claude Code can then connect and query:
# - Resource states and health status
# - Real-time console logs
# - Distributed traces
# - Available Aspire integrations

MCP の機能

接続すると、AI アシスタントは次の操作を行えます。

• リソースを照会する - リソースの状態、エンドポイント、ヘルスステータスを取得する
• ログを使ってデバッグする - すべてのサービスのリアルタイムなコンソール出力にアクセスする
• テレメトリを調査する - 構造化ログと分散トレースを確認する
• コマンドを実行する - リソース固有のコマンドを実行する
• 統合機能を検出する - 利用可能な Aspire ホスティング統合機能（Redis、PostgreSQL、Azure サービス）を一覧表示する

開発におけるメリット

• AI アシスタントは、実際に実行中のアプリケーションの状態を確認できます
• デバッグ支援では、実際のテレメトリデータを使用します
• ログを手動でコピーして貼り付ける必要がありません
• AI は分散トレースのスパンの関連付けを支援できます

詳しくは、以下をご覧ください。

• Aspire MCP の設定
• Aspire CLI コマンド

---

デバッグのヒント

1. Aspire Dashboard を実行する - テストが失敗した場合は、http://localhost:15888 のダッシュボードを確認してください
2. MCP を使って Aspire CLI を使用する - AI アシスタントに実際のアプリケーションの状態を照会させます
3. 詳細なログを有効にする - 出力をより詳細にするには、ASPIRE_ALLOW_UNSECURED_TRANSPORT=true を設定します
4. コンテナーのログを確認する - docker logs を使ってコンテナーの出力を調査します
5. フィクスチャでブレークポイントを使う - フィクスチャの初期化をデバッグし、起動時の問題を特定します
6. リソース名を確認する - AppHost とテスト間でリソース名が一致していることを確認します