Improving Test Code Readability and Assert Failure Messages with Shouldly

Shouldly is an open source library that aims to improve the assert phase of tests; it does this in two ways. The first is offering a more “fluent like” syntax that for the most part leverages extension methods and obviates the need to keep remembering which parameter is the expected or actual as with regular Assert.Xxxx(1,2) methods. The second benefit manifests itself when tests fail; Shouldly outputs more readable, easily digestible test failure messages.

Failure Message Examples

The following are three failure messages from tests that don’t use Shouldly and instead use the assert methods bundled with the testing framework (NUnit, xUnit.net, etc):

  • “Expected: 9  But was:  5”
  • “Assert.NotNull() Failure”
  • “Not found: Monday In value:  List<String> ["Tuesday", "Wednesday", "Thursday"]”

In each of the preceding failure messages, there is not much helpful context in the failure message.

Compare the above to the following equivalent Shouldly failure messages:

  • “schedule.TotalHours should be 9 but was 5”
  • “schedule.Title should not be null or empty”
  • “schedule.Days should contain "Monday" but does not”

Notice the additional context in these failure messages. In each case here, Shouldly is telling us the name of the variable in the test code (“schedule”) and the name of the property/field being asserted (e.g. “Total Hours”).

Test Code Readability

For the preceding failure messages, the following test assert code is used (notice the use of the Shouldly extension methods):

  • schedule.TotalHours.ShouldBe(9);
  • schedule.Title.ShouldNotBeNullOrEmpty();
  • schedule.Days.ShouldContain("Monday");

In these examples there is no mistaking an actual value parameter for an expected value parameter and the test code reads more “fluently” as well.

To find out more about Shouldly check out the project on GitHub, install via NuGet, or checkout my Better Unit Test Assertions with Shouldly Pluralsight course.

SHARE:

Clean C# eBook Published

The final version of my free Clean C# eBook has just been published.

Clean C# eBook Cover Image

 

You can download the book for free from http://cleancsharp.com/

