Table of Contents

Interface ITestContext

Namespace
Xunit
Assembly
xunit.v3.core.dll

Represents the current state of the test pipeline.

public interface ITestContext
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.

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.

CancellationToken CancellationToken { get; }

Property Value

CancellationToken

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

ITestOutputHelper? TestOutputHelper { get; }

Property Value

ITestOutputHelper

TestState

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

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.

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.

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

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.

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.

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.

void CancelCurrentTest()

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

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.

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.

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.

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.

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.

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.

Edit this page