DEV Community: Mohsen Bazmi

Writing High Quality Tests to Foster Abstractions to Evolve

Mohsen Bazmi — Tue, 28 May 2024 06:52:21 +0000

In the intricate world of software design, distinguishing between stable and volatile components is essential. Our tests should rely on stable abstractions, yet the iterative nature of modeling often reveals instability in what was once deemed rock-solid. However, modifying these abstractions can be risky as tests may not adequately safeguard them. These series of articles aim to address this challenge by leveraging some automation testing patterns and exploring strategies for crafting automated tests that enhance the safety of the refactoring process, despite the evolving nature of software design.

In these series of articles, we will delve into various approaches for building maintainable tests. We’ll discuss the advantages and disadvantages of each method. Our journey begins with an illustrative test case for a poorly designed system. Instead of immediately revamping the system’s design, we will investigate various methods to adjust the test that safeguards our refactoring initiatives.

As we progress, we will discover techniques to optimize the scope of units under test. At the same time, we’ll gain insights into the factors we need to control in order to safeguard the quality of tests throughout our journey. Smells to sniff and goals to protect. The following image illustrates them.

\newline

We'll start with deliberately using a poorly designed model and a subpar test surrounding it, we'll investigate diverse approaches to tackle the issues.

To kick things off, let's consider a simple scenario: scheduling a doctor's appointment with a naive unsophisticated domain model.

public void Successful_Appointment()
{
    //Arrange

        //Load the doctor
        Doctor doctor = new Doctor();
        doctor.Name = "David Smith";
        doctor.HourlyRate = 80;


        //Load the patient
        Patient patient = new Patient();
        patient.Name = "Maria Garcia";
        patient.Age = 65;

    //Exsercise
        var appointment = new Appointment();
        appointment.Doctor = doctor;
        appointment.Patient = patient;
        var time = DateTime.Now.AddDays(2);
        var fee = 80;

        appointment.Make(doctor, time, fee);

    //Assert: 
       Assert.Equal("David Smith", appointment.Doctor.Name);
       Assert.Equal("Maria Garcia", appointment.Patient.Name);
       Assert.Equal(DateTime.Now.AddDays(2), appointment.Time);
}

Despite the issues in the test code, it is clear that the domain model lacks a robust design. However, at this moment, we choose not to delve into those issues. Our current domain knowledge informs us that we should defer further design considerations.

Now, the critical question arises: In this specific scenario, does the test effectively protect the model, allowing us to refactor it later?

“Whenever I do refactoring, the first step is always the same. I need to ensure I have a solid set of tests for that section of code. The tests are essential because even though I will follow refactorings structured to avoid most of the opportunities for introducing bugs.”
— Martin Fowler

How confident can we be in refactoring the domain model? For instance, can I modify the model to be used as follows without breaking the test mentioned above?

Doctor doctor = new Doctor("David Smith", 80);
Patient patient = new Patient("Maria Garcia", 65);
patient.ScheduleAppointment(DateTime.Now.AddDays(3));

Clearly not. Smallest change to the interface will fail the test. Even if the system's behavior stays the same.

The problem of our test is known as Interface Sensitivity (XUnit Patterns).

Besides Interface Sensitivity, the test doesn't document the system's behavior transparently.

A quick step towards addressing both problems is to extract the test steps into separate methods. These methods can also be extracted into a separate class (named Appointment), and express the Ubiquitous Language (DDD) in the methods’ names.

public void Successful_Appointment()
{
    appointments
        .Given(David_Smith_is_a_doctor())
          .And(Maria_Garcia_is_a_patient())
        .When(Maria_Garcia_makes_an_appointment_with_Dr_Smith())
        .Then(Maria_Garcia_should_have_an_appointment_with_Dr_Smith());
}

We extracted four methods.

David_Smith_is_a_doctor()
Maria_Garcia_is_a_patient()
Maria_Garcia_makes_an_appointment_with_Dr_Smith()
Maria_Garcia_should_have_an_appointment_with_Dr_Smith()

These are called Test Utility Methods (XUnit Patterns) and the class that contains them (Appointment) is called a Test Helper (XUnit Patterns).

The methods can be reused in multiple test cases.

Each Test Utility Method is a single source of truth. It implies that whenever a change breaks one or more tests that use our new Test Utility Methods it's much easier to find and update them accordingly to go back green again (pass all the tests that are impacted by the change). So this refactoring made our test more maintainable for two reasons.

