Extends xUnit to expose extra context and simplify logging.
Redirects Trace.Write, Debug.Write, and Console.Write and Console.Error.Write to ITestOutputHelper. Also provides static access to the current ITestOutputHelper for use within testing utility methods.
Uses AsyncLocal to track state.
See Milestones for release notes.
https://nuget.org/packages/XunitContext/
static class ClassBeingTested
{
public static void Method()
{
Trace.WriteLine("From Trace");
Console.WriteLine("From Console");
Debug.WriteLine("From Debug");
Console.Error.WriteLine("From Console Error");
}
}XunitContextBase is an abstract base class for tests. It exposes logging methods for use from unit tests, and handle the flushing of logs in its Dispose method. XunitContextBase is actually a thin wrapper over XunitContext. XunitContexts Write* methods can also be use inside a test inheriting from XunitContextBase.
public class TestBaseSample(ITestOutputHelper output) :
XunitContextBase(output)
{
[Fact]
public void Write_lines()
{
WriteLine("From Test");
ClassBeingTested.Method();
var logs = XunitContext.Logs;
Assert.Contains("From Test", logs);
Assert.Contains("From Trace", logs);
Assert.Contains("From Debug", logs);
Assert.Contains("From Console", logs);
Assert.Contains("From Console Error", logs);
}
}In addition to XunitContextBase class approach, one is also possible to use IContextFixture to gain access to XunitContext :
public class FixtureSample(ITestOutputHelper helper, ContextFixture ctxFixture) :
IContextFixture
{
Context context = ctxFixture.Start(helper);
[Fact]
public void Usage()
{
Console.WriteLine("From Test");
Assert.Contains("From Test", context.LogMessages);
}
}XunitContext provides static access to the logging state for tests. It exposes logging methods for use from unit tests, however registration of ITestOutputHelper and flushing of logs must be handled explicitly.
public class XunitLoggerSample :
IDisposable
{
[Fact]
public void Usage()
{
XunitContext.WriteLine("From Test");
ClassBeingTested.Method();
var logs = XunitContext.Logs;
Assert.Contains("From Test", logs);
Assert.Contains("From Trace", logs);
Assert.Contains("From Debug", logs);
Assert.Contains("From Console", logs);
Assert.Contains("From Console Error", logs);
}
public XunitLoggerSample(ITestOutputHelper testOutput) =>
XunitContext.Register(testOutput);
public void Dispose() =>
XunitContext.Flush();
}XunitContext redirects Trace.Write, Console.Write, and Debug.Write in its static constructor.
Trace.Listeners.Clear();
Trace.Listeners.Add(new TraceListener());
#if (NETFRAMEWORK)
Debug.Listeners.Clear();
Debug.Listeners.Add(new TraceListener());
#else
DebugPoker.Overwrite(
text =>
{
if (string.IsNullOrEmpty(text))
{
return;
}
if (text.EndsWith(Environment.NewLine))
{
WriteLine(text.TrimTrailingNewline());
return;
}
Write(text);
});
#endif
TestWriter writer = new();
Console.SetOut(writer);
Console.SetError(writer);These API calls are then routed to the correct xUnit ITestOutputHelper via a static AsyncLocal.
Approaches to routing common logging libraries to Diagnostics.Trace:
- Serilog use Serilog.Sinks.Trace.
- NLog use a Trace target.
XunitContext.Filters can be used to filter out unwanted lines:
public class FilterSample(ITestOutputHelper output) :
XunitContextBase(output)
{
static FilterSample() =>
Filters.Add(_ => _ != null && !_.Contains("ignored"));
[Fact]
public void Write_lines()
{
WriteLine("first");
WriteLine("with ignored string");
WriteLine("last");
var logs = XunitContext.Logs;
Assert.Contains("first", logs);
Assert.DoesNotContain("with ignored string", logs);
Assert.Contains("last", logs);
}
}Filters are static and shared for all tests.
For every tests there is a contextual API to perform several operations.
Context.TestOutput: Access to ITestOutputHelper.Context.WriteandContext.WriteLine: Write to the current log.Context.LogMessages: Access to all log message for the current test.- Counters: Provide access in predicable and incrementing values for the following types:
Guid,Int,Long,UInt, andULong. Context.Test: Access to the currentITest.Context.SourceFile: Access to the file path for the current test.Context.SourceDirectory: Access to the directory path for the current test.Context.SolutionDirectory: The current solution directory. Obtained by walking up the directory tree fromSourceDirectory.Context.TestException: Access to the exception if the current test has failed. See Test Failure.
// ReSharper disable UnusedVariable
public class ContextSample(ITestOutputHelper output) :
XunitContextBase(output)
{
[Fact]
public void Usage()
{
Context.WriteLine("Some message");
var currentLogMessages = Context.LogMessages;
var testOutputHelper = Context.TestOutput;
var currentTest = Context.Test;
var sourceFile = Context.SourceFile;
var sourceDirectory = Context.SourceDirectory;
var solutionDirectory = Context.SolutionDirectory;
var currentTestException = Context.TestException;
}
}Some members are pushed down to the be accessible directly from XunitContextBase:
// ReSharper disable UnusedVariable
public class ContextPushedDownSample(ITestOutputHelper output) :
XunitContextBase(output)
{
[Fact]
public void Usage()
{
WriteLine("Some message");
var currentLogMessages = Logs;
var testOutputHelper = Output;
var sourceFile = SourceFile;
var sourceDirectory = SourceDirectory;
var solutionDirectory = SolutionDirectory;
var currentTestException = TestException;
}
}Context can accessed via a static API:
// ReSharper disable UnusedVariable
public class ContextStaticSample(ITestOutputHelper output) :
XunitContextBase(output)
{
[Fact]
public void StaticUsage()
{
XunitContext.Context.WriteLine("Some message");
var currentLogMessages = XunitContext.Context.LogMessages;
var testOutputHelper = XunitContext.Context.TestOutput;
var currentTest = XunitContext.Context.Test;
var sourceFile = XunitContext.Context.SourceFile;
var sourceDirectory = XunitContext.Context.SourceDirectory;
var solutionDirectory = XunitContext.Context.SolutionDirectory;
var currentTestException = XunitContext.Context.TestException;
}
}There is currently no API in xUnit to retrieve information on the current test. See issues #1359, #416, and #398.
To work around this, this project exposes the current instance of ITest via reflection.
Usage:
// ReSharper disable UnusedVariable
public class CurrentTestSample(ITestOutputHelper output) :
XunitContextBase(output)
{
[Fact]
public void Usage()
{
var currentTest = Context.Test;
// DisplayName will be 'CurrentTestSample.Usage'
var displayName = currentTest.DisplayName;
}
[Fact]
public void StaticUsage()
{
var currentTest = XunitContext.Context.Test;
// DisplayName will be 'CurrentTestSample.StaticUsage'
var displayName = currentTest.DisplayName;
}
}Implementation:
namespace Xunit;
public partial class Context
{
ITest? test;
public ITest Test
{
get
{
InitTest();
return test!;
}
}
MethodInfo? methodInfo;
public MethodInfo MethodInfo
{
get
{
InitTest();
return methodInfo!;
}
}
Type? testType;
public Type TestType
{
get
{
InitTest();
return testType!;
}
}
void InitTest()
{
if (test != null)
{
return;
}
if (TestOutput == null)
{
throw new(MissingTestOutput);
}
#if NET8_0_OR_GREATER
[UnsafeAccessor(UnsafeAccessorKind.Field, Name = "test")]
static extern ref ITest GetTest(TestOutputHelper? c);
test = GetTest((TestOutputHelper) TestOutput);
#else
test = (ITest) GetTestMethod(TestOutput)
.GetValue(TestOutput)!;
#endif
var method = (ReflectionMethodInfo) test.TestCase.TestMethod.Method;
var type = (ReflectionTypeInfo) test.TestCase.TestMethod.TestClass.Class;
methodInfo = method.MethodInfo;
testType = type.Type;
}
public const string MissingTestOutput = "ITestOutputHelper has not been set. It is possible that the call to `XunitContext.Register()` is missing, or the current test does not inherit from `XunitContextBase`.";
#if !NET8_0_OR_GREATER
static FieldInfo? cachedTestMember;
static FieldInfo GetTestMethod(ITestOutputHelper testOutput)
{
if (cachedTestMember != null)
{
return cachedTestMember;
}
var testOutputType = testOutput.GetType();
cachedTestMember = testOutputType.GetField("test", BindingFlags.Instance | BindingFlags.NonPublic);
if (cachedTestMember == null)
{
throw new($"Unable to find 'test' field on {testOutputType.FullName}");
}
return cachedTestMember;
}
#endif
}When a test fails it is expressed as an exception. The exception can be viewed by enabling exception capture, and then accessing Context.TestException. The TestException will be null if the test has passed.
One common case is to perform some logic, based on the existence of the exception, in the Dispose of a test.
// ReSharper disable UnusedVariable
public static class GlobalSetup
{
[ModuleInitializer]
public static void Setup() =>
XunitContext.EnableExceptionCapture();
}
public class TestExceptionSample(ITestOutputHelper output) :
XunitContextBase(output)
{
[Fact(Skip = "Will fail")]
public void Usage() =>
//This tests will fail
Assert.False(true);
public override void Dispose()
{
var theExceptionThrownByTest = Context.TestException;
var testDisplayName = Context.Test.DisplayName;
var testCase = Context.Test.TestCase;
base.Dispose();
}
}When creating a custom base class for other tests, it is necessary to pass through the source file path to XunitContextBase via the constructor.
public class CustomBase(
ITestOutputHelper testOutput,
[CallerFilePath] string sourceFile = "")
:
XunitContextBase(testOutput, sourceFile);Provided the parameters passed to the current test when using a [Theory].
Use cases:
- To derive the unique test name.
- In extensibility scenarios for example Verify file naming.
Usage:
public class ParametersSample(ITestOutputHelper output) :
XunitContextBase(output)
{
[Theory]
[MemberData(nameof(GetData))]
public void Usage(string arg)
{
var parameter = Context.Parameters.Single();
var parameterInfo = parameter.Info;
Assert.Equal("arg", parameterInfo.Name);
Assert.Equal(arg, parameter.Value);
}
public static IEnumerable<object[]> GetData()
{
yield return ["Value1"];
yield return ["Value2"];
}
}Implementation:
static List<Parameter> GetParameters(ITestCase testCase) =>
GetParameters(testCase, testCase.TestMethodArguments);
static List<Parameter> GetParameters(ITestCase testCase, object[] arguments)
{
var method = testCase.TestMethod;
var infos = method
.Method.GetParameters()
.ToList();
if (arguments == null || arguments.Length == 0)
{
if (infos.Count == 0)
{
return empty;
}
throw NewNoArgumentsDetectedException();
}
List<Parameter> items = [];
for (var index = 0; index < infos.Count; index )
{
items.Add(new(infos[index], arguments[index]));
}
return items;
}Only core types (string, int, DateTime etc) can use the above automated approach. If a complex type is used the following exception will be thrown
No arguments detected for method with parameters. This is most likely caused by using a parameter that Xunit cannot serialize. Instead pass in a simple type as a parameter and construct the complex object inside the test. Alternatively; override the current parameters using
UseParameters()via the current test base class, or viaXunitContext.Current.UseParameters().
To use complex types override the parameter resolution using XunitContextBase.UseParameters:
public class ComplexParameterSample(ITestOutputHelper output) :
XunitContextBase(output)
{
[Theory]
[MemberData(nameof(GetData))]
public void UseComplexMemberData(ComplexClass arg)
{
UseParameters(arg);
var parameter = Context.Parameters.Single();
var parameterInfo = parameter.Info;
Assert.Equal("arg", parameterInfo.Name);
Assert.Equal(arg, parameter.Value);
}
public static IEnumerable<object[]> GetData()
{
yield return [new ComplexClass("Value1")];
yield return [new ComplexClass("Value2")];
}
public class ComplexClass(string value)
{
public string Value { get; } = value;
}
}Provided a string that uniquely identifies a test case.
Usage:
public class UniqueTestNameSample(ITestOutputHelper output) :
XunitContextBase(output)
{
[Fact]
public void Usage()
{
var testName = Context.UniqueTestName;
Context.WriteLine(testName);
}
}Implementation:
string GetUniqueTestName(ITestCase testCase)
{
var method = testCase.TestMethod;
var name = $"{method.TestClass.Class.ClassName()}.{method.Method.Name}";
if (!Parameters.Any())
{
return name;
}
var builder = new StringBuilder($"{name}_");
foreach (var parameter in Parameters)
{
builder.Append($"{parameter.Info.Name}=");
builder.Append(string.Join(",", SplitParams(parameter.Value)));
builder.Append('_');
}
builder.Length -= 1;
return builder.ToString();
}
static IEnumerable<string> SplitParams(object? parameter)
{
if (parameter == null)
{
yield return "null";
yield break;
}
if (parameter is string stringValue)
{
yield return stringValue;
yield break;
}
if (parameter is IEnumerable enumerable)
{
foreach (var item in enumerable)
{
foreach (var sub in SplitParams(item))
{
yield return sub;
}
}
yield break;
}
var toString = parameter.ToString();
if (toString == null)
{
yield return "null";
}
else
{
yield return toString;
}
}Xunit has no way to run code once before any tests executing. So use one of the following:
- C# 9 Module Initializer.
- Fody Module Initializer.
- Having a single base class that all tests inherit from, and place any configuration code in the static constructor of that type.
Wolverine designed by Mike Rowe from The Noun Project.