dotnet-testing-xunit-project-setup

xUnit テストプロジェクト設定ガイド

プロジェクト構造のベストプラクティス

推奨されるソリューション構造

MyProject/
├── src/                          # 主程式碼目錄
│   └── MyProject.Core/
│       ├── MyProject.Core.csproj
│       ├── Calculator.cs
│       ├── Services/
│       └── Models/
├── tests/                        # 測試程式碼目錄
│   └── MyProject.Core.Tests/
│       ├── MyProject.Core.Tests.csproj
│       ├── CalculatorTests.cs
│       ├── Services/
│       └── Models/
└── MyProject.sln

構造の原則：

1. src と tests の分離：本番コードとテストコードを明確に区別する
2. 命名規則：テストプロジェクト名は {メインプロジェクト名}.Tests
3. ディレクトリの対応：テストプロジェクトのフォルダー構造はメインプロジェクトの構造に対応させる
4. 1 対 1 のマッピング：各メインプロジェクトには対応するテストプロジェクトが必要

xUnit テストプロジェクトの作成

方法 1：.NET CLI を使用する（推奨）

ステップ 1：ソリューションとプロジェクトの作成

# 建立解決方案
dotnet new sln -n MyProject

# 建立主專案（類別庫）
dotnet new classlib -n MyProject.Core -o src/MyProject.Core

# 建立測試專案（xUnit 範本）
dotnet new xunit -n MyProject.Core.Tests -o tests/MyProject.Core.Tests

# 將專案加入解決方案
dotnet sln add src/MyProject.Core/MyProject.Core.csproj
dotnet sln add tests/MyProject.Core.Tests/MyProject.Core.Tests.csproj

# 建立專案參考（測試專案參考主專案）
dotnet add tests/MyProject.Core.Tests/MyProject.Core.Tests.csproj reference src/MyProject.Core/MyProject.Core.csproj

ステップ 2：コードカバレッジツールのインストール

# 切換到測試專案目錄
cd tests/MyProject.Core.Tests

# 安裝 coverlet.collector（用於收集程式碼覆蓋率）
dotnet add package coverlet.collector

方法 2：Visual Studio を使用する

1. ソリューションの作成

   • File → New → Project
   • 「Blank Solution」を選択
   • プロジェクト名を付ける

2. メインプロジェクトの追加

   • ソリューションを右クリック → Add → New Project
   • 「Class Library」を選択
   • MyProject.Core と命名

3. テストプロジェクトの追加

   • ソリューションを右クリック → Add → New Project
   • 「xUnit Test Project」を検索して選択
   • MyProject.Core.Tests と命名

4. プロジェクト参照の設定

   • テストプロジェクトを右クリック → Add → Project Reference
   • メインプロジェクトにチェックを入れる

xUnit テストプロジェクトの csproj 設定

標準的な xUnit テストプロジェクトの csproj

同じディレクトリにある templates/xunit-test-project.csproj テンプレートファイルを参照してください。

主要な依存パッケージの説明：

1. xunit（2.9.3+）

   • xUnit テストフレームワークの中核パッケージ
   • [Fact]、[Theory] などのテスト属性を提供
   • Assert クラスとアサーションメソッドを含む

2. xunit.runner.visualstudio（3.0.0+）

   • Visual Studio Test Explorer との統合
   • VS Code、Visual Studio、Rider でテストを探索・実行できるようにする
   • テスト結果のリアルタイム表示をサポート

3. Microsoft.NET.Test.Sdk（18.3.0+）

   • .NET テストプラットフォームの SDK
   • dotnet test コマンドでテストを実行できるようにする
   • テスト結果レポートとテスト探索をサポート

4. coverlet.collector（8.0.0+）

   • コードカバレッジ収集ツール
   • dotnet test と統合
   • カバレッジレポートを生成（Cobertura、OpenCover などの形式をサポート）

重要な csproj 設定項目

<PropertyGroup>
  <TargetFramework>net9.0</TargetFramework>
  <ImplicitUsings>enable</ImplicitUsings>
  <Nullable>enable</Nullable>
  <IsPackable>false</IsPackable>
  <IsTestProject>true</IsTestProject>
</PropertyGroup>

設定の説明：

• IsPackable=false：テストプロジェクトは NuGet パッケージとしてパッケージ化すべきではない
• IsTestProject=true：テストプロジェクトであることを明示的にマークし、ツールに認識させる
• Nullable=enable：Null 許容参照型のチェックを有効にする

テストクラスの基本構造

標準的なテストクラスのテンプレート