We made a more supportive Safety Net.
In terms of documentation, the Test Utility Method names explicitly conform to the Ubiquitous Language. So the methods are easier to find whenever a change is required.

So can we call this test an executable documentation? I don't think so. 😔 The maintainability can also be improved further. We will learn more on them later.

So far, we learned to enhance the quality of our safety net by extracting Test Utility Methods and Test Helpers. This was the first refactoring and the simplest one in our journey. With a few more minor adjustments, this kind of refactoring can serve as a last-resort solution 😁. But let's see what exactly is wrong with it first.

Tests as Documentation

Ideally, tests should have the following properties to be considered as executable documentation.

Ubiquitous Language (DDD): They should conform to the Ubiquitous Language (DDD), so that it's easily understandable by non-technical domain experts.
Proof of Claims: How much the test proves what it claims? The test's reader should transparently see the effect of API calls on the system. This also simplifies the debugging process in the event of unexpected failures.
Usability Guide: Tests should contain information about how the system under test can be used, effectively serving as a form of live documentation.
Easy to Grasp: All of the properties above should be easily graspable at first glance. Tests should be easy to read and understand, Even for someone who is not familiar with the codebase. Easy to understand tests are also more maintainable.
Always-Up-to-Date Documentation: Changes to the production code should reflect into the tests with minimum hassle. This can be achieved using refactoring tools or other automated methods to ensure that the tests remain up-to-date as the system evolves. This is crucial for maintaining the accuracy of the documentation provided by the tests.
Expressive Result Verification: Testing procedures should strike a balance, avoiding excessive or insufficient verification. The focus of verification should be meaningful and aligned with business requirements. Transparent examination of API call results through explicit assertions.
Minimal Distraction: Tests should minimize the noise for readers. They should only contain relevant information.

The properties try to shape a common image. They picture what an ideal executable documentation looks like. Some of them may sound overlapping. In fact, they try to complement each other. They are different dimensions of the same concept.

We we are not prescribing a one size fits all solution. Not all properties can be perfectly applied into a single test.

Let's take a look at our test again.

public void Successful_Appointment()
{
    appointments
        .Given(a => a.David_Smith_is_a_doctor())
          .And(a => a.Maria_Garcia_is_a_patient())
        .When(a => a.Maria_Garcia_makes_an_appointment_with_Dr_Smith())
        .Then(a => a.Maria_Garcia_should_have_an_appointment_with_Dr_Smith());
}

While Ubiquitous Language is clearly expressed in this test, It still cannot be used as an average documentation. The following chart illustrates how the qualities apply to this test. 🧐

Let's try to parameterize the Test Utility Methods to see if it improves the test's quality as documentation.

public void Successful_Appointment()
{
    const string Dr_David_Smith = "David Smith";
    const string Maria_Garcia = "Maria Garcia";
    const string time = "2024-10-10";

    appointments
      .Given(a => a.Register_Doctor(Dr_David_Smith))
        .And(a => a.Register_Patient(Maria_Garcia))
      .When(a => a.Make_Appointment(Dr_David_Smith, Maria_Garcia, time))
      .Then(a => a.Appointment_should_exist_for(Dr_David_Smith, Maria_Garcia, time));
}

The Test Utility Methods might pass additional parameters to the production APIs, however, we only passed what matters in this scenario, and let the utility methods to decide on the rest. By only passing the parameters that matter in this scenario to the Test Utility Methods we made the causal relationship between the steps (Given, When, and Then) more transparent. It's usually a good practice to paramerize the test method as well.

[InlineData("Dr David Smith", "Maria Garcia", "2024-10-10")]
public void Make_appointment_for(string Dr_Smith, string  Maria, string at_13)
{
  appointments
    .Given(a => a.Register_Doctor(Dr_Smith))
      .And(a => a.Register_Patient(Maria))
    .When(a => a.Make_Appointment(Dr_Smith, Maria, at_13))
    .Then(a => a.Appointment_should_exist_for(Dr_Smith, Maria, at_13));
}

By parameterizing the test, this test explicitly expresses the data it depends on. The Test Utility Methods are also more reusable and they convey their intention more transparently. Besides, it can proof what it claims better by adding different variations of data.

[InlineData("Dr John Davis", "Jane Miller", "2020-03-05")]
[InlineData("Dr Sam Brown", "Tony Jones", "2020-03-05")]
[InlineData("Dr David Smith", "Maria Garcia", "2024-10-10")]
public void Make_appointment_for(string Dr_Smith, string Maria, string at_13)

