xUnit Assert basics: True/False, Equal, Same, Matches and more
Published: Monday 29 September 2025
xUnit has over 30 different assert methods that you can use, but most developers are only using a few.
We are going to explore some of the basic assert methods that can be used for boolean, equality, numeric ranges and string validations.
The methods we are going to test
Throughout this article, we are going to use these methods to write unit tests:
// RatingHelper.cs
public enum RatingEnum
{
Poor,
Satisfactory,
Good,
Great
}
public static class RatingHelper
{
public static RatingEnum GetRating(this int number)
{
return number switch
{
>= 1 and < 2 => RatingEnum.Poor,
>= 2 and < 4 => RatingEnum.Satisfactory,
>= 4 and < 7 => RatingEnum.Good,
>= 7 and <= 10 => RatingEnum.Great,
_ => throw new ArgumentOutOfRangeException("Unable to get rating")
};
}
}// SpeedConversionHelper.cs
public class SpeedConversionHelper
{
public static decimal ConvertToKph(decimal mph)
{
return mph * 1.6093m;
}
}// Product.cs
public record Product(int Id, string Name);Boolean assertions
These are the simplest assertions that are used for condition-based testing. In xUnit, you have either Assert.True or Assert.False. You also have the Assert.Fail method if you want to fail a test method at any point.
// RatingHelperBooleanTests.cs
public class RatingHelperBooleanTests
{
[Theory]
[InlineData(7)]
[InlineData(8)]
[InlineData(9)]
[InlineData(10)]
public static void GetRating_HasGreatRating_ReturnsTrue(int rating)
{
try
{
var act = RatingHelper.GetRating(rating);
Assert.True(act == RatingEnum.Great);
}
catch (Exception)
{
Assert.Fail("Test has failed due to an exception");
}
}
[Theory]
[InlineData(1)]
[InlineData(2)]
[InlineData(4)]
[InlineData(6)]
public static void GetRating_DoesNotHaveGreatRating_ReturnsFalse(int rating)
{
try
{
var act = RatingHelper.GetRating(rating);
Assert.False(act == RatingEnum.Great);
}
catch (Exception)
{
Assert.Fail("Test has failed due to an exception");
}
}
}Equality assertions
These assertions check whether values or objects match each other. If you want to compare values, you have the Assert.Equal and Assert.NotEqual assert methods. There is also a Assert.StrictEqual method. This is very similar to Assert.Equal, but it uses the type's default comparer.
// SpeedConversionEqualityTests.cs
public class SpeedConversionEqualityTests
{
[Fact]
public void ConvertToKph_CheckValidExpected_IsEqual()
{
var act = SpeedConversionHelper.ConvertToKph(100);
Assert.Equal(160.93m, act);
}
[Fact]
public void ConvertToKph_CheckInvalidExpected_IsNotEqual()
{
var act = SpeedConversionHelper.ConvertToKph(100);
Assert.NotEqual(180, act);
}
[Fact]
public void ConvertToKph_CheckValidExpected_IsStrictEqual()
{
var act = SpeedConversionHelper.ConvertToKph(100);
Assert.StrictEqual(160.93m, act);
}
}There are also a number of methods for checking objects. Assert.Same will compare two objects that are the same instance. Assert.NotSame will do the opposite.
You also have Assert.Equivalent which is similar to Assert.Same, but the two objects can have different references as long as they have the same values.
There are also null checker assert methods. These can be used by either calling Assert.Null or Assert.NotNull.
// ProductEqualityTests.cs
public class ProductEqualityTests
{
[Fact]
public void Product_CompareSameObjects_ReturnsSame()
{
var act = new Product(1, "Watch");
var reference = act;
Assert.Same(reference, act);
}
[Fact]
public void Product_CompareDifferentObjects_ReturnsNotSame()
{
var ref1 = new Product(1, "Watch");
var ref2 = new Product(1, "Watch");
Assert.NotSame(ref1, ref2);
}
[Fact]
public void Product_CompareDifferentObjectsWithSameData_ReturnsEquivalent()
{
var ref1 = new Product(1, "Watch");
var ref2 = new Product(1, "Watch");
Assert.Equivalent(ref1, ref2);
}
[Fact]
public void Product_Null_ReturnsNull()
{
Product? ref1 = null;
Assert.Null(ref1);
}
[Fact]
public void Product_CreateInstance_ReturnsNotNull()
{
var ref1 = new Product(1, "Watch");
Assert.NotNull(ref1);
}
}Range assertions
Range assertions are common in numeric testing. You have Assert.InRange where a number is in a range or Assert.NotInRange which does the opposite.
// SpeedConversionHelperRangeTests.cs
public class SpeedConversionHelperRangeTests
{
[Fact]
public void ConvertToKph_Between160And180_InRange()
{
var act = SpeedConversionHelper.ConvertToKph(100);
Assert.InRange(act, 160, 180);
}
[Fact]
public void ConvertToKph_Between180And200_NotInRange()
{
var act = SpeedConversionHelper.ConvertToKph(100);
Assert.NotInRange(act, 180, 200);
}
}String assertions
xUnit offers a variety of assertions tailored for strings, ensuring precise validation of text output. The Assert.StartsWith method compares a string at the beginning with the Assert.EndsWith method doing it at the end. Then you have Assert.Contains and Assert.DoesNotContain which matches a pattern at any point of the string. You can also do regular expression matches by calling either Assert.Matches or Assert.DoesNotMatch.
// RatingHelperStringTests.cs
public class RatingHelperStringTests
{
[Theory]
[InlineData(4)]
[InlineData(9)]
public void GetRating_HasGoodOrGreatRating_StartsWithG(int rating)
{
var act = RatingHelper.GetRating(rating);
Assert.StartsWith("G", act.ToString());
}
[Theory]
[InlineData(8)]
[InlineData(9)]
public void GetRating_HasGreatRating_EndsWithAt(int rating)
{
var act = RatingHelper.GetRating(rating);
Assert.EndsWith("at", act.ToString());
}
[Theory]
[InlineData(8)]
[InlineData(9)]
public void GetRating_HasGreatRating_ContainsRea(int rating)
{
var act = RatingHelper.GetRating(rating);
Assert.Contains("rea", act.ToString());
}
[Theory]
[InlineData(1)]
[InlineData(4)]
[InlineData(6)]
public void GetRating_HasGoodOrPoorRating_MatchesRegex(int rating)
{
var act = RatingHelper.GetRating(rating);
Assert.Matches("^[A-Za-z]{4}$", act.ToString());
}
[Theory]
[InlineData(1)]
[InlineData(4)]
[InlineData(6)]
public void GetRating_HasGoodOrPoorRating_DoesMatchesRegexWithDigits(int rating)
{
var act = RatingHelper.GetRating(rating);
Assert.DoesNotMatch("^[0-9]{4}$", act.ToString());
}
}Watch the video
When you watch this video, you'll find out about these different assert methods so you can use them in your unit tests:
And when you download the code example, you can see how the unit tests are run with these different assert methods.
Final thoughts
There is a good range of assert methods in xUnit for all different types of tests. And we've only covered just over half of the different assert methods available in this article. Therefore, it goes to show that xUnit has you covered for any unit test that you want to write.
Latest tutorials
