Table of Contents

Class TestContext

Namespace
Xunit
Assembly
xunit.v3.core.dll

Represents information about the current state of the test engine. It may be available at various points during the execution pipeline, so consumers must always take care to ensure that they check for null values from the various properties.

public sealed class TestContext : ITestContext, IDisposable
Inheritance
TestContext
Implements
Inherited Members
Extension Methods

Properties

Attachments

Gets the attachments for the current test, if the engine is currently in the process of running a test; will return null outside of the context of a test.

public IReadOnlyDictionary<string, TestAttachment>? Attachments { get; }

Property Value

IReadOnlyDictionary<string, TestAttachment>

CancellationToken

Gets the cancellation token that is used to indicate that the test run should be aborted. Async tests should pass this along to any async functions that support cancellation tokens, to help speed up the cancellation process.

public CancellationToken CancellationToken { get; }

Property Value

CancellationToken

Current

Gets the current test context. If called outside of the text discovery or execution path, will return a test context that is in the Unknown stage. The current test context is a "snapshot in time" for when this/ property is called, so do not cache the instance across a single method boundary (or else/ you run the risk of having an out-of-date context).

public static ITestContext Current { get; }

Property Value

ITestContext

KeyValueStorage

Stores key/value pairs that are available across all stages of the pipeline. Can be used to communicate between extensions at different execution stages, in both directions, as a single storage container is used for the entire pipeline.

public Dictionary<string, object?> KeyValueStorage { get; }

Property Value

Dictionary<string, object>

Remarks

This storage system is purely for communication between extension points. The values in here are thrown away after the pipeline execution is complete. It is strongly recommend that extensions either prefix their key names or use guaranteed unique IDs like GUIDs, to prevent collisions with other extension authors.

PipelineStage

Gets the current test pipeline stage.

public TestPipelineStage PipelineStage { get; }

Property Value

TestPipelineStage

Test

Gets the current test, if the engine is currently in the process of running a test; will return null outside of the context of a test.

public ITest? Test { get; }

Property Value

ITest

Remarks

When running with the default test framework implementation, the value here is likely to implement IXunitTest.

TestAssembly

Gets the current test assembly, if the engine is currently in the process of running or discovering tests in assembly; will return null out of this context (this typically means the test framework itself is being created and initialized).

public ITestAssembly? TestAssembly { get; }

Property Value

ITestAssembly

Remarks

When running with the default test framework implementation, the value here is likely to implement IXunitTestAssembly.

TestAssemblyStatus

Gets the current test engine status for the test assembly.

public TestEngineStatus? TestAssemblyStatus { get; }

Property Value

TestEngineStatus?

TestCase

Gets the current test case, if the engine is currently in the process of running a test case; will return null outside of the context of a test case.

public ITestCase? TestCase { get; }

Property Value

ITestCase

Remarks

When running with the default test framework implementation, the value here is likely to implement IXunitTestCase.

TestCaseStatus

Gets the current test engine status for the test case. Will only be available when TestCase is not null.

public TestEngineStatus? TestCaseStatus { get; }

Property Value

TestEngineStatus?

TestClass

Gets the current test method, if the engine is currently in the process of running a test class; will return null outside of the context of a test class. Note that not all test framework implementations require that tests be based on classes, so this value may be null even if TestCase is not null.

public ITestClass? TestClass { get; }

Property Value

ITestClass

Remarks

When running with the default test framework implementation, the value here is likely to implement IXunitTestClass.

TestClassInstance

Gets the instance of the test class; will return null outside of the context of a test. Static test methods do not create test class instances, so this will always be null for static test methods.

public object? TestClassInstance { get; }

Property Value

object

Remarks

This value will only be available when PipelineStage is TestExecution and TestStatus is Running, and only after the test class has been created. It will become null again immediately after the test class has been disposed.

TestClassStatus

Gets the current test engine status for the test class. Will only be available when TestClass is not null.

public TestEngineStatus? TestClassStatus { get; }

Property Value

TestEngineStatus?

TestCollection

Gets the current test collection, if the engine is currently in the process of running a test collection; will return null outside of the context of a test collection.

public ITestCollection? TestCollection { get; }

Property Value

ITestCollection

Remarks

When running with the default test framework implementation, the value here is likely to implement IXunitTestCollection.

TestCollectionStatus

Gets the current test engine status for the test collection. Will only be available when TestCollection is not null.

public TestEngineStatus? TestCollectionStatus { get; }

Property Value

TestEngineStatus?

TestMethod

Gets the current test method, if the engine is currently in the process of running a test method; will return null outside of the context of a test method. Note that not all test framework implementations require that tests be based on methods, so this value may be null even if TestCase is not null.

public ITestMethod? TestMethod { get; }