The BDD framework does not sound necessary any more. We can remove it.

[InlineData("Dr David Smith", "Maria Garcia", "2024-10-10")]
public void Make_appointment_for(string Dr_Smith, string Maria, string at_13)
{
  //Given
  appointments.Register_Doctor(Dr_Smith);
  appointments.Register_Patient(Maria);

  //When
  appointments.Make_Appointment(Dr_Smith, Maria, at_13);

  //Then
  appointments.Appointment_should_exist_for(Dr_Smith, Maria, at_13);
}

The refactored version of our test partially documents the system's functionality, but it's yet to reach the level of ideal documentation. Let's see how this refactoring affects the chart.

The diagram illustrates a an optimistic language for assessing the quality of our test as documentation. However, it's not the most straightforward language for warning potential quality deficiencies in software. In software industry literature, a more skeptical yet direct language is employed. In this context, the word smells is used to warn symptoms of potential quality shortcomings. So let's pause and learn more about test smells.

We saw a simple example of how simple safety nets can protect our evolving design. But it's not always that straightforward. Our initial BDD-style test wasn't cutting it in terms of quality. We remedied the quality issues, and turned our BDD style test into a solid fallback plan.

Now, it's time to take things slow and mix our exploration with some theory and discussion to tackle the issues more directly. We're starting from scratch. We want to stick with the imperfect domain model design for as long as possible, so we can explore different problems and figure out solutions to build strong yet flexible safety nets.

Introduction to Test Smells
Test smells are indicators of potential issues or weaknesses in our tests. Similar to code smells in production code, which signal areas requiring refactoring or enhancement, test smells highlight areas where tests could be improved to ensure better quality. They're used as cues for possible deficiencies in the design or implementation of the test suite. Some smells lead to other smells.

And a few smells may be called by different aliases.

The purpose of this guide is to keep it rather example-based and practical. Let's look for a couple of those symptoms in our original test.

public void Successful_Appointment()
{
    //Arrange

        //Load the doctor
        Doctor doctor = new Doctor();
        doctor.Name = "David Smith";
        doctor.HourlyRate = 80;


        //Load the patient
        Patient patient = new Patient();
        patient.Name = "Maria Garcia";
        patient.Age = 65;

    //Exsercise
        var appointment = new Appointment();
        appointment.Doctor = doctor;
        appointment.Patient = patient;
        var date = DateTime.Now.AddDays(2);
        var time = DateTime.Now.AddDays(2);
        var fee = 80;

        appointment.Make(date, time, fee);

     //Assert
        Assert.Equal("David Smith", appointment.Doctor.Name);
        Assert.Equal("Maria Garcia", appointment.Patient.Name);
        Assert.Equal(DateTime.Now.AddDays(2), appointment.Time);
}

The most obvious issue with this test is that it's not easy to understand it at a glance. This smell is called Obscure Test(XUnit Patterns). But that is a general problem. Lots of smells can lead to Obscure Tests. Which ones are the root causes in our test?

\newline \newline \newline \newline \newline

To be continued...

When do you avoid writing unit tests?

Mohsen Bazmi — Mon, 06 Jul 2020 18:16:49 +0000

Plug your existing domain models into NServiceBus Sagas

Mohsen Bazmi — Mon, 06 Jul 2020 15:13:17 +0000

“An NServiceBus saga is an Aggregate root.” Udi Dahan

“An aggregate can be seen as a state machine/workflow so a very good solution when using NServiceBus is to use sagas to implement aggregates.” Mauro Servienti

Mauro Servienti also states that, if needed, domain events can be published by NServiceBus. There is no need to reinvent the wheel.

This article will explain how to plug an “existing” aggregate into an NServiceBus saga.

But why should one ever do that? Why not use sagas as aggregates instead of adding another layer of indirection?

Because legacies are everywhere. Maybe you aren’t using NServiceBus already and now you want to adopt it. For example, you may have “deferred” some infrastructural decisions while designing your system, and now you’ve come up with adopting NServiceBus to make your system more scalable, or eliminate the maintenance of all the unnecessary home-made implementations, and focus on solving your core business problems instead. Let’s keep it short.

Imagine the following user aggregate:

Now we want to plug it into the following NServiceBus Saga:

So we don’t have to implement the repository to persist the user aggregate. The saga takes care of that for us.

