Release Notes for 0.3.0-pre.18 [2024 August 30]

Today, we’re shipping one new release and two new prereleases:

xUnit.net Core Framework v3 0.3.0-pre.18
xUnit.net Analyzers 1.16.0 (release notes)
xUnit.net Visual Studio adapter 3.0.0-pre.30 (release notes)

It’s been 1 month since the release of 0.2.0-pre.69.

As always, we’d like to thank all the users who contributed to the success of xUnit.net through usage, feedback, and code contributions. 🎉

If you are new to v3

We have created two new pieces of documentation that we will continue to evolve as we create newer prerelease versions of xUnit.net v3:

We recommend you read them in that order. The migration guide will help you understand what changes are necessary to get your v2 test project ready to upgrade to v3, and it includes a fairly comprehensive list of the changes (and hopefully relatively small bumps in the road) that you can expect. This latter part is provided primarily in resource form, so rather than reading the giant boring lists, you can do a search on the page when you encounter issues with specific types. Once you’ve got your project ported over to v3, the what’s new guide will be useful to understand what new features are available to you with v3.

Please note that you will need to use a version 3.x.y release of the Visual Studio adapter to run v3 tests, as the 2.x.y releases are only capable of running v1 and v2 tests. We will eventually stop shipping the 2.x.y builds, as the 3.x.y builds are also capable of running v1 and v2 tests. We’d love if users test the 3.x.y release of the Visual Studio adapter even if they cannot migrate to the v3 Core Framework.

Release Notes

These release notes are a list of changes from 0.2.0-pre.69 to 0.3.0-pre.18.

Core Framework

Added serialization support for both Index and Range types. xunit/xunit#3003
Added TestContext.Current.TestClassInstance which will point to the instance of the current test class. Note that this value is only valid after the test class constructor has run, and becomes null against after the test class has been disposed. In instances where the test class is not created (i.e., static test methods), the value will always be null. xunit/xunit#3005
BUG: Fixtures were not able to get IMessageSink injected into them. Note that v3 fixture authors have the option to use TestContext.Current.SendDiagnosticMessage rather than taking the IMessageSink dependency. xunit/xunit#3001
BUG: Setting a SynchronizationContext in the test class constructor was broken in that the sync context during the test method would not be correct (it would be null in most cases), due to the added ability in v3 to allow asynchronous test class creation. As a result, the return value of TestRunner.CreateTestClassInstance has changed from ValueTask<object?> to ValueTask<(object? Instance, SynchronizationContext? SyncContext)> and implementers are expected to capture and return the overridden synchronization context during the creation process. For an example of this code, see XunitTestRunner.CreateTestClassInstance. xunit/xunit#3014

Assertion Library

Added support for Lazy<T> to Assert.Equivalent. When evaluating a value which is Lazy<T>, it will call .Value and use the the T value for comparison purposes. This applies to both sides of the comparison (expected and actual).

Extensibility

Added three new properties to ITestCaseMetadata:
- Explicit (as bool)
- TestMethodParameterTypes (as string[])
- TestMethodReturnType (as string)
The type values will generally be filled with the fully qualified type names. (Note: if you are using a 0.2.0-pre build of the core framework for your tests and a 0.3.0-pre build of the runner utility library, all three of these new values will appear as null on the runner side since they are not provided by the execution side unless the tests are linked against a 0.3.0-pre build.)
IDataAttribute.GetData added a MethodInfo parameter, to match the v2 signature which provided IMethodInfo. This value was inadvertently removed in the v2 to v3 migration. xunit/xunit#2998
Added ITestProcessLauncher as an optional parameter to XunitFrontController.Create, which is used to control the launching of the test process for v3 projects. This extensibility point is intended to support unusual launch circumstances (like the need for xunit.runner.visualstudio to attach to the debugger, and NCrunch to be able to run v3 test projects in-process). The default implementation lives in LocalOutOfProcessTestProcessLauncher. The boolean forceInProcess parameter to Xunit3.ForDiscoveryAndExecution has been replaced with the ITestProcessLauncher, and the in-process launch functionality has been moved to InProcessTestProcessLauncher (note that this is primarily to support NCrunch, and users who attempt to use this launcher will be responsible for all dependency resolution).

The methods IFrontControllerDiscoverer.Find, IFrontController.FindAndRun, and IFrontController.Run now all return void rather than int?, as the process ID (if there is one) is an implementation detail of the process launcher.
BUG: Fixed an issue where v3 diagnostic and internal diagnostic messages (IDiagnosicMessage and IInternalDiagnosticMessage, respectively) were not being properly routed to the diagnostic message sink in Xunit3.
BUG: Fixed an issue where v3 synchronous message reporting capability was not working properly. To support this, the -automated in-process console runner switch now accepts an optional value of either async or sync to designate whether synchronous messaging is requested. When synchronous messaging is requested, the in-process console runner will call Console.ReadLine() after each message is sent as a form of acknowledgment. Xunit3 (and helper classes) have been updated to perform this synchronous handshake, and Xunit3ArgumentFactory will only send -automated sync (and thus only support synchronous reporting) if it knows the test project is linked against 0.3.0-pre or later.
BUG: The return type of ISourceInformationProvider.GetSourceInformation was changed from a tuple to a struct (named SourceInformation) due to a compatibility issue with Mono. (Note: the fix was shipped as part of xunit.runner.visualstudio version 3.0.0-pre.24.) xunit/visualstudio.xunit#411

Runner support for Core Framework v3

Supported by the xUnit.net team

Functional:

In-box Console and MSBuild runners
Command line (dotnet test and dotnet vstest) [tested with 17.10.4]
Visual Studio 2022 (Test Explorer) [tested with 17.10.4]
Visual Studio Code [tested with 1.91.1]

Support for dotnet test, Visual Studio, and Visual Studio Code comes from the Visual Studio runner (a 3.x.y build of xunit.runner.visualstudio).

Supported by third parties

Functional:

Resharper/Rider [requires 2024.2 or later]

Conditionally functional:

NCrunch [testing has passed initial validation, but a build is not yet publicly available]

Status unknown:

CodeRush