namespace MyProject.Core.Tests;

public class CalculatorTests
{
    private readonly Calculator _calculator;

    // 建構函式：每個測試執行前都會被呼叫
    public CalculatorTests()
    {
        _calculator = new Calculator();
    }
}

テストライフサイクル（重要な概念）

xUnit のテスト分離の仕組み：

1. 各テストメソッドごとに新しいテストクラスのインスタンスが作成される
2. コンストラクター：各テストメソッドの実行前に呼び出される
3. テストメソッド：テストロジックを実行する
4. Dispose()：IDisposable を実装している場合、各テストメソッドの実行後に呼び出される

実行順序の例：

執行 Test1：
  → 建構函式 → Test1 方法 → Dispose()

執行 Test2：
  → 建構函式 → Test2 方法 → Dispose()

これによりテスト分離が確保され、FIRST 原則の I（Independent） に適合します。

テストの実行

.NET CLI を使用する

# 建置專案
dotnet build

# 執行所有測試
dotnet test

# 執行測試並收集程式碼覆蓋率
dotnet test --collect:"XPlat Code Coverage"

# 執行特定測試專案
dotnet test tests/MyProject.Core.Tests/MyProject.Core.Tests.csproj

# 執行測試並產生詳細輸出
dotnet test --verbosity detailed

IDE で実行する

VS Code（C# Dev Kit のインストールが必要）

1. C# Dev Kit をインストール
2. Test Explorer（テストエクスプローラー）を開く
3. テストの横にある再生ボタンをクリックして実行

Visual Studio

1. Test Explorer を開く（テスト → Test Explorer）
2. 「Run All」をクリックしてすべてのテストを実行
3. 個別のテストを右クリックして実行またはデバッグできる

JetBrains Rider

1. テストメソッドの横に緑色の実行アイコンが表示される
2. クリックしてテストを実行またはデバッグ
3. Unit Tests ウィンドウでテストを管理

プロジェクト参照の設定原則

参照方向のルール

測試專案 → 主專案   （正確）
主專案 → 測試專案   （錯誤）

テストプロジェクトはメインプロジェクトを参照すべきですが、メインプロジェクトがテストプロジェクトを参照することは絶対に避けてください。

プロジェクト参照の設定

# 讓測試專案參考主專案
dotnet add tests/MyProject.Core.Tests/MyProject.Core.Tests.csproj reference src/MyProject.Core/MyProject.Core.csproj

csproj には次のように生成されます：

<ItemGroup>
  <ProjectReference Include="..\..\src\MyProject.Core\MyProject.Core.csproj" />
</ItemGroup>

発展：複数のテストプロジェクトの構成

プロジェクトが大きくなると、複数のテストプロジェクトが必要になる場合があります：

MyProject/
├── src/
│   ├── MyProject.Core/
│   ├── MyProject.Web/
│   └── MyProject.Infrastructure/
├── tests/
│   ├── MyProject.Core.Tests/           # 單元測試
│   ├── MyProject.Web.Tests/            # Web 層測試
│   ├── MyProject.Infrastructure.Tests/ # 基礎設施測試
│   └── MyProject.Integration.Tests/    # 整合測試
└── MyProject.sln

命名規則の推奨：

• *.Tests - 単体テスト
• *.Integration.Tests - 統合テスト
• *.Acceptance.Tests - 受け入れテスト
• *.Performance.Tests - パフォーマンステスト

実際の業務プロジェクトにおける命名規範

実際の業務プロジェクトでは、テストの種類を区別するためにより明確な命名形式を使用することを推奨します：

推奨される命名形式：

MyProject/
├── src/
│   ├── MyProject.Core/
│   └── MyProject.WebApi/
├── tests/
│   ├── MyProject.Core.Test.Unit/              # 單元測試（明確標示）
│   ├── MyProject.WebApi.Test.Unit/            # WebApi 單元測試
│   └── MyProject.WebApi.Test.Integration/     # WebApi 整合測試
└── MyProject.sln

命名ルール：

• 単体テスト：{プロジェクト名}.Test.Unit

  • 例：MyProject.Core.Test.Unit
  • 特性：外部リソース（データベース、API、ファイルシステムなど）に依存しない
  • 実行速度：高速（ミリ秒単位）

• 統合テスト：{プロジェクト名}.Test.Integration

  • 例：MyProject.WebApi.Test.Integration
  • 特性：複数のコンポーネントの統合をテストし、外部リソースに依存する場合がある
  • 実行速度：比較的遅い（秒単位）