Another benefit is that NServiceBus publishes the domain events which keeps us from maintaining all the unnecessary infrastructure to store the events, pick them up, put them into the queue, notify the listeners, and preserve the transaction consistency.

We need to focus on our core business problems instead of reinventing the wheel.

But what about the order of the events? Does NServiceBus preserve the order of the events? Well, as far as I know, NServiceBus does not have that option. The order of messages matter in some scenarios. Preserving the order is not the responsibility of the messaging infrastructure. We can easily attach a version to each event before publishing them, which can be a subject for another post. Here is a modified version of the previous extension method to show the idea.

You got it. But it’s tricky to plug your domain events into sagas. The complete runnable sample project and the additional classes that help the NServiceBus SagaData class wrap the aggregate can be found in this GitHub repository. I

Special thanks to Mauro Servienti, solution architect from Particular Software for answering my questions, and for helping me with editing this article.

Summary
You can use sagas as your aggregate roots and keep things simpler, but in legacy scenarios, it’s usually not worth it.
You may have “deferred” some infrastructural decisions and now you’ve decided to adopt NServicebus to make your system more scalable.
An NServiceBus Saga can wrap DDD style aggregates so that you can focus on your core business problems.

Focus on your core business problems rather than implementing Infrastructure.

Thank you for reading.

Your value objects are your test data builders

Mohsen Bazmi — Thu, 14 May 2020 15:31:09 +0000

In previous post we saw how changes to constructors can turn into a burden of shotgun surgery of many unit tests. Calling constructors in unit tests can also jeopardize the trustworthiness of unit tests in the long run. In this post we will see some refactoring proof examples of creating Value Objects for tests.

In previous post we saw the Point value object with the following constructor :

var point = new Point(x : 32, y : -9);

Now we know why calling it in the unit test bodies is a bad idea. We also went through a couple of workarounds to avoid calling them which may suffice in some situations. One of the solutions was calling a factory:

public static Point CreateAPoint()
{
    return new Point(32, -9);
}

In this post we will see more ways of creating test value objects, and finally add some language around the pattern in order to give the constructors more freedom to change later on.

As I said test builders can be useful but almost always it's best not to use test specific builders for building Value Objects. Your Value Objects are your test builders:

