dotnet-testing-test-output-logging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

測試輸出與記錄專家指南

测试输出与记录专家指南

本技能協助您在 .NET xUnit 測試專案中實作高品質的測試輸出與記錄機制。

本技能将协助您在.NET xUnit测试项目中实现高质量的测试输出与记录机制。

適用情境

适用情境

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

在 xUnit 測試中使用 ITestOutputHelper 輸出診斷資訊
實作 ILogger 的測試替代品（XUnitLogger）
建立 AbstractLogger 或 CompositeLogger 模式
設計結構化測試輸出進行除錯
實作效能測試診斷工具

当需要执行以下任务时，请使用此技能：

在xUnit测试中使用ITestOutputHelper输出诊断信息
实现ILogger的测试替代方案（XUnitLogger）
建立AbstractLogger或CompositeLogger模式
设计结构化测试输出用于调试
实现性能测试诊断工具

核心原則

核心原则

1. ITestOutputHelper 使用原則

1. ITestOutputHelper使用原则

正確的注入方式

透過建構式注入
```
ITestOutputHelper
```
每個測試類別的實例與測試方法綁定
不可在靜態方法或跨測試方法間共用

csharp

public class MyTests
{
    private readonly ITestOutputHelper _output;
    
    public MyTests(ITestOutputHelper testOutputHelper)
    {
        _output = testOutputHelper;
    }
}

常見錯誤

❌ 靜態存取：

private static ITestOutputHelper _output

❌ 在非同步測試中未等待即使用
❌ 嘗試在 Dispose 方法中使用

正确的注入方式

通过构造函数注入
```
ITestOutputHelper
```
每个测试类的实例与测试方法绑定
不可在静态方法或跨测试方法间共用

csharp

public class MyTests
{
    private readonly ITestOutputHelper _output;
    
    public MyTests(ITestOutputHelper testOutputHelper)
    {
        _output = testOutputHelper;
    }
}

常见错误

❌ 静态存取：

private static ITestOutputHelper _output

❌ 在异步测试中未等待即使用
❌ 尝试在Dispose方法中使用

2. 結構化輸出格式設計

2. 结构化输出格式设计

建議的輸出結構

csharp

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}");
}

輸出時機

測試開始時：記錄測試設置與輸入資料
執行過程中：記錄重要的狀態變化
斷言前：記錄預期值與實際值
測試結束時：記錄執行時間與結果摘要

建议的输出结构

csharp

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 測試策略

3. ILogger测试策略

挑戰：擴充方法無法直接 Mock

ILogger.LogError()

是擴充方法，NSubstitute 無法直接攔截。需要攔截底層的

Log<TState>

方法：

csharp

// ❌ 錯誤：直接 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>

來簡化測試：

csharp

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);
}

測試時使用

csharp

var logger = Substitute.For<AbstractLogger<MyService>>();
// 現在可以簡單驗證
logger.Received().Log(LogLevel.Error, Arg.Any<Exception>(), Arg.Is<string>(s => s.Contains("錯誤訊息")));

挑战：扩展方法无法直接Mock

ILogger.LogError()

是扩展方法，NSubstitute无法直接拦截。需要拦截底层的

Log<TState>

方法：

csharp

// ❌ 错误：直接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>

来简化测试：

csharp

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);
}

测试时使用

csharp

var logger = Substitute.For<AbstractLogger<MyService>>();
// 现在可以简单验证
logger.Received().Log(LogLevel.Error, Arg.Any<Exception>(), Arg.Is<string>(s => s.Contains("错误消息")));

4. 診斷工具整合

4. 诊断工具整合

XUnitLogger：將記錄導向測試輸出

csharp

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：同時支援驗證與輸出

csharp

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...
}

使用方式

csharp

// 同時進行行為驗證與測試輸出
var mockLogger = Substitute.For<AbstractLogger<MyService>>();
var xunitLogger = new XUnitLogger<MyService>(_output);
var compositeLogger = new CompositeLogger<MyService>(mockLogger, xunitLogger);

var service = new MyService(compositeLogger);

XUnitLogger：将记录导向测试输出

csharp

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：同时支持验证与输出

csharp

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...
}

使用方式

csharp

// 同时进行行为验证与测试输出
var mockLogger = Substitute.For<AbstractLogger<MyService>>();
var xunitLogger = new XUnitLogger<MyService>(_output);
var compositeLogger = new CompositeLogger<MyService>(mockLogger, xunitLogger);

var service = new MyService(compositeLogger);

實作指南

实现指南

效能測試中的時間點記錄

性能测试中的时间点记录

csharp

[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");
    }
}

csharp

[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");
    }
}

診斷測試基底類別

诊断测试基类

csharp

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}");
    }
}

csharp

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}");
    }
}

DO - 建議做法

DO - 建议做法