この命名の利点：

1. 明確さ：一目でテストの種類を判別できる

2. 実行戦略：CI/CD で段階的に実行できる

   # 快速回饋：只執行單元測試
   dotnet test --filter "FullyQualifiedName~.Test.Unit"
   
   # 完整驗證：執行整合測試
   dotnet test --filter "FullyQualifiedName~.Test.Integration"
   

3. 依存関係の管理：統合テストは異なるパッケージ依存（Testcontainers など）を持てる

4. チーム協力：新しいメンバーがプロジェクト構造をすばやく理解できる

CLI での作成例：

# 建立單元測試專案
dotnet new xunit -n MyProject.Core.Test.Unit -o tests/MyProject.Core.Test.Unit
dotnet add tests/MyProject.Core.Test.Unit reference src/MyProject.Core

# 建立整合測試專案
dotnet new xunit -n MyProject.WebApi.Test.Integration -o tests/MyProject.WebApi.Test.Integration
dotnet add tests/MyProject.WebApi.Test.Integration reference src/MyProject.WebApi

ヒント：この例では説明を簡略化するために .Tests 形式を使用していますが、実際のプロジェクトでは .Test.Unit と .Test.Integration というより明確な形式を強く推奨します。

よくある問題と解決策

Q1: テスト探索に失敗し、Test Explorer にテストが表示されない？

チェックリスト：

1. xunit.runner.visualstudio パッケージがインストールされていることを確認する
2. Microsoft.NET.Test.Sdk パッケージがインストールされていることを確認する
3. dotnet build を実行して再ビルドする
4. IDE を再起動するか、Test Explorer を再読み込みする

Q2: テストは CLI で実行できるが IDE で実行できない？

解決策：

• IDE に関連する拡張機能がインストールされていることを確認する（VS Code には C# Dev Kit が必要）
• キャッシュをクリアする：bin/ と obj/ フォルダーを削除して再ビルドする
• .csproj の IsTestProject プロパティが true であるか確認する

Q3: テストプロジェクトで Internal クラスを使用するには？

メインプロジェクトの .csproj または AssemblyInfo.cs に追加します：

[assembly: InternalsVisibleTo("MyProject.Core.Tests")]

または csproj に：

<ItemGroup>
  <InternalsVisibleTo Include="MyProject.Core.Tests" />
</ItemGroup>

テンプレートファイル

同じディレクトリにあるテンプレートファイルを参照して、プロジェクトをすばやく作成してください：

• templates/project-structure.md - 完全なプロジェクト構造の例
• templates/xunit-test-project.csproj - xUnit テストプロジェクトの csproj テンプレート

チェックリスト

xUnit テストプロジェクトを作成する際は、以下の項目を確認してください：

• テストプロジェクト名が {メインプロジェクト名}.Tests である
• テストプロジェクトが tests/ ディレクトリにある
• xunit、xunit.runner.visualstudio、Microsoft.NET.Test.Sdk パッケージがインストールされている
• コードカバレッジ用に coverlet.collector がインストールされている
• テストプロジェクトがメインプロジェクトを参照している
• IsPackable が false に設定されている
• IsTestProject が true に設定されている
• dotnet test を正常に実行できる
• IDE の Test Explorer でテストを探索できる

輸出格式

• 產生完整的 xUnit 測試專案結構（src/ 與 tests/ 分離）
• 產生測試專案 csproj 檔案（含必要套件參考）
• 提供 dotnet CLI 建立指令序列
• 包含專案參考設定與 xunit.runner.json 配置（如需要）
• 產生基本測試類別範本（.cs 檔案）

參考資源

原始文章

本技能內容提煉自「老派軟體工程師的測試修練 - 30 天挑戰」系列文章：

• Day 02 - xUnit 框架深度解析

  • 鐵人賽文章：https://ithelp.ithome.com.tw/articles/10373952
  • 範例程式碼：https://github.com/kevintsengtw/30Days_in_Testing_Samples/tree/main/day02

• Day 03 - xUnit 進階功能與測試資料管理

  • 鐵人賽文章：https://ithelp.ithome.com.tw/articles/10374064
  • 範例程式碼：https://github.com/kevintsengtw/30Days_in_Testing_Samples/tree/main/day03

官方文件

• xUnit 官方文件
• .NET 測試最佳實踐

相關技能

• unit-test-fundamentals - 單元測試基礎與 FIRST 原則
• test-naming-conventions - 測試命名規範
• code-coverage-analysis - 程式碼覆蓋率分析