Release Notes for v3 3.0.0-pre.15 [2025 June 7]

Today, we’re shipping two new prereleases:

• xUnit.net Core Framework v3 3.0.0-pre.15
• xUnit.net Analyzers 1.23.0-pre.3 (release notes)

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

Release Notes

These release notes are a list of changes from 2.0.3 to 3.0.0-pre.15.

This release contains breaking changes as indicated by the major version bump. Binary compatibility with 2.x.y packages is not guaranteed, and extensibility projects should verify whether these breaking changes affect them as they may be required to issue new versions.

Core Framework

• We have added a new property Label to the theory data row classes and theory data attributes. Developers can set the Label property to influence the parameter display for test cases with theory data:

  • Unset (or set to null) will use the existing behavior: TestMethod(...parameters...)
  • Set to an empty string will remove the parameter list: TestMethod
  • Set to a non-empty string will add the label to the display name: TestMethod [LabelValue]

  This will be most commonly used when combined to either label tests with complex parameters with a simpler label, or remove the parameters when combined with custom display names that already include all the necessary information for differentiating theory data rows from one another. Note that if you set this value on both the data attribute and the data row, the value from the data row will take precedence. xunit/xunit#3300

• We have added new properties (SkipType, SkipUnless, and SkipWhen) to the theory data row classes and theory data attributes. These mirror the properties that were already available on FactAttribute, and allow data rows to be conditionally skipped. Note that if you set these values on both the data attribute and the data row, the value from the data row will take precedence. xunit/xunit#3314

• Breaking change: The type of TestContext.Current.KeyValueStorage has changed:

  • 2.0.3: Dictionary<string, object?>
  • 3.0.0: ConcurrentDictionary<string, object?>

  This change was made to accommodate race conditions that could exist when reading or writing shared values from multiple tests and/or multiple extensibility points. xunit/xunit#3306

• Breaking change: For v3 test projects, we have opted to use [CallerFilePath] and [CallerLineNumber] decorated onto FactAttribute and TheoryAttribute rather than CecilSourceInformationProvider. This should improve both performance and reliability for retrieving source location information. This is a binary breaking change only; there should be no compilation issues caused by these changes, as the new parameters are (by design) decorated with default values.

  Tests should not try to set these values manually as they will be provided automatically by the compiler. xunit/xunit#3304

Assertion Library

• Breaking change: We have removed an obsolete overload of CollectionTracker.AreCollectionsEqual. This was marked obsolete in 2.0.0 with a warning about being removed in the next major version.

Extensibility

• Breaking change: We have added a new property (Label) to ITheoryDataRow and IDataAttribute.

• Breaking change: We have added three new properties (SkipType, SkipUnless, and SkipWhen) to IDataAttribute, ITheoryDataRow, and IXunitTest. The constructor for XunitTest was updated to accommodate these new values.

• Breaking change: We have added two new properties (SourceFilePath and SourceLineNumber) to IFactAttribute. The new FactAttribute constructor (mentioned above) sets these values.

  Any extensibility point which creates its own attributes derived (directly or indirectly) from FactAttribute will want to provide these same constructor arguments, or else source location information will be unavailable for tests decorated with such attributes. We have added an analyzer rule to detect this situation, since the compiler will not be helpful to discover the change.

• Breaking change: The existing ExecutionErrorTestCase constructor has been marked as obsolete, replaced by a new constructor that includes two new parameters (sourceFilePath and sourceLineNumber). The old constructor will be removed in the next major release.

• Breaking change: The existing TestIntrospectionHelper.GetTestCaseDetails has been marked as obsolete, replaced by a new overload that includes a new label parameter. The old overload will be removed in the next major version.

• Breaking change: The return type from TestIntrospectionHelper methods GetTestCaseDetails and GetTestCaseDetailsForTheoryDataRow now include two new values in the unnamed tuple return value: SourceFilePath and SourceLineNumber.

• Breaking change: We have added a new property (TestMethodArity) to ITestCaseMetadata and ITestMethodMetadata to support a new requirement from Microsoft Testing Platform 1.7 that requires method arity for test case metadata. This has a downstream impact on ITestCaseDiscovered, ITestCaseStarting, and ITestMethodStarting, as well as the classes which implement all of these interfaces.

  Note that arity will only be available for messages from v3 test projects; this information is not back-ported for v1 or v2, and will return as null. microsoft/testfx#5516

Microsoft Testing Platform

• Microsoft.Testing.Platform dependencies have been updated to 1.7.1.

• Test attachments are now supported by Test Explorer, in addition to dotnet test. xunit/xunit#3227

• We have added support for testconfig.json when running in Microsoft Testing Platform mode. For more information, see our testconfig.json documentation. xunit/xunit#3247

Copyright © .NET Foundation. Contributions welcomed at https://github.com/xunit/xunit/tree/gh-pages.