Bruno Peeters Technical Blog

An assertion are used within programming code, to check if some predicate holds at runtime. This means a check should be true to let the assertion not ‘assert’. When the assertion fails depending on the used assertion framework, it will let the user know that the assertion failed. In this way it can help to make your software more robust against programming errors.

The main characteristics of assertions

Assertions are first and all used by developers to test the code they have written, by checking if a certain condition is false. It helps programmers to write what specifications a piece of code should hold in order to be correct. For example it can test for pre- and postconditions. In this way they can specify the contract of the method (i.e. designing by contract).

They can be turned on and off during runtime, or even compiled out of the code. Typically they are not part of any production code.

An assertion at least contains one argument, that is a boolean expression that describes the assumption that must be true to let the assertion not to assert. Depending on the used assertion framework, it will throw an exception if the assertion fails.

Besides the guard that must be true, you can also provide a message that will be displayed when the assumption failed.

Example of an assertion

In C# an assertion can be written like this:

private int CelciusToFahrenheit(int degreesCelcius)
{ 
    Debug.Assert(degreeCelcius < -273, "Degree celcius can't be smaller then -273")
    int result = degreesCelcius;    
    if (degreeCelcius < -273)
    {
       result = -273;
    }

The example above typically defines the precondition of the method and validates this. If the temperature is lower then -273, then the assert will be false and the message "Degree celcius can't be smaller then -273" will be shown. When the code is shipped and the assertions are turned off, the assertion will actually not be triggered and the degrees Fahrenheit will be calculated based on the absolute zero, meaning -273 degrees Celcius.

Assertions compared to exceptions

Something that might look close to assertions, are exceptions. However, there are some major differences between those two concepts. First of all exceptions are always part of the compiled code. As said earlier, assertions can be turned on or off during runtime or being compiled out. This means the assertions won’t be part your final compiled code. So assertions can be turned off, exceptions not.

There is also a difference in where they are used. Exceptions are used to check if exceptional cases don’t occur. Therefore, exceptions are more used as a guard of an interface. For example checking if parameters passed on to a public method contain a valid value. Within your private methods, it is more appropriate to use assertions to check if a in-between value of a variable is valid.

Assertions are also used for documenting the contract of a method. Although exceptions can be used to guard inputs of an exception, which then yields in an exception if they are violated, exceptions are not used to check any post conditions.

Unit tests and assertions

One place where assertions extensively used are unit tests. Exceptions aren’t used over here, since we expect the possibility that some failure could occur and therefore is possible. By throwing an exception, you let others know that something really unexpected occurred and the code doesn’t know to handle this. Calling code can then deal with this.

Assertions let you clearly communicate your expectations. By writing Assert.That(retrievedValue, Is.EqualTo(expectedValue)) you can clearly read what you are expecting, namely that the retrieved value is equal to the expected value.

The assertion framework can be build in such a way, the test won’t fail directly when the first assertion failed. In this way also the subsequent assertions can be evaluated. In this way it can show which tests failed and still continue test the other asserts.

So we use assertions instead of exceptions within unit tests for the following reasons:

• Within a test we expect something can go wrong
• Assertions clearly communicate to the reader what is expected
• If one assertion fails, rest of the assertions can still be evaluated

When to use assertions

So in sort, when to use assertions:

• To test your code during development
• To document pre- and postconditions or other assumptions within the code