An assertion is a statement that checks whether a particular condition is true or false. If the condition is true, the test passes. If the condition is false, the test fails, indicating a problem with the subject under test.Let’s visit a few ways to assert correctness. We use barebone xUnit functionality in this section, but you can bring in the assertion library of your choice if you have one.
In xUnit, the assertion throws an exception when it fails, but you may never even realize that. You do not have to handle those; that’s the mechanism to propagate the failure result to the test runner.
We won’t explore all possibilities, but let’s start with the following shared pieces:
public class AssertionTest
{
[Fact]
public void Exploring_xUnit_assertions()
{
object obj1 = new MyClass { Name = “Object 1” };
object obj2 = new MyClass { Name = “Object 1” };
object obj3 = obj1;
object?
obj4 = default(MyClass);
//
// Omitted assertions
//
static void OperationThatThrows(string name)
{
throw new SomeCustomException { Name = name };
}
}
private record class MyClass
{
public string?
Name { get; set; }
}
private class SomeCustomException : Exception
{
public string?
Name { get; set; }
}
}
The two preceding record classes, the OperationThatThrows method, and the variables are utilities used in the test to help us play with xUnit assertions. The variables are of type object for exploration purposes, but you can use any type in your test cases. I omitted the assertion code that we are about to see to keep the code leaner.The following two assertions are very explicit:
Assert.Equal(expected: 2, actual: 2);
Assert.NotEqual(expected: 2, actual: 1);
The first compares whether the actual value equals the expected value, while the second compares if the two values are different. Assert.Equal is probably the most commonly used assertion method.
As a rule of thumb, it is better to assert equality (Equal) than assert that the values are different (NotEqual). Except in a few rare cases, asserting equality will yield more consistent results and close the door to missing defects.
The next two assertions are very similar to the equality ones but assert that the objects are the same instance or not (the same instance means the same reference):
Assert.Same(obj1, obj3);
Assert.NotSame(obj2, obj3);
The next one validates that the two objects are equal. Since we are using record classes, it makes it super easy for us; obj1 and obj2 are not the same (two instances) but are equal (see Appendix A for more information on record classes):
Assert.Equal(obj1, obj2);
The next two are very similar and assert that the value is null or not:
Assert.Null(obj4);
Assert.NotNull(obj3);
The next line asserts that obj1 is of the MyClass type and then returns the argument (obj1) converted to the asserted type (MyClass). If the type is incorrect, the IsType method will throw an exception:
var instanceOfMyClass = Assert.IsType<MyClass>(obj1);
Then we reuse the Assert.Equal method to validate that the value of the Name property is what we expect:
Assert.Equal(expected: “Object 1”, actual: instanceOfMyClass.Name);
The following code block asserts that the testCode argument throws an exception of the SomeCustomException type:
var exception = Assert.Throws<SomeCustomException>(
testCode: () => OperationThatThrows(“Toto”)
);
The testCode argument executes the OperationThatThrows inline function we saw initially. The Throws method allows us to test some exception properties by returning the exception in the specified type. The same behavior as the IsType method happens here; if the exception is of the wrong type or no exception is thrown, the Throws method will fail the test.
It is a good idea to ensure that not only the proper exception type is thrown, but the exception carries the correct values as well.
The following line asserts that the value of the Name property is what we expect it to be, ensuring our program would propagate the proper exception:
Assert.Equal(expected: “Toto”, actual: exception.Name);
We covered a few assertion methods, but many others are part of xUnit, like the Collection, Contains, False, and True methods. We use many assertions throughout the book, so if these are still unclear, you will learn more about them.Next, let’s look at data-driven test cases using theories.