gabrielmoreira 測試輸出與記錄專家指南
本技能協助您在 .NET xUnit 測試專案中實作高品質的測試輸出與記錄機制。
核心原則
1. ITestOutputHelper 使用原則
正確的注入方式
- 透過建構式注入
ITestOutputHelper - 每個測試類別的實例與測試方法綁定
- 不可在靜態方法或跨測試方法間共用
public class MyTests
{
private readonly ITestOutputHelper _output;
public MyTests(ITestOutputHelper testOutputHelper)
{
_output = testOutputHelper;
}
}
常見錯誤
- 靜態存取：
private static ITestOutputHelper _output - 在非同步測試中未等待即使用
- 嘗試在 Dispose 方法中使用
2. 結構化輸出格式設計
建議的輸出結構
private void LogSection(string title)
{
_output.WriteLine($"\n=== {title} ===");
}
private void LogKeyValue(string key, object value)
{
_output.WriteLine($"{key}: {value}");
}
private void LogTimestamp(DateTime time)
{
_output.WriteLine($"執行時間: {time:yyyy-MM-dd HH:mm:ss.fff}");
}
輸出時機
- 測試開始時：記錄測試設置與輸入資料
- 執行過程中：記錄重要的狀態變化
- 斷言前：記錄預期值與實際值
- 測試結束時：記錄執行時間與結果摘要
3. ILogger 測試策略
挑戰：擴充方法無法直接 Mock
ILogger.LogError() 是擴充方法，NSubstitute 無法直接攔截。需要攔截底層的 Log<TState> 方法：
// ❌ 錯誤：直接 Mock 擴充方法會失敗
logger.Received().LogError(Arg.Any<string>());
// ✅ 正確：攔截底層方法
logger.Received().Log(
LogLevel.Error,
Arg.Any<EventId>(),
Arg.Is<object>(o => o.ToString().Contains("預期訊息")),
Arg.Any<Exception>(),
Arg.Any<Func<object, Exception, string>>()
);
解決方案：使用抽象層
建立 AbstractLogger<T> 來簡化測試：
public abstract class AbstractLogger<T> : ILogger<T>
{
public IDisposable BeginScope<TState>(TState state)
=> null;
public bool IsEnabled(LogLevel logLevel)
=> true;
public void Log<TState>(
LogLevel logLevel,
EventId eventId,
TState state,
Exception exception,
Func<TState, Exception, string> formatter)
{
Log(logLevel, exception, state?.ToString() ?? string.Empty);
}
public abstract void Log(LogLevel logLevel, Exception ex, string information);
}
測試時使用
var logger = Substitute.For<AbstractLogger<MyService>>();
// 現在可以簡單驗證
logger.Received().Log(LogLevel.Error, Arg.Any<Exception>(), Arg.Is<string>(s => s.Contains("錯誤訊息")));
4. 診斷工具整合
XUnitLogger：將記錄導向測試輸出
public class XUnitLogger<T> : ILogger<T>
{
private readonly ITestOutputHelper _testOutputHelper;
public XUnitLogger(ITestOutputHelper testOutputHelper)
{
_testOutputHelper = testOutputHelper;
}
public void Log<TState>(LogLevel logLevel, EventId eventId, TState state,
Exception exception, Func<TState, Exception, string> formatter)
{
var message = formatter(state, exception);
_testOutputHelper.WriteLine($"[{DateTime.Now:HH:mm:ss.fff}] [{logLevel}] [{typeof(T).Name}] {message}");
if (exception != null)
{
_testOutputHelper.WriteLine($"Exception: {exception}");
}
}
// 其他必要的介面實作...
}
CompositeLogger：同時支援驗證與輸出
public class CompositeLogger<T> : ILogger<T>
{
private readonly ILogger<T>[] _loggers;
public CompositeLogger(params ILogger<T>[] loggers)
{
_loggers = loggers;
}
public void Log<TState>(LogLevel logLevel, EventId eventId, TState state,
Exception exception, Func<TState, Exception, string> formatter)
{
foreach (var logger in _loggers)
{
logger.Log(logLevel, eventId, state, exception, formatter);
}
}
// 其他介面實作會委派給所有內部 logger...
}
使用方式
// 同時進行行為驗證與測試輸出
var mockLogger = Substitute.For<AbstractLogger<MyService>>();
var xunitLogger = new XUnitLogger<MyService>(_output);
var compositeLogger = new CompositeLogger<MyService>(mockLogger, xunitLogger);
var service = new MyService(compositeLogger);
實作指南
效能測試中的時間點記錄
[Fact]
public async Task ProcessLargeDataSet_效能測試()
{
// Arrange
var stopwatch = Stopwatch.StartNew();
var checkpoints = new List<(string Stage, TimeSpan Elapsed)>();
_output.WriteLine("開始處理大型資料集...");
// Act & Monitor
await processor.LoadData(dataSet);
checkpoints.Add(("資料載入", stopwatch.Elapsed));
_output.WriteLine($"資料載入完成: {stopwatch.Elapsed.TotalMilliseconds:F2} ms");
await processor.ProcessData();
checkpoints.Add(("資料處理", stopwatch.Elapsed));
_output.WriteLine($"資料處理完成: {stopwatch.Elapsed.TotalMilliseconds:F2} ms");
stopwatch.Stop();
// Assert & Report
_output.WriteLine("\n=== 效能報告 ===");
foreach (var (stage, elapsed) in checkpoints)
{
_output.WriteLine($"{stage}: {elapsed.TotalMilliseconds:F2} ms");
}
}
診斷測試基底類別
public abstract class DiagnosticTestBase
{
protected readonly ITestOutputHelper Output;
protected DiagnosticTestBase(ITestOutputHelper output)
{
Output = output;
}
protected void LogTestStart(string testName)
{
Output.WriteLine($"\n=== {testName} ===");
Output.WriteLine($"執行時間: {DateTime.Now:yyyy-MM-dd HH:mm:ss.fff}");
}
protected void LogTestData(object data)
{
Output.WriteLine($"測試資料: {JsonSerializer.Serialize(data, new JsonSerializerOptions { WriteIndented = true })}");
}
protected void LogAssertionFailure(string field, object expected, object actual)
{
Output.WriteLine("\n=== 斷言失敗 ===");
Output.WriteLine($"欄位: {field}");
Output.WriteLine($"預期值: {expected}");
Output.WriteLine($"實際值: {actual}");
}
}
最佳實踐
適當使用 ITestOutputHelper
- 在複雜測試中記錄重要步驟，幫助追蹤失敗原因
- 採用一致的結構化輸出格式（章節標題、時間戳記），讓輸出易於閱讀
- 在效能測試中記錄時間點，提供量化數據
Logger 測試策略
- 使用抽象層（AbstractLogger）簡化測試，因為 ILogger 擴充方法無法直接 Mock
- 驗證記錄層級而非完整訊息，避免測試因訊息文字微調而失敗
- 使用 CompositeLogger 結合 Mock 與實際輸出，同時達成驗證與診斷
常見誤區
過度使用輸出 — 大量輸出會拖慢測試執行速度，且雜訊會淹沒有用資訊。只在複雜或易失敗的測試中加入輸出即可。記錄敏感資訊（密碼、金鑰）也是常見的安全風險。
硬編碼記錄驗證 — 驗證完整的記錄訊息字串容易因訊息微調而失敗，驗證呼叫次數則過度指定了內部實作。改為驗證記錄層級和關鍵字即可。
忽略生命週期 — ITestOutputHelper 的實例與測試方法綁定，在靜態方法或跨測試方法中使用會拋出例外。非同步測試中遺漏 await 也可能導致輸出遺失。
範例參考
參考 templates/ 目錄下的完整範例：
itestoutputhelper-example.cs- ITestOutputHelper 使用範例ilogger-testing-example.cs- ILogger 測試策略範例diagnostic-tools.cs- XUnitLogger 與 CompositeLogger 實作
輸出格式
- 產生含 ITestOutputHelper 注入的測試類別
- 提供 AbstractLogger/XUnitLogger/CompositeLogger 實作程式碼
- 包含結構化輸出的 helper 方法
- ILogger 驗證使用底層 Log 方法而非擴充方法
參考資源
原始文章
本技能內容提煉自「老派軟體工程師的測試修練 - 30 天挑戰」系列文章：
- Day 08 - 測試輸出與記錄：xUnit ITestOutputHelper 與 ILogger
官方文件
相關技能
unit-test-fundamentals- 單元測試基礎xunit-project-setup- xUnit 專案設定nsubstitute-mocking- 測試替身與模擬
範例檔案
- templates/itestoutputhelper-example.cs - ITestOutputHelper 使用範例
- templates/ilogger-testing-example.cs - ILogger 測試範例
- templates/diagnostic-tools.cs - 診斷工具實作
測試清單
在實作測試輸出與記錄時，確認以下檢查項目：
- ITestOutputHelper 透過建構式正確注入
- 使用結構化的輸出格式（章節、時間戳記）
- Logger 測試使用抽象層或 CompositeLogger
- 驗證記錄層級而非完整訊息
- 效能測試包含時間點記錄
- 沒有在輸出中洩漏敏感資訊
- 非同步測試正確等待記錄完成
- 測試失敗時提供足夠的診斷資訊