public class Point
{
    public Point(double x, double y, double z = 0)
    {
       ...
    }
    public Point ButWithX(double alternativeX)
    {
        return new Point(alternativeX, this.Y, this.Z);
    }
...

Let's call it:

public void Point_remembers_its_x()
{
    var point = CreateAPoint().ButWithX(32);
    point.X.Should().Be(32);
}

Now the factory method CreateAPoint() creates a valid default Value Object outside of the scope of the test method's body, and customizing the created Point is done locally inside of the test method's body using the Value Object's API. Calling CreateAPoint().ButWithX(32) makes the test yell at the reader that the only thing important thing in this scenario is X, no matter what Y or Z are, no matter what any additional future constructor parameters will be, and no matter how the Value Object gets created. How an instance of a Point should be created is not the responsibility of the test. The test asks CreateAPoint() to take care of that.

Which class does the factory method belong to?

What if we want to create the Value Object to be used by multiple test classes? We definitely don't like to do this:

PointTests.CreateAPoint()

The creation of a Value Object does not fit into the responsibilities of a test class. A value object may be used by multiple aggregates that each have a separate unit test class.

The factory method is better to be extracted into a new class which is responsible for creating multiple (or all) Value Objects needed by any of the unit tests.
The class may be alarming to be bloated at first glance, but breaking it down does not really add value.

public static class A
{
    public static Point Point => new Point(32, -9);
}

You got the idea.
Let's call it:

public void Point_remembers_its_x()
{
    var point = A.Point.ButWithX(32);
    point.X.Should().Be(32);
}

Much better! The language is shining.
There is yet another way of avoiding calling constructors in unit tests. We can use data generators for many scenarios. In dotnet Autofixture library can be used to create a random Value Object:

public void point_remembers_its_x()
{
    var point = new Fixture().Create<Point>().ButWithX(32);
    point.X.Should().Be(32);
}

Rather than calling test data generators directly from the unit test method's body, hide the random creation of test data behind the interface of the A class and let the A class decide how to create the object:

public static class A
{
    public static Point Point => new Fixture().Create<Point>();
}

Since a valid X is between -90 and +90 and Y should be from -180 to 180 the test data generator should be configured to generate the Value Object correctly which is outside of the scope of this post.

public void Point_remembers_its_x()
=> A.Point
  .ButWithX(32)
  .X.Should().Be(32);

We can also add more methods to the A class:

public static class A
{
    public static Point Point => new Fixture().Create<Point>();
    public static Relocation Relocation => new Relocation(from: Point, to:Point);
}

The A class encapsulates the creation of more complex Value Objects. The factory methods can be easily composed inside the A class.

Summery

Direct object instantiation in unit test method bodies can end up fragile and untrustworthy safety nets.
No safety net is a lot of the time better than an untrustworthy one.
Value Objects can be used as test data builders.
How to build Value Objects is rarely the responsibility of unit tests.
Test data generators are best to be kept outside of unit test method bodies.

Full runnable project sample for this post can be found on this github repository.

Thanks for reading.

Don’t call constructors in unit tests

Mohsen Bazmi — Thu, 14 May 2020 10:58:02 +0000

Writing good tests is tricky. Modifying implementation details should not break tests. A lot of times constructors are implementation details. Especially the ones we hide behind interfaces. Also, constructors usually change more frequently than methods. In this post, we're going to quickly see a couple of simple examples of how calling constructors in unit tests can turn into a disaster, then we will see some workarounds to avoid them in different situations.

Let's start with a simple immutable Point Value Object:

var point = new Point(x : 32, y : -9);

And test if it remembers the x we passed to it's constructor:

public void Point_remembers_its_x()
{
    var point = new Point(x : 32, y : -9);
    point.X.Should().Be(32);
}

Look at the magic numbers: 32 , -9 ,....
The test is not trustworthy. I would generate them randomly.The trustworthiness can be a subject for another post. I'd use the magic numbers for these series for the sake of simplicity.

Notice that for assertion the FluentAssertions library is used here. You can use any tool that's convenient for you depending on the programming language you use.
The implementation of production code is straightforward.

Now Let's add another test:

public void Point_rejects_x_when_it_is_greater_than_90()
{
    Action newPoint = () => new Point(x: 92, y: -9);
    newPoint.Should().Throw<ArgumentOutOfRangeException>();
}

There are also other tests:

Point rejects X when it is smaller than -90.
Point rejects Y when it is greater than -180.
Point rejects Y when it is smaller than -180.
Point remembers it's Y. I skip writing the test bodies in the post as they are straightforward. So we have 6 tests so far and each one call the constructor of the Point. A couple of iterations later it turns out that Z is also required to be a part of Point. That requires shotgun surgery of all of the 6 unit tests! The Point is a fairly simple predictable object, what about more complex objects with more unit tests? By each change in a constructor we need to update tens of tests. It not only is time consuming and boring, but also every time you change a unit test you reduce it's trustworthiness. We may change the signature of a constructor, and forget to update the test accordingly. So an old test may pass Y as X parameter to the constructor somewhere. That small change ends up with unit tests that should not pass but they do. And a lot of times not having a safety net at all is much better than having an untrustworthy one.

A simple solution would be setting default parameters to avoid changing all of the tests:

public class Point
{
    public Point(double x, double y, double z = 0)
    {
...

That works here. Changes to the constructor parameters no longer need all of the tests to be updated, but there are still other problems that we may face when unit testing less obvious domains. For example a new parameter may require to be placed between the existing parameters, and as we know many programming languages (like C#) require optional parameters to be last parameters.

Another solution would be extracting the creation of a valid instance of the class to a factory method, so that every time the constructor changes, a single factory method needs to be changed.

public Point CreateAPoint()
{
    return new Point(32, -9);
}

So all tests call this single factory method. If the constructor changes later on, I will easily change this single factory method to support all of my existing tests. Let's call it:

public void Point_remembers_its_x()
{
    var point = CreateAPoint();
    point.X.Should().Be(32);
}

But we have a mystery guest here. Why should X be 32?

That's not readable and causes Yoyo Problem.
That's not safe. What if I change the implementation of the CreateAPoint() factory method?
And as mentioned before, that's not trustworthy.

Trustworthiness can be addressed by test builders. But Value Objects don't usually need separate test specific builders. Value Objects can act as builders of themselves. It's best not to add redundant Value Object builders in unit test projects. Value Objects are linguistically allowed to act as builders of themselves, even if some of the builder methods never get called by production code.
Let's dig deeper in the next post and see more detailed examples of how to build clean Value Objects in unit tests.