dotnet-testing-xunit-project-setup

name

dotnet-testing-xunit-project-setup

description

xUnit 測試專案建立與設定的專門技能。當需要建立測試專案、設定專案結構、配置 NuGet 套件、組織測試資料夾時使用。涵蓋 csproj 設定、套件管理、專案結構、xunit.runner.json 配置等。 Make sure to use this skill whenever the user mentions creating a test project, xUnit setup, project structure for tests, NuGet test packages, or csproj configuration for testing, even if they don't explicitly ask for project setup guidance. Keywords: xunit project, xunit setup, 測試專案建立, test project setup, 建立測試專案, project structure, 專案結構, folder structure, xunit package, nuget packages, 測試套件, 如何建立測試專案, xunit configuration

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. 一對一映射：每個主專案應有對應的測試專案

建立 xUnit 測試專案

方法一：使用 .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

方法二：使用 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 - 程式碼覆蓋率分析