Property Value

ITestMethod

Remarks

When running with the default test framework implementation, the value here is likely to implement IXunitTestMethod.

TestMethodStatus

Gets the current test engine status for the test method. Will only be available when TestMethod is not null.

public TestEngineStatus? TestMethodStatus { get; }

Property Value

TestEngineStatus?

TestOutputHelper

Gets the output helper, which can be used to add output to the test. Will only be available when Test is not null. Note that the value may still be null when Test is not null, if the test framework implementation does not provide output helper support.

public ITestOutputHelper? TestOutputHelper { get; }

Property Value

ITestOutputHelper

TestState

Gets the current state of the test. Will only be available after the test has finished running.

public TestResultState? TestState { get; }

Property Value

TestResultState

TestStatus

Gets the current test engine status for the test. Will only be available when Test is not null.

public TestEngineStatus? TestStatus { get; }

Property Value

TestEngineStatus?

Warnings

Gets the set of warnings associated with the current test. Will only be available when Test is not null; will also return null if there have been no warnings issued.

public IReadOnlyList<string>? Warnings { get; }

Property Value

IReadOnlyList<string>

Methods

AddAttachment(string, byte[], string)

Adds an attachment that is a binary value (represented by a byte array and media type).

public void AddAttachment(string name, byte[] value, string mediaType = "application/octet-stream")

Parameters

name string

The name of the attachment

value byte[]

The value of the attachment

mediaType string

The media type of the attachment; defaults to "application/octet-stream"

Remarks

The mediaType value must be in the MIME "type/subtype" form, and does not support parameter values. The subtype is allowed to have a single "+" to denote specialization of the subtype (i.e., "application/xhtml+xml"). For more information on media types, see https://datatracker.ietf.org/doc/html/rfc2045#section-5.1.

AddAttachment(string, string)

Adds an attachment that is a string value.

public void AddAttachment(string name, string value)

Parameters

name string

The name of the attachment

value string

The value of the attachment

AddWarning(string)

Adds a warning to the test result.

public void AddWarning(string message)

Parameters

message string

The warning message to be reported

CancelCurrentTest()

Attempt to cancel the currently executing test, if one is executing. This will signal the CancellationToken for cancellation.

public void CancelCurrentTest()

Dispose() 

public void Dispose()

GetFixture(Type)

Gets a fixture that was attached to the test class. Will return null if there is no exact match for the requested fixture type, or if there is no test class (that is, if TestClass returns null).

public ValueTask<object?> GetFixture(Type fixtureType)

Parameters

fixtureType Type

The exact type of the fixture

Returns

ValueTask<object>

The fixture, if available; null, otherwise

Remarks

This may be a fixture attached via IClassFixture<TFixture>, ICollectionFixture<TFixture>, or AssemblyFixtureAttribute.

SendDiagnosticMessage(string)

Sends a diagnostic message. Will only be visible if the end user has enabled diagnostic messages. See https://xunit.net/docs/configuration-files for configuration information.

public void SendDiagnosticMessage(string message)

Parameters

message string

The message to send

SendDiagnosticMessage(string, object?)

Sends a formatted diagnostic message. Will only be visible if the end user has enabled diagnostic messages. See https://xunit.net/docs/configuration-files for configuration information.

public void SendDiagnosticMessage(string format, object? arg0)

Parameters

format string

A composite format string.

arg0 object

The value to replace {0} in the format string.

SendDiagnosticMessage(string, object?, object?)

Sends a formatted diagnostic message. Will only be visible if the end user has enabled diagnostic messages. See https://xunit.net/docs/configuration-files for configuration information.

public void SendDiagnosticMessage(string format, object? arg0, object? arg1)

Parameters

format string

A composite format string.

arg0 object

The value to replace {0} in the format string.

arg1 object

The value to replace {1} in the format string.

SendDiagnosticMessage(string, object?, object?, object?)

Sends a formatted diagnostic message. Will only be visible if the end user has enabled diagnostic messages. See https://xunit.net/docs/configuration-files for configuration information.

public void SendDiagnosticMessage(string format, object? arg0, object? arg1, object? arg2)

Parameters

format string

A composite format string.

arg0 object

The value to replace {0} in the format string.

arg1 object

The value to replace {1} in the format string.

arg2 object

The value to replace {2} in the format string.

SendDiagnosticMessage(string, params object?[])

Sends a formatted diagnostic message. Will only be visible if the end user has enabled diagnostic messages. See https://xunit.net/docs/configuration-files for configuration information.

public void SendDiagnosticMessage(string format, params object?[] args)

Parameters

format string

A composite format string.

args object[]

An object array that contains zero or more objects to format.

SetForInitialization(IMessageSink?, bool, bool)