適當使用 ITestOutputHelper
- ✅ 在複雜測試中記錄重要步驟
- ✅ 採用一致的結構化輸出格式
- ✅ 測試失敗時提供診斷資訊
- ✅ 在效能測試中記錄時間點
Logger 測試策略
- ✅ 使用抽象層（AbstractLogger）簡化測試
- ✅ 驗證記錄層級而非完整訊息
- ✅ 使用 CompositeLogger 結合 Mock 與實際輸出
- ✅ 確保敏感資料不被記錄
結構化輸出
- ✅ 使用章節標題分隔不同階段
- ✅ 包含時間戳記便於追蹤
- ✅ 提供足夠的上下文資訊

适当使用ITestOutputHelper
- ✅ 在复杂测试中记录重要步骤
- ✅ 采用一致的结构化输出格式
- ✅ 测试失败时提供诊断信息
- ✅ 在性能测试中记录时间点
Logger测试策略
- ✅ 使用抽象层（AbstractLogger）简化测试
- ✅ 验证记录层级而非完整消息
- ✅ 使用CompositeLogger结合Mock与实际输出
- ✅ 确保敏感数据不被记录
结构化输出
- ✅ 使用章节标题分隔不同阶段
- ✅ 包含时间戳便于追踪
- ✅ 提供足够的上下文信息

DON'T - 避免做法

不要過度使用輸出
- ❌ 避免在每個測試中都大量輸出
- ❌ 不要記錄敏感資訊（密碼、金鑰）
- ❌ 避免影響測試執行效能
不要硬編碼記錄驗證
- ❌ 避免驗證完整的記錄訊息（易碎）
- ❌ 不要驗證記錄呼叫的確切次數（過度指定）
- ❌ 避免測試內部實作細節
不要忽略生命週期
- ❌ 不要在靜態方法中使用 ITestOutputHelper
- ❌ 不要嘗試跨測試方法共用實例
- ❌ 避免在非同步測試中遺漏等待

不要过度使用输出
- ❌ 避免在每个测试中都大量输出
- ❌ 不要记录敏感信息（密码、密钥）
- ❌ 避免影响测试执行性能
不要硬编码记录验证
- ❌ 避免验证完整的记录消息（易碎）
- ❌ 不要验证记录调用的确切次数（过度指定）
- ❌ 避免测试内部实现细节
不要忽略生命周期
- ❌ 不要在静态方法中使用ITestOutputHelper
- ❌ 不要尝试跨测试方法共用实例
- ❌ 避免在异步测试中遗漏等待

範例參考

范例参考

參考

templates/

目錄下的完整範例：

```
itestoutputhelper-example.cs
```
- ITestOutputHelper 使用範例
```
ilogger-testing-example.cs
```
- ILogger 測試策略範例
```
diagnostic-tools.cs
```
- XUnitLogger 與 CompositeLogger 實作

参考

templates/

目录下的完整范例：

```
itestoutputhelper-example.cs
```
- ITestOutputHelper使用范例
```
ilogger-testing-example.cs
```
- ILogger测试策略范例
```
diagnostic-tools.cs
```
- XUnitLogger与CompositeLogger实现

參考資源

参考资源

原始文章

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

Day 08 - 測試輸出與記錄：xUnit ITestOutputHelper 與 ILogger
- 鐵人賽文章：https://ithelp.ithome.com.tw/articles/10374711
- 範例程式碼：https://github.com/kevintsengtw/30Days_in_Testing_Samples/tree/main/day08

本技能内容提炼自「老派软件工程师的测试修炼 - 30天挑战」系列文章：

Day 08 - 测试输出与记录：xUnit ITestOutputHelper与ILogger
- 铁人赛文章：https://ithelp.ithome.com.tw/articles/10374711
- 范例代码：https://github.com/kevintsengtw/30Days_in_Testing_Samples/tree/main/day08

官方文件

官方文档

xUnit Capturing Output

xUnit Capturing Output

測試清單

测试清单

參考資源

参考资源

請參考同目錄下的範例檔案：

templates/itestoutputhelper-example.cs - ITestOutputHelper 使用範例
templates/ilogger-testing-example.cs - ILogger 測試範例
templates/diagnostic-tools.cs - 診斷工具實作

请参考同目录下的范例文件：

templates/itestoutputhelper-example.cs - ITestOutputHelper使用范例
templates/ilogger-testing-example.cs - ILogger测试范例
templates/diagnostic-tools.cs - 诊断工具实现

dotnet-testing-test-output-logging

Original

Translation

測試輸出與記錄專家指南

测试输出与记录专家指南

適用情境

适用情境

核心原則

核心原则

1. ITestOutputHelper 使用原則

1. ITestOutputHelper使用原则

2. 結構化輸出格式設計

2. 结构化输出格式设计

3. ILogger 測試策略

3. ILogger测试策略

4. 診斷工具整合

4. 诊断工具整合

實作指南

实现指南

效能測試中的時間點記錄

性能测试中的时间点记录

診斷測試基底類別

诊断测试基类

DO - 建議做法

DO - 建议做法

DON'T - 避免做法

DON'T - 避免做法

範例參考

范例参考

參考資源

参考资源

原始文章

原始文章

官方文件

官方文档

相關技能

相关技能

測試清單

测试清单

參考資源

参考资源