dotnet-testing-test-naming-conventions-lite

# .NET 測試命名規範指南 ## 測試方法命名規範 ### 標準格式 使用底線分隔的三段式命名法： ```text [被測試方法名稱]_[測試情境/輸入條件]_[預期行為/結果] ``` ### 各段說明 | 區段 | 說明 | 範例 | | --------------------- | ------------------------ | ------------------------------------------ | | **被測試方法名稱** | 正在測試的方法名稱 | `Add`、`ProcessOrder`、`IsValidEmail` | | **測試情境/輸入條件** | 描述測試的前置條件或輸入 | `輸入1和2`、`輸入null`、`輸入有效訂單` | | **預期行為/結果** | 描述預期的輸出或行為 | `應回傳3`、`應拋出Exception`、`應回傳True` | ## 命名範例對照表 ### 好的命名 vs 不好的命名 三段式命名可以使用中文或英文，依團隊慣例選擇。以下同時展示兩種風格： | 不好的命名 | 中文命名（推薦） | 英文命名 | 原因 | | ------------- | --------------------------------------------------- | ------------------------------------------------------------- | -------------------------- | | `TestAdd` | `Add_輸入1和2_應回傳3` | `Add_WhenGiven1And2_ShouldReturn3` | 清楚說明測試情境與預期結果 | | `Test1` | `Add_輸入負數和正數_應回傳正確結果` | `Add_WhenGivenNegativeAndPositive_ShouldReturnCorrectResult` | 有意義的描述 | | `EmailTest` | `IsValidEmail_輸入有效Email_應回傳True` | `IsValidEmail_WhenValidEmail_ShouldReturnTrue` | 完整的三段式命名 | | `OrderTest` | `ProcessOrder_輸入null_應拋出ArgumentNullException` | `ProcessOrder_WhenNull_ShouldThrowArgumentNullException` | 明確的例外情境 | ## 實際範例 ### 基本運算測試 ```csharp // ✅ 正常路徑測試 [Fact] public void Add_輸入1和2_應回傳3() // ✅ 邊界條件測試 [Fact] public void Add_輸入0和0_應回傳0() // ✅ 負數測試 [Fact] public void Add_輸入負數和正數_應回傳正確結果() ``` ### 驗證邏輯測試 ```csharp // ✅ 有效輸入測試 [Fact] public void IsValidEmail_輸入有效Email_應回傳True() // ✅ 無效輸入 - null [Fact] public void IsValidEmail_輸入null值_應回傳False() // ✅ 無效輸入 - 空字串 [Fact] public void IsValidEmail_輸入空字串_應回傳False() // ✅ 無效輸入 - 格式錯誤 [Fact] public void IsValidEmail_輸入無效Email格式_應回傳False() ``` ### 業務邏輯測試 ```csharp // ✅ 處理流程測試 [Fact] public void ProcessOrder_輸入有效訂單_應回傳處理後訂單() // ✅ 例外處理測試 [Fact] public void ProcessOrder_輸入null_應拋出ArgumentNullException() // ✅ 格式化測試 [Fact] public void GetOrderNumber_輸入有效訂單_應回傳格式化訂單號碼() ``` ### 計算邏輯測試 ```csharp // ✅ 正常計算 [Fact] public void Calculate_輸入100元和10Percent折扣_應回傳90元() // ✅ 無效輸入 - 負數 [Fact] public void Calculate_輸入負數價格_應拋出ArgumentException() // ✅ 邊界值測試 [Fact] public void Calculate_輸入0元價格_應正常處理() // ✅ 含稅計算 [Fact] public void CalculateWithTax_輸入100元和5Percent稅率_應回傳105元() ``` ### 狀態變化測試 ```csharp // ✅ 初始狀態測試 [Fact] public void Increment_從0開始_應回傳1() // ✅ 連續操作測試 [Fact] public void Increment_從0開始連續兩次_應回傳2() // ✅ 重設測試 [Fact] public void Reset_從任意值_應回傳0() ``` ## 測試類別命名規範 ### 標準格式 ```text [被測試類別名稱]Tests ``` ### 範例 | 被測試類別 | 測試類別名稱 | | ----------------- | ---------------------- | | `Calculator` | `CalculatorTests` | | `OrderService` | `OrderServiceTests` | | `EmailHelper` | `EmailHelperTests` | | `PriceCalculator` | `PriceCalculatorTests` | ### 類別結構範本 ```csharp namespace MyProject.Tests; /// <summary> /// class CalculatorTests - Calculator 測試類別 /// </summary> public class CalculatorTests { private readonly Calculator _calculator; public CalculatorTests() { _calculator = new Calculator(); } //--------------------------------------------------------------------------------------------- // Add 方法測試 [Fact] public void Add_輸入1和2_應回傳3() { // ... } //--------------------------------------------------------------------------------------------- // Divide 方法測試 [Fact] public void Divide_輸入10和2_應回傳5() { // ... } } ``` ## 參數化測試命名 使用 `[Theory]` 時的命名規範： ```csharp // ✅ 使用「各種」表示多組測試資料 [Theory] [InlineData(1, 2, 3)] [InlineData(-1, 1, 0)] [InlineData(0, 0, 0)] public void Add_輸入各種數值組合_應回傳正確結果(int a, int b, int expected) // ✅ 使用「有效」表示正向測試 [Theory] [InlineData("test@example.com")] [InlineData("user.name@domain.org")] public void IsValidEmail_輸入有效Email格式_應回傳True(string validEmail) // ✅ 使用「無效」表示負向測試 [Theory] [InlineData("invalid-email")] [InlineData("@example.com")] public void IsValidEmail_輸入無效Email格式_應回傳False(string invalidEmail) ``` ## 常用情境詞彙 ### 輸入條件詞彙 | 詞彙 | 使用情境 | | ----------- | -------------------- | | `輸入` | 一般輸入參數 | | `給定` | Given-When-Then 風格 | | `當` | 事件觸發 | | `從...開始` | 初始狀態描述 | ### 預期結果詞彙 | 詞彙 | 使用情境 | | ------------ | -------- | | `應回傳` | 有回傳值 | | `應拋出` | 預期例外 | | `應為` | 狀態驗證 | | `應包含` | 集合驗證 | | `應正常處理` | 邊界條件 | ## 命名檢查清單 為測試方法命名時，請確認： - [ ] 使用三段式命名 `方法_情境_預期` - [ ] 情境描述清楚明確 - [ ] 預期結果具體可驗證 - [ ] 使用中文增加可讀性 - [ ] 避免模糊詞彙如 `Test1`、`TestMethod` - [ ] 參數化測試使用「各種」、「有效」、「無效」等詞彙 ## 測試報告可讀性 好的命名會讓測試報告更易讀： ```text PASS CalculatorTests PASS Add_輸入1和2_應回傳3 PASS Add_輸入負數和正數_應回傳正確結果 FAIL Divide_輸入10和0_應拋出DivideByZeroException PASS EmailHelperTests PASS IsValidEmail_輸入有效Email_應回傳True PASS IsValidEmail_輸入null值_應回傳False ``` ## 輸出格式 - 使用三段式命名法：`[方法名稱]_[測試情境]_[預期行為]` - 測試類別命名為 `{被測類別}Tests` - 情境描述使用中文以提升可讀性 - 參數化測試使用「各種」、「有效」、「無效」等詞彙 ## 參考資源 請參考同目錄下的範例檔案： - [templates/naming-convention-examples.cs](templates/naming-convention-examples.cs) - 命名規範完整範例 - [references/naming-examples.md](references/naming-examples.md) - 依測試情境分類的命名範例集，可直接複製套用 ### 原始文章 本技能內容提煉自「老派軟體工程師的測試修練 - 30 天挑戰」系列文章： - **Day 01 - 老派工程師的測試啟蒙** - 鐵人賽文章：https://ithelp.ithome.com.tw/articles/10373888 - 範例程式碼：https://github.com/kevintsengtw/30Days_in_Testing_Samples/tree/main/day01 ### 相關技能 - `dotnet-testing-unit-test-fundamentals-lite` - 單元測試基礎 - `dotnet-testing-xunit-project-setup-lite` - xUnit 專案設定