This skill helps you implement high-quality test output and logging mechanisms in .NET xUnit test projects.
Core Principles
1. ITestOutputHelper Usage Principles
Correct Injection Method
- Inject via constructor
ITestOutputHelper - Each test class instance is bound to a test method
- Must not be shared in static methods or across test methods
public class MyTests
{
private readonly ITestOutputHelper _output;
public MyTests(ITestOutputHelper testOutputHelper)
{
_output = testOutputHelper;
}
}
**常見錯誤**
- 靜態存取：`private static ITestOutputHelper _output`
- 在非同步測試中未等待即使用
- 嘗試在 Dispose 方法中使用
### 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}");
}
Output Timing
- At test start: record test setup and input data
- During execution: record important state changes
- Before assertions: record expected and actual values
- At test end: record execution time and result summary
3. ILogger Testing Strategy
Challenge: Extension methods cannot be mocked directly
ILogger.LogError() is an extension method, and NSubstitute cannot intercept it directly. You need to intercept the underlying Log<TState> method:
// ❌ 錯誤：直接 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>>()
);
Solution: Use an abstraction layer
Create AbstractLogger<T> to simplify testing:
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);
}
Use during testing
var logger = Substitute.For<AbstractLogger<MyService>>();
// 現在可以簡單驗證
logger.Received().Log(LogLevel.Error, Arg.Any<Exception>(), Arg.Is<string>(s => s.Contains("錯誤訊息")));
4. Diagnostic Tool Integration
XUnitLogger: Direct logging to test output
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: Supports both verification and output
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...
}
Usage
// 同時進行行為驗證與測試輸出
var mockLogger = Substitute.For<AbstractLogger<MyService>>();
var xunitLogger = new XUnitLogger<MyService>(_output);
var compositeLogger = new CompositeLogger<MyService>(mockLogger, xunitLogger);
var service = new MyService(compositeLogger);
Implementation Guide
Timing Point Logging in Performance Tests
[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");
}
}
Diagnostic Test Base Class
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}");
}
}
Best Practices
-
Use ITestOutputHelper appropriately
- Log important steps in complex tests to help trace failure causes
- Adopt a consistent structured output format (section headings, timestamps) to make output easy to read
- Log timing points in performance tests to provide quantitative data
-
Logger Testing Strategy
- Use an abstraction layer (AbstractLogger) to simplify testing, because ILogger extension methods cannot be mocked directly
- Verify log levels rather than full messages to avoid test failures caused by minor message text changes
- Use CompositeLogger to combine mocking and actual output, achieving both verification and diagnostics
Common Pitfalls
-
Overuse of output — Large amounts of output slow down test execution, and noise drowns out useful information. Only add output to complex or failure-prone tests. Logging sensitive information (passwords, keys) is also a common security risk.
-
Hard-coded logging verification — Verifying complete log message strings is prone to failure due to minor message changes, and verifying call counts over-specifies the internal implementation. Instead, verify log levels and keywords.
-
Ignoring lifecycle — ITestOutputHelper instances are bound to test methods; using them in static methods or across test methods will throw an exception. Missing await in asynchronous tests may also cause output loss.
Example Reference
Refer to templates/ for complete examples in the directory:
itestoutputhelper-example.cs- ITestOutputHelper usage examplesilogger-testing-example.cs- ILogger testing strategy examplesdiagnostic-tools.cs- XUnitLogger and CompositeLogger implementations
Output Format
- Generate a test class with ITestOutputHelper injection
- Provide AbstractLogger/XUnitLogger/CompositeLogger implementation code
- Include helper methods for structured output
- ILogger verification uses the underlying Log method rather than extension methods
Reference Resources
Original Article
The content of this skill is distilled from the "Old-School Software Engineer's Testing Practice - 30-Day Challenge" series of articles:
- Day 08 - Test Output and Logging: xUnit ITestOutputHelper and ILogger
- Ironman Series Article:https://ithelp.ithome.com.tw/articles/10374711
- Sample Code:https://github.com/kevintsengtw/30Days_in_Testing_Samples/tree/main/day08
Official Documentation
Related Skills
unit-test-fundamentals- Unit Testing Fundamentalsxunit-project-setup- xUnit Project Setupnsubstitute-mocking- Test Doubles and Mocking
Sample Files
- templates/itestoutputhelper-example.cs - ITestOutputHelper Usage Example
- templates/ilogger-testing-example.cs - ILogger Test Example
- templates/diagnostic-tools.cs - Diagnostic Tool Implementation
Test Checklist
When implementing test output and logging, confirm the following checklist items:
- ITestOutputHelper is correctly injected via the constructor
- Use a structured output format (sections, timestamps)
- Logger tests use an abstraction layer or CompositeLogger
- Verify log levels rather than complete messages
- Performance tests include timestamp logging
- No sensitive information is leaked in the output
- Asynchronous tests correctly wait for logging to complete
- Provide sufficient diagnostic information when tests fail