Release Notes for 0.4.0-pre.20 [2024 September 22]

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

xUnit.net Core Framework v2 2.9.1 (release notes)
xUnit.net Core Framework v3 0.4.0-pre.20
xUnit.net Visual Studio adapter 3.0.0-pre.35 (release notes)

It’s been 3 weeks since the release of 0.3.0-pre.18.

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.3.0-pre.18 to 0.4.0-pre.20.

Core Framework

We have added support for Microsoft Testing Platform natively to all v3 test projects. This enables a new dotnet test and Test Explorer experience (both of which are currently experimental), as well as an alternative command line UX (you can toggle between xUnit.net’s native command line vs. Microsoft Testing Platform’s command line at compile time with an MSBuild property). For more information, see Microsoft Testing Platform support in xUnit.net v3.
We have updated ITestOutputHelper to include Write methods, in addition to WriteLine methods. (Note that output will still be buffered per line, so live output will still be reported on a per-line basis, not on a per Write basis. Lines are demarcated by Environment.NewLine, so if writing newlines manually, make sure you use this runtime value and don’t hardcore \r\n or \n, if your tests run on multiple OSes.)
We have added two new assembly-level attributes ([CaptureConsole] and [CaptureTrace]) which will capture Console output and Trace/Debug output, respectively. Output to these sources will show up in the standard output, as though it had been written to ITestOutputHelper. xunit/xunit#1730
We have added support for Timeout on tests which are not async; previously, Timeout only worked for tests that were async test methods. (Note that the effectiveness of using Timeout with parallelization enabled requires that you use the conservative parallelization algorithm). xunit/xunit#2222
The TestContext class now implements ITestContext, and ITestContextAccessor.Current returns ITestContext.
We have added a TestMethodArguments property to IXunitTest. Extensions may retrieve the test method arguments for the currently executing test by inspecting TestContext.Current.Test, and testing to see that it implements IXunitTest (the built-in test framework will always do so). (Note for extensibility authors, this used to be present on XunitTestRunnerContext, and plumbing through these values changed the signatures of several of the base interfaces and context classes; these breaking changes are what necessitated the bump to 0.4.0.) xunit/xunit#3020
We have updated the xUnit.net XML report (and bumped the schema version to 3) to add start-rtf and finish-rtf properties to <test> nodes.
We have updated the TRX report to add startTime and endTime properties nodes to <UnitTestResult> nodes. We have also added several new nodes to the report to track the TRX report that is generated by Microsoft Testing Platform.
BUG: We fixed an issue where sometimes conditionally skipped theories would not be properly skipped (when pre-enumeration was disabled). (Note for extensibility authors, this required a constructor signature change to XunitDelayEnumeratedTheoryTestCase to pass along the conditional skip values from the [Theory] attribute.)
BUG: We fixed an issue with the TRX report that was mistakenly categorizing ‘not run’ tests (usually Explicit = true tests which weren’t run) as notExecuted. They are now correctly categorized as notRunnable.

Assertion Library

We have added support for Guid values to Assert.Equivalent. xunit/xunit#2974
We have added support for Lazy<T> values to Assert.Equivalent. When encountered anywhere in the expected and/or actual side of the comparison, the underlying value will be compared.
We have added support for IEnumerable<IGrouping<TKey, TValue>> to Assert.Equivalent. We have also added support for this to ArgumentFormatter, which should allow properly displaying groupings rather than falling back to the triple-ellipses display. (Note: Using Assert.Equal with groupings will cause false positives due of the fact IGrouping<> implements IEnumerable<TValue>, so the containers only compare values and not keys. Only Assert.Equivalent is supported for comparing two groupings.) xunit/xunit#3028
BUG: We have fixed an issue with compiler ambiguity related to arrays and spans (for .NET 6+ users) by adding an additional overload (Equal<T>(ReadOnlySpan<T>, T[]). xunit/xunit#3021

Runners

We have added the ability to use a query filter language to filter tests.
- For xUnit.net native command lines and xunit.v3.runner.console, specify a query filter using -filter <expression>
- For Microsoft Testing Platform command lines, specify a query filter using --query-filter <expression>
You can use either query filtering or the existing simple filtering, but you cannot mix both together at the same time. Note that query filters specified to xunit.v3.runner.console can also be used for v1 and v2 tests (in addition to v3 tests). xunit/xunit#1833

Extensibility

We have added the TestClassSimpleName property to ITestCaseMetadata and ITestClassMetadata. This will be set to the class name without the namespace, but include the nested class hierarchy (i.e., if TestClassName is Foo.Bar.Baz+Biff and TestClassNamespace is Foo.Bar, then TestClassSimpleName will be Baz+Biff).

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