xUnit 測試專案設定指南

適用情境

當被要求執行以下任務時，請使用此技能：

•建立新的 xUnit 測試專案
•設定 .NET 測試專案結構
•配置 xUnit 相依套件與 NuGet 套件
•規劃測試專案的資料夾組織
•設定程式碼覆蓋率收集工具
•理解測試專案的 csproj 設定

專案結構最佳實踐

建議的解決方案結構

text

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

結構原則：

•src 與 tests 分離：清楚區分生產程式碼與測試程式碼
•命名慣例：測試專案名稱為 {主專案名稱}.Tests
•目錄對應：測試專案的資料夾結構應對應主專案的結構
•一對一映射：每個主專案應有對應的測試專案

建立 xUnit 測試專案

方法一：使用 .NET CLI（推薦）

步驟 1：建立解決方案與專案

powershell

# 建立解決方案
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：安裝程式碼覆蓋率工具

powershell

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

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

方法二：使用 Visual Studio

•
建立解決方案
- •File → New → Project
- •選擇「Blank Solution」
- •命名為專案名稱
•
加入主專案
- •右鍵解決方案 → Add → New Project
- •選擇「Class Library」
- •命名為 MyProject.Core
•
加入測試專案
- •右鍵解決方案 → Add → New Project
- •搜尋並選擇「xUnit Test Project」
- •命名為 MyProject.Core.Tests
•
設定專案參考
- •右鍵測試專案 → Add → Project Reference
- •勾選主專案

xUnit 測試專案的 csproj 設定

標準 xUnit 測試專案 csproj

請參考同目錄下的 templates/xunit-test-project.csproj 範本檔案。

核心相依套件說明：

•
xunit（2.9.3+）
- •xUnit 測試框架的核心套件
- •提供 [Fact]、[Theory] 等測試屬性
- •包含 Assert 類別與斷言方法
•
xunit.runner.visualstudio（3.0.0+）
- •Visual Studio Test Explorer 整合
- •讓測試能在 VS Code、Visual Studio、Rider 中被探索與執行
- •支援測試結果的即時顯示
•
Microsoft.NET.Test.Sdk（17.12.0+）
- •.NET 測試平台的 SDK
- •讓 dotnet test 指令能夠執行測試
- •支援測試結果報告與測試探索
•
coverlet.collector（6.0.3+）
- •程式碼覆蓋率收集工具
- •與 dotnet test 整合
- •產生覆蓋率報告（支援 Cobertura、OpenCover 等格式）

重要 csproj 設定項目

xml

<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 的參考型別檢查

測試類別基本結構

標準測試類別範本

csharp

namespace MyProject.Core.Tests;

public class CalculatorTests
{
    private readonly Calculator _calculator;

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

測試生命週期（重要概念）

xUnit 的測試隔離機制：

•每個測試方法都會創建新的測試類別實例
•建構函式：在每個測試方法執行前被呼叫
•測試方法：執行測試邏輯
•Dispose()：如果實作 IDisposable，在每個測試方法執行後被呼叫

執行順序範例：

text

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

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

這確保了 測試隔離，符合 FIRST 原則的 I (Independent)。

執行測試

使用 .NET CLI

powershell

# 建置專案
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）

•安裝 C# Dev Kit
•開啟 Test Explorer（測試總管）
•點擊測試旁的播放按鈕執行

Visual Studio

•開啟 Test Explorer（測試 → Test Explorer）
•點擊「Run All」執行所有測試
•可以右鍵單一測試執行或偵錯

JetBrains Rider

•測試方法旁會出現綠色執行圖示
•點擊執行或偵錯測試
•使用 Unit Tests 視窗管理測試

專案參考設定原則

參考方向規則

text

測試專案 → 主專案   ✅ 正確
主專案 → 測試專案   ❌ 錯誤

測試專案應該參考主專案，但主專案絕對不應參考測試專案。

設定專案參考

powershell

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

在 csproj 中會產生：

xml

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

進階：多個測試專案的組織

當專案變大時，可能需要多個測試專案：

text

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 - 效能測試

實際工作專案的命名規範

在實際的工作專案中，建議使用更明確的命名格式來區分測試類型：

推薦的命名格式：

text

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
- •特性：測試多個元件的整合，可能依賴外部資源
- •執行速度：較慢（秒級）

這種命名的優勢：

•
清晰度：一眼就能分辨測試類型

•

執行策略：可以在 CI/CD 中分階段執行

powershell

# 快速回饋：只執行單元測試
dotnet test --filter "FullyQualifiedName~.Test.Unit"

# 完整驗證：執行整合測試
dotnet test --filter "FullyQualifiedName~.Test.Integration"

•
相依性管理：整合測試可以有不同的套件相依（如 Testcontainers）
•
團隊協作：新成員能快速理解專案結構

CLI 建立範例：

powershell

# 建立單元測試專案
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 看不到測試？

檢查清單：

•確認已安裝 xunit.runner.visualstudio 套件
•確認已安裝 Microsoft.NET.Test.Sdk 套件
•執行 dotnet build 重新建置
•重啟 IDE 或重新載入 Test Explorer

Q2: 測試可以在 CLI 執行但在 IDE 中無法執行？

解決方案：

•確認 IDE 已安裝相關擴充套件（VS Code 需要 C# Dev Kit）
•清除快取：刪除 bin/ 和 obj/ 資料夾後重新建置
•檢查 .csproj 中的 IsTestProject 屬性是否為 true

Q3: 如何在測試專案中使用 Internal 類別？

在主專案的 .csproj 或 AssemblyInfo.cs 中加入：

csharp

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

或在 csproj 中：

xml

<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 可以探索到測試

參考資源

原始文章

本技能內容提煉自「老派軟體工程師的測試修練 - 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 測試最佳實踐

dotnet-testing-xunit-project-setup

xUnit 測試專案設定指南

適用情境

專案結構最佳實踐

建議的解決方案結構

建立 xUnit 測試專案

方法一：使用 .NET CLI（推薦）

步驟 1：建立解決方案與專案

步驟 2：安裝程式碼覆蓋率工具

方法二：使用 Visual Studio

xUnit 測試專案的 csproj 設定

標準 xUnit 測試專案 csproj

重要 csproj 設定項目

測試類別基本結構

標準測試類別範本

測試生命週期（重要概念）

執行測試

使用 .NET CLI

在 IDE 中執行

VS Code（需安裝 C# Dev Kit）

Visual Studio

JetBrains Rider

專案參考設定原則

參考方向規則

設定專案參考

進階：多個測試專案的組織

實際工作專案的命名規範

常見問題與解決方案

Q1: 測試探索失敗，Test Explorer 看不到測試？

Q2: 測試可以在 CLI 執行但在 IDE 中無法執行？

Q3: 如何在測試專案中使用 Internal 類別？

範本檔案

檢查清單

參考資源

原始文章

官方文件

相關技能