Sets the test context for test framework initialization. This is the moment before any specific assembly is being discovered or run. This is typically used by custom runners just before they create the test framework via a call to GetTestFramework(Assembly).

public static void SetForInitialization(IMessageSink? diagnosticMessageSink, bool diagnosticMessages, bool internalDiagnosticMessages)

Parameters

diagnosticMessageSink IMessageSink

The optional message sink used to receive IDiagnosticMessage and IInternalDiagnosticMessage instances.

diagnosticMessages bool

A flag to indicate whether the user wants to receive diagnostic messages

internalDiagnosticMessages bool

A flag to indicate whether the user wants to receive internal diagnostic messages

SetForTest(ITest, TestEngineStatus, CancellationToken, TestResultState?, ITestOutputHelper?, object?)

Sets the test context for execution of a test. This assumes an existing test context already exists from which it can pull the diagnostic and internal diagnostic message sinks.

public static void SetForTest(ITest test, TestEngineStatus testStatus, CancellationToken cancellationToken, TestResultState? testState = null, ITestOutputHelper? testOutputHelper = null, object? testClassInstance = null)

Parameters

test ITest

The test that is being executed

testStatus TestEngineStatus

The test status (valid values: Initializing, Running, and CleaningUp)

cancellationToken CancellationToken

The cancellation token used to cancel execution

testState TestResultState

The state of the test (only required when testStatus is CleaningUp).

testOutputHelper ITestOutputHelper

The test output helper that the test can use to write output. Must be passed when testStatus is Initializing; can be null for other statuses (as it will be pulled from the existing test context).

testClassInstance object

The instance of the test class (may be null for static class and before the test class has been created)

SetForTestAssembly(ITestAssembly, TestEngineStatus, CancellationToken)

Sets the test context for discovery or execution of a test assembly. This assumes an existing test context already exists from which it can pull the diagnostic and internal diagnostic message sinks.

public static void SetForTestAssembly(ITestAssembly testAssembly, TestEngineStatus testAssemblyStatus, CancellationToken cancellationToken)

Parameters

testAssembly ITestAssembly

The test assembly that is being executed

testAssemblyStatus TestEngineStatus

The test assembly status

cancellationToken CancellationToken

The cancellation token used to cancel execution

SetForTestCase(ITestCase, TestEngineStatus, CancellationToken)

Sets the test context for execution of a test case. This assumes an existing test context already exists from which it can pull the diagnostic and internal diagnostic message sinks.

public static void SetForTestCase(ITestCase testCase, TestEngineStatus testCaseStatus, CancellationToken cancellationToken)

Parameters

testCase ITestCase

The test case that is being executed

testCaseStatus TestEngineStatus

The test case status (valid values: Initializing, Running, and CleaningUp)

cancellationToken CancellationToken

The cancellation token used to cancel execution

SetForTestClass(ITestClass, TestEngineStatus, CancellationToken, FixtureMappingManager?)

Sets the test context for execution of a test class. This assumes an existing test context already exists from which it can pull the diagnostic and internal diagnostic message sinks.

public static void SetForTestClass(ITestClass testClass, TestEngineStatus testClassStatus, CancellationToken cancellationToken, FixtureMappingManager? fixtures = null)

Parameters

testClass ITestClass

The test class that is being executed

testClassStatus TestEngineStatus

The test class status (valid values: Initializing, Running, and CleaningUp)

cancellationToken CancellationToken

The cancellation token used to cancel execution

fixtures FixtureMappingManager

The fixtures that are available to the test class

SetForTestCollection(ITestCollection, TestEngineStatus, CancellationToken)

Sets the test context for execution of a test collection. This assumes an existing test context already exists from which it can pull the diagnostic and internal diagnostic message sinks.

public static void SetForTestCollection(ITestCollection testCollection, TestEngineStatus testCollectionStatus, CancellationToken cancellationToken)

Parameters

testCollection ITestCollection

The test collection that is being executed

testCollectionStatus TestEngineStatus

The test collection status (valid values: Initializing, Running, and CleaningUp)

cancellationToken CancellationToken

The cancellation token used to cancel execution

SetForTestMethod(ITestMethod, TestEngineStatus, CancellationToken)

Sets the test context for execution of a test method. This assumes an existing test context already exists from which it can pull the diagnostic and internal diagnostic message sinks.

public static void SetForTestMethod(ITestMethod testMethod, TestEngineStatus testMethodStatus, CancellationToken cancellationToken)

Parameters

testMethod ITestMethod

The test method that is being executed

testMethodStatus TestEngineStatus

The test method status (valid values: Initializing, Running, and CleaningUp)

cancellationToken CancellationToken

The cancellation token used to cancel execution

Edit this page