The book contains the following chapters:

  • Comments
  • Naming Things
  • Methods
  • Structuring Programs for Readability
  • Errors and Exceptions
  • Visual Formatting
  • Cohesion and Coupling
  • Clean Tests
  • Building On Clean Code
  • SHARE:

    New Free eBook: LINQ Succinctly

    My new free Syncfusion eBook is now available.

    x-ebook

    LINQ Succinctly is available from the Syncfusion site along with all the other eBooks in the Succinctly series.

    LINQ Succinctly covers the following areas:

    1. LINQ Fundamentals
    2. Fluent and Query Expression Styles
    3. LINQ Query Operators
    4. LINQ to XML
    5. Interpreted Queries
    6. Parallel LINQ
    7. LINQ Tools and Resources

    SHARE:

    Fixie - A Convention-based .NET Testing Framework

    Fixie is a relative newcomer to the .NET testing framework space. It throws away the idea of marking elements of test code with attributes in favour of a conventions based approach.

    At a high level, what this means is simply naming things in test projects following a defined default (customized conventions are also supported) convention.

    A Fixie test class with a single test inside it would look like the following, notice the lack of attributes and even using statements.

    namespace MyApplication.Tests
    {
        public class SomeClassTests
        {
            public void ShouldDoSomething()
            {
            }
        }
    }
    
    

    After building the test will now show up in Visual Studio Test Explorer as the following screenshot shows.

    Visual Studio Test Explorer showing Fixie Test

    Fixie knows this is a test because it matches the default conventions that come out of the box.

    Fixie knows that this is a test class because it ends with “Tests” and it knows that the method is a test because it’s a public void method.

    If these default conventions are not suitable for your project you can create your own custom conventions to customise the test discovery. There’s also a lot more to custom conventions, such as customising the test execution lifecycle and creating data-driven tests.

    To learn more about Fixie, check out the docs or my Introduction to Fixie Pluralsight course.

    SHARE:

    Arrange Act Assert Comments in Tests

    The Arrange, Act, Assert (AAA) pattern is used in tests to help organise and clarify test code. It can also help to spot potential problems in test code if these three phases don’t seem to exist.

    The Arrange phase is where the thing we’re testing (the system under test) is put into a known beginning state.

    The Act phase is where we perform some action on the thing being tested.

    The Assert phase is where we check that the results of the Act phase are as expected.

    When first learning to use the AAA pattern, it can be helpful to start with 3 comments:

    public void ShouldAddNumbers()
    {
        // Arrange
        
        // Act
        
        // Assert
    
    }
    

     

    These comments can help to focus on making sure there are three distinct phases.

    While these comments are useful when trying to learn (or teach) AAA, they should not be needed in the final version of the test code.

    Test code should ideally be as good as production code. One of the things that qualifies code as “clean” is the absence of useless/pointless comments.

    Test code should be easy to read, it should not need the AAA comments to be left in to be able to be understood.

    If you are using the comment-first approach to help you get started and learn the AAA approach that’s all well and good. However, once the test is written, these comments should usually be removed before the code is committed to source control.

    Once the AAA comments are removed, it should still be clear what the flow of the test is. If it is not then the test code may need some changes to improve the readability.

    SHARE:

    New Pluralsight Course - Introduction to .NET Testing with NUnit

    If you are just dipping your toe in the water when it comes to testing .NET applications it can be a bit confusing. In addition to learning how and what to write test, you also have to learn a testing framework such as MSTest, xUnit.net, NUnit, etc.

    My new beginner Pluralsight course helps you to get started with testing in .NET and how to use the NUnit testing framework.

    Watch the course at the above link or get to it from my Pluralsight author page.

    SHARE:

    Using Cyclomatic Complexity as an Indicator of Clean Code

    Cyclomatic complexity is one way to measure how complicated code is, it measures how complicated the structure of the code is and by extension how likely it may be to attract bugs or additional cost in maintenance/readability.

    The calculated value for the cyclomatic complexity indicates how many different paths through the code there are. This means that lower numbers are better than higher numbers.

    Clean code is likely to have lower cyclomatic complexity that dirty code. High cyclomatic complexity increases the risk of the presence of defects in the code due to increased difficulty in its testability, readability, and maintainability.

    Calculating Cyclomatic Complexity in Visual Studio

    To calculate the cyclomatic complexity, go to the the Analyze menu and choose Calculate Code Metrics for Solution (or for a specific project within the solution).

    This will open the Code Metrics Results window as seen in the following screenshot.

    image

    Take the following code (in a project called ClassLibrary1):

    namespace ClassLibrary1
    {
        public class Class1
        {
        }
    }
    

    If we expand the results in the Code Metrics Window we can drill down into classes and right down to individual methods as in the following screenshot.

    image

    More...

    SHARE:

    The ConditionalWeakTable in .NET

    The ConditionalWeakTable class exists in the System.Runtime.CompilerServices namespace and as its namespace suggests is used in compilation processes.

    The class allows a key-value pair to be stored (using its Add method), once the key object no longer has any references outside of the ConditionalWeakTable the key can be destroyed during garbage collection as the key is held as a weak reference inside the table, as opposed to a usual strong reference. At this point the key object can be garbage collected. Also at this point, if the value object also has no other references, it too can be collected. Or too quote MSDN: “It does not persist keys. That is, a key is not kept alive only because it is a member of the collection”.

    The following code shows a console application followed by its output:

    using System;
    using System.Runtime.CompilerServices;
    
    namespace ConditionalWeakTableExample
    {
        class Program
        {
            static void Main(string[] args)
            {
                var cwt = new ConditionalWeakTable<SomeKeyClass, SomeValueClass>();
    
                Console.WriteLine("Creating new instance of SomeKeyClass called key1");
                var key1 = new SomeKeyClass();
    
                Console.WriteLine("Creating new instance of SomeValueClass called value1");
                var value1 = new SomeValueClass();
    
                Console.WriteLine("Creating variable anotherReferenceToKey1 referencing key1");
                var anotherReferenceToKey1 = key1;
    
                Console.WriteLine("Adding key1, value1");
                cwt.Add(key1, value1);
    
    
    
    
                Console.WriteLine("Press a key to set key1 to null");
                Console.ReadLine();
                key1 = null;
                Console.WriteLine("key1 to null");
    
                ForceGc();
    
    
    
    
                Console.WriteLine("Press a key to set anotherReferenceToKey1 to null");
                Console.ReadLine();
                anotherReferenceToKey1 = null;
                Console.WriteLine("anotherReferenceToKey1 to null");
    
                ForceGc();            
    
    
    
    
                Console.WriteLine("End of program - press any key to exit");
                Console.ReadLine();
            }
    
    
            private static void ForceGc()
            {
                Console.WriteLine("Forcing garbage collection and waiting for finalizers");
                GC.Collect();
                GC.WaitForPendingFinalizers();
            }
        }
    
    
        class SomeKeyClass
        {
            ~SomeKeyClass()
            {
                Console.ForegroundColor = ConsoleColor.Red;
                Console.WriteLine("****** SomeKeyClass Destroyed");
                Console.ResetColor();
            }        
        }
    
        class SomeValueClass
        {
            ~SomeValueClass()
            {
                Console.ForegroundColor = ConsoleColor.Red;
                Console.WriteLine("****** SomeValueClass Destroyed");
                Console.ResetColor();
            }
        }
    }
    
    
    image

     

    So here, even though the cwt contains an entry using key1, it is held in a weak way so it will not prevent garbage collection.

    Also notice in this example, the value object has not been destroyed as we still have a reference to it in the variable value1.

    If we change the code to also set value1 to null, when the Garbage Collector runs it will destroy the key object as before, but now there are also no references to the value object, so it too can be destroyed:

    static void Main(string[] args)
    {
        var cwt = new ConditionalWeakTable<SomeKeyClass, SomeValueClass>();
    
        Console.WriteLine("Creating new instance of SomeKeyClass called key1");
        var key1 = new SomeKeyClass();
    
        Console.WriteLine("Creating new instance of SomeValueClass called value1");
        var value1 = new SomeValueClass();
    
        Console.WriteLine("Creating variable anotherReferenceToKey1 referencing key1");
        var anotherReferenceToKey1 = key1;
    
        Console.WriteLine("Adding key1, value1");
        cwt.Add(key1, value1);
    
    
    
    
        Console.WriteLine("Press a key to set key1 to null");
        Console.ReadLine();
        key1 = null;
        Console.WriteLine("key1 to null");
    
        ForceGc();
    
    
    
    
        Console.WriteLine("Press a key to set anotherReferenceToKey1, value1 to null");
        Console.ReadLine();
        anotherReferenceToKey1 = null;
        value1 = null;
        Console.WriteLine("anotherReferenceToKey1 & value1 to null");
    
        ForceGc();            
    
    
    
    
        Console.WriteLine("End of program - press any key to exit");
        Console.ReadLine();
    }
    

     

    image

     

    So even though this is not a class we’d use in everyday coding, it’s one of the many interesting things in .NET that are hidden away in namespaces we don’t usually use. It also should be noted that it doesn’t really behave as a “normal” dictionary, for example it doesn’t contain GetEnumerator method.

    To learn some cool C# Tips, check out my free C# Tips eBook or my Pluralsight C# Tips and Traps course.

    SHARE: