Today, we're shipping xUnit.net 2.4.2; this includes RTM builds of the core framework and analyzers (now at version 1.0.0! 🎉).
It's been nearly 4 years since the release of 2.4.1 RTM. This release includes a few targeted bug fixes for the core framework, and an updated assertion library with many of the new v3 assertions being back-ported to v2. This new assertion library includes several new assertions and overloads of existing assertions, improvements to output for failing tests, and nullable annotations.
We did not intend to ship any more v2 releases; that said, we also did not intend for the v3 development process to take as long as it has. We felt it was necessary to address a couple specific high-friction issues (including two from the .NET Team at Microsoft); the new assertions are merely an extra reason to encourage the upgrade (and help tide teams over who might be waiting for v3 with some of the new features).
You will notice that we have not changed any of the minimum requirements for this release, despite the fact that .NET 4.5.2 and .NET Core 1.0 are quite old at this point. We did not want to disrupt the workflow of those who may still be stuck on older (even out of support) versions of .NET Framework or .NET Core. You should not consider this an endorsement that you use these older versions of .NET Framework or .NET Core; this was merely about making as few changes as possible to minimize compatibility issues, especially with third party extensibility libraries and test runners. Please upgrade to supported versions as soon as possible, as some of them are not even receiving security patches at this point in time.
This need to stick to the older target frameworks is the reason we are unable
to ship the new assertions based on
ValueTask. If you wish you be able to consume these, they are part
of the source package
xunit.assert.source, which you could use
xunit.assert), and then define the appropriate constants
in the project (using
in your project file) to enable more advanced features. For more information on the
constants and available features, please see the
home page README.
As 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 reflect the entirety of the changes between 2.4.1 and 2.4.2.
Skip on an
[InlineData] attribute was being ignored by Visual Studio Test Explorer.
decimal values weren't
usable in generic theories because the type coercion logic was not accounting for
the possibility of multiple type-compatible
would incorrectly use
object to close all the generic types rather than
continuing to inspect the subsequent non-
null values for their
DisposalTracker which was a race
condition that could cause objects to fail to get disposed and/or cause objects to
get disposed twice.
Assert.Distinct to verify that a collection does not contain any duplicate values.
Assert.Equivalent to check for object equivalence. Object equivalence
is intended to be a looser kind of assertion than
Assert.Equal. This assertion
allows an optional
strict flag to influence its behavior. The rules for equivalence
are as follows:
null values are only ever equivalent to other
null values (regardless
In particular, this means that types must match exactly (for example,
long values are never equivalent, even if they have the same underlying value; or,
in code form:
Assert.Equivalent(12, 12L); will fail).
[1, 2] is equivalent to
[2, 1]) and
regardless of the collection type (for example,
List<int> can be compared
strict parameter influences this comparison by requiring
that all values in the
expected list are in the
actual list (meaning
expected: [1, 2] is equivalent to
actual: [2, 3, 1] when
false, but not equivalent when
way to think of this is that
strict: false allows
actual to be a strict
strict: true does not.
Circular references are not allowed, and will be surfaced as test failures. For all other reference types,
the public non-static fields and readable properties are compared for equivalence without regard to the
types of the two values and without regard to which values came from fields vs. properties.
Like collections, the
strict flag indicates whether
actual is allowed to be a
strict superset of
strict: false) or an exact match (
true). Reference types inspected in this way determine the equivalence of individual field/property
values by using these same sets of rules when comparing the field/property values. This includes reference
type values (meaning the reference type equivalence is considered to be "deep", not "shallow").
KeyValuePair<,> is handled specially: the keys are checked for equivalence
against each other, as are the values; this allows embedded collections inside of keys and/or
values inside a KeyValuePair.
Assert.Fail which unilaterally fails the test with the given message.
Assert.Multiple which allows the developer to run several independent
assertions (expressed as
Actions) and then collect up all the failures into
a single failure. This behavior differs from the default behavior (which stops running
assertions upon the first failure).
Assert.All which takes an
Action<T, int> so
the inspecting action get access to both the value and its index in the collection.
Assert.Equal for doubles which includes a
Assert.Equal for floats and doubles that allows specifying a
tolerance (rather than a precision).
Assert.Collection with a pointer-style message (like string
assertions) that make it easier to identify the failing part of the collection.
Assert.Empty to match other expected/actual exceptions.
Assert.Single to improve the output message when
being used with a "match" expression (it used to say the collection was empty, but
now correctly mentions the fact that you were matching specific values).
Assert.Equal for strings with
Assert.Equal with collections that can iterate multiple times
(which is generally considered bad form with
IEnumerable). The most egregious case of
this was fixed, though there is still at least one more possibility during test failure to end
up enumerating a second time.
Assert.NotNull tells the compiler that the
object parameter will
null if the function doesn't throw.
tells the compiler that the
object parameter may be
the function doesn't throw.
Assert.DoesNotContain for dictionaries requires
the dictionary key type to be non-nullable.
Assert.Single against non-generic
IEnumerable indicates the return
value may be
null parameter values
are acceptable and when they aren't, as well as updating return signatures to indicate when
returned values may or may not be
Fail) are marked as
never returning (aka, throwing) based on the input data.
XunitException's constructors which take inner exceptions as
Assert.RaisesAsync) no longer express type requirements for
xunit.runner.visualstudio package has a separate lifecycle and
separate minimum framework requirements from xUnit.net core. Use this table
to determine which version you should use (pick the lowest version of
the combination of target frameworks you're using):
Visual Studio does not allow mixed versions of this package in your solution, so do not mix versions; doing so may cause problems running your projects that need the older version of the runner package. Choose the lowest version of the package that applies to all of the test projects in your solution.