» Release Notes
» Release Notes
Today, we’re shipping one new prerelease:
3.0.0-pre.25As always, we’d like to thank all the users who contributed to the success of xUnit.net through usage, feedback, and code contributions. 🎉
These release notes are a list of changes from 3.0.0-pre.15 to 3.0.0-pre.25.
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. You should review all prerelease notes for all breaking changes since 2.x.y as this list only contains deltas from the previous prerelease build.
Breaking change: We have decided to deprecate CecilSourceInformationProvider based on performance and compatibility issues.
v3 projects will utilize the compile-time source information available via [FactAttribute], introduced in 3.0.0-pre.15. This is used for all execution paths: xUnit.net native runners, Microsoft Testing Platform, and VSTest (aka xunit.runner.visualstudio).
v1/v2 projects will utilize DiaSession from VSTest. Source information will only be available for these projects when running in the context of VSTest. v1/v2 projects running in xUnit.net native runners will not include source information, and these projects do not support Microsoft Testing Platform.
Breaking change: To fix a bug with attributes throwing in their constructors, we have changed the way we discover attributes. This “new” behavior is actually a restoration of older behavior from v2, which was required by virtue of the way we opted to allow attributes to be discovered by interface instead of concrete type. While this code is based on well tested code from v2, it’s being put into new use in v3, and there may be edge case issues surrounding attribute discovery owing to this implementation change. Developers relying upon ReflectionExtensions.GetMatchingCustomAttributes should test to ensure that no attribute lookup bugs in their extensions have been caused by this change. xunit/xunit#3319
BUG: We have fixed a memory leak in TestContext due to a CancellationTokenSource object which was being allocated but not disposed. xunit/xunit#3323
Assert.Throws which allow the developer to provide an exception inspector. The inspector lambda accepts the exception (typed as Exception in the non-generic versions, or typed as T in the generic versions), and can return true to accept the exception or false to reject the exception. You may also throw (including using assertions) inside the lambda if you wish. xunit/xunit#2154We have bumped up the “crash detection” idle message timeout from 5 seconds to 60 seconds, to help eliminate potential false positives related to crashing when running tests on slower machines. This value can be changed by runners by setting XunitProject.Configuration.CrashDetectionSinkTimeout. This configuration value is not directly adjustable by end users at this time, and there should be no noticeable change in project execution time for test projects which aren’t crashing.
Breaking change: We have deprecated the AssemblyRunner class (and all associated types) that live in the Xunit.Runners namespace, in favor of a new design that lives in the Xunit.SimpleRunner namespace. The v3 TestRunner Sample has been updated to use the new APIs. xunit/xunit#3265
Notable changes include:
A new AssemblyRunnerOptions class is used to do all configuration of the assembly runner.
This replaces the previous mixture of configuration that was spread out across the factory functions (WithoutAppDomain and WithAppDomain), the AssemblyRunner instance itself (for events), and the AssemblyRunnerStartOptions class (for configuration).
Instead, you create AssemblyRunnerOptions with the path to the test assembly, and then you can configure it and subscribe to the events on it. It becomes a self-contained description of your intended test run. When constructed, the configuration options are pre-populated with values from the test assembly configuration (typically xunit.runner.json).
The AssemblyRunnerOptions includes a few new metadata properties: TargetFrameworkIdentifier (which target framework the test assembly was compiled against), TargetFrameworkVersion (which version of the target framework the test assembly was compiled for), and XunitVersion (which major version of xUnit.net the test assembly targets).
Configuration values in AssemblyRunnerOptions document which major versions of xUnit.net they support, and they will not only validate the values provided but also that setting the values will be meaningful. For example, if you try to set AssertEquivalentMaxDepth and your test assembly isn’t targeting xUnit.net v3, then an exception will be thrown indicating this. Documentation example:
There are three properties on AssemblyRunnerOptions that are only available when your runner is targeting .NET Framework and your test project is targeting .NET Framework using xUnit.net v1 or v2: AppDomain, ShadowCopy, and ShadowCopyFolder. These values replace the configuration available previously via WithAppDomain.
We have dramatically increased the number of available configuration options to be better aligned with all the options now available in v3.
Test filtering is now fully supported. The old lambda-based TestCaseFilter has been replaced by the Filters property on AssemblyRunnerOptions, which allows you to specify any of the typically available filtering options. This includes simple filters (like including/excluding based on class, method, namespace, etc.) as well query filters. Note: You may not mix simple filters with query filters. Use one or the other.
Most of the event information classes have been improved to include more information about the respective events. All the Finished event information includes the information from the related Starting event information so that you no longer need to track that information across the two events.
We have also added two new events: OnDiscoveryStaring and OnExecutionStarting.
We have added support for generating one or more of the built-in reports (XML, HTML, CTRF, etc.) at the end of test execution. You can request reports by calling AddReport on the AssemblyRunnerOptions instance.
The old design offered a Start method which immediately returned, and required the developer to periodically poll the Status property to determine when test execution was complete. The new design replaces this with a Run method which returns Task. Developers should await the Task to determine when the execution is complete. Note: The AssemblyRunner cannot issue multiple simultaneous Run requests, though it can be reused after it’s finished a previous run.