Two readability tips - naming and organizing tests

I have mentioned earlier that readability is one of the pillars of good unit tests. Making readable unit tests is not trivial. It takes practice, but there are some good practices that can be applied to get a good start.

As an example, let's consider a test which verifies that a vector dot product is calculated correctly.

Naming

How do you name your unit tests? You should be able to get an idea of what a test verifies by just reading the name. Test names like this tell nothing about the tests:

[Test]
public void VectorDotProductTest1()
{
   ...
}

[Test]
public void VectorDotProductTest2()
{
   ...
}

This is more descriptive, but reading the names is still a bit akward:

[Test]
public void TestThatTheVectorDotProductIsZeroWhenOneOfTheVectorsIsZero()
{
   ...
}

[Test]
public void TestThatTheVectorDotProductIsDoneCorrectlyWhenVectorsAreNonZero()
{
   ...
}

Having a standard naming pattern like this makes it easier:

ItemUnderTest_Scenario_ExpectedBehaviour

As you can see, the name is divided into three parts, divided by underscores. The three parts are

• Item under test: The item, usually a property, method or constructor, which is being tested
• Scenario: The scenario, e.g. input data, parameters or other prerequisites
• Expected behaviour: The expected result or outcome of the test

The previous examples would then be:

[Test]
public void DotProduct_OneVectorIsZero_ReturnsZero()
{
   ...
}

[Test]
public void DotProduct_VectorsAreNonZero_ReturnsCorrectProduct()
{
   ...
}

As you can see, dividing the names into sections following a defined pattern makes the names much easier to read.

Organizing the tests

How do you organize your tests? It should be perfectly clear to the user which part of the test is doing setup and preparation (arrangement), which part does the action which is being tested (act) and which part is doing the assertion (assert).

A common and recommended way to achieve this is to follow the "Arrange,Act,Assert" (AAA) pattern. The test is strictly divided into Arrange, Act and Assert sections like this:

[Test]
public void DotProduct_VectorsAreNonZero_ReturnsCorrectProduct()
{
  // Arrange
  var lhsVector = new Vector(1, 2, 3);
  var rhsVector = new Vector(4, 5, 6);

  // Act
  double result = lhsVector.DotProduct(rhsVector);

  // Assert
  Assert.AreEqual(26, result);
}

In this test, the AAA pattern makes it perfectly clear and obvious to the reader which part is doing what. Moreover, this pattern makes it easier to maintain the test. It's much harder to maintain a test where the asserts are spread all over the place.

If you find that it's tempting to add asserts in between the Arrange and Act sections, it's a sign that it's worth considering refactoring the test and/or the production code... or just take deep breath and have a coffee.

"We are too busy"

This seems to be the most common argument against test-driven development... ;-)

TDD and 3D visualization

So far I have been posting about fairly trivial stuff -- fundamentals and best practices of TDD. Let's step out of the comfort zone and talk about something less comfortable: testing of 3D graphics applications.

This is an area which is not covered much (or not at all) by text books or articles. Why? I think it's mainly because it's harder to test 3D graphics than testing numeric algorithms or database manipulation. Another reason is that the web application community seems to have been better at picking up TDD than the scientific or game development community.

It's not impossible, though. So where do we start? Let's have a look on a scenario where we want to develop an application with a 3D scatter plot of a 4 dimensional dataset. The plot has the following requirements:

• All data samples shall be represented as spheres in 3D space
• The first 3 dimensions shall be defined by the spatial X/Y/Z position in the plot
• The 4th dimension shall be indicated with a color
• In order to ble able to focus on a specific area and minimize the cluttering of the display, the user shall be able to interactively move a box-shaped probe in the plot and make the points outside of this box smaller.

These are typical requirements for a scientific application, but the principles for testing it can be applied to geological 3D models, medical data, games or other kinds of 3D graphics.

The plot should look like this (left). The user is focusing on a smaller area (right).

Know what you are testing

Testing 3D graphics can seem a bit daunting. How do you verify that the graphics card is producing the correct pixels animated on the screen? The short answer is: usually you shouldn't.

Keep in mind the pillars of good unit tests: test the right thing. Also keep in mind the Single Responsibility Principle. What is the visualization code under test doing? Is it actually producing pixels, or is it using a 3D rendering toolkit to do the visualization?

High-level visualization

3D visualization software often use a high-level 3D toolkit like Open Inventor, VTK or HueSpace to do the 3D rendering. In this case, you should trust that the 3D toolkit is rendering correctly whatever you instruct it to render. Your code is creating a scenegraph or a visual decision tree, and the 3D toolkit is doing the rendering based on this.

Let's say that we have a dataset and data sample class that looks like this:

public struct DataSample
{
  public double ValueDim1;
  public double ValueDim2;
  public double ValueDim3;
  public double ValueDim4;
}

public class Dataset
{
  public event ChangedEventHandler DataSamplesChanged;

  public IEnumerable<DataSample> DataSamples { get; private set; }

  ...and the rest of the implementation here
}

The plot view is a class which takes a dataset as constructor parameter and produces an Open Inventor scenegraph. A naive Open Inventor implementation might look like this:

public class ScatterPlotView
{
  private Dataset _dataset;
  public SoSeparator OivNode { get; private set; }

  public ScatterPlotView(Dataset dataset)
  {
    _dataset = dataset;
    this.OivNode = new SoSeparator();

    UpdateNode();
  }

  private void UpdateNode()
  {
    this.OivNode.RemoveAllChildren();

    foreach (var dataSample in _dataset.DataSamples)
    {
      var sampleRoot = new SoSeparator();
      var color = new SoMaterial();
      sampleRoot.AddChild(color);
      color.diffuseColor.SetValue(GetColorByValue(dataSample.ValueDim4));

      var translation = new SoTranslation();
      sampleRoot.AddChild(translation);
      translation.translation.Value = new SbVec3f(dataSample.ValueDim1, dataSample.ValueDim2, dataSample.ValueDim3);

      var sphere = new SoSphere();
      sphere.radius.Value = GetRadiusBasedOnWhetherSampleIsInsideProbe(...);
      sampleRoot.AddChild(sphere);

      this.OivNode.AddChild(sampleRoot);
    }
  }

  private SbVec3f GetColorByValue(double valueDim4)
  {
    // Look up color in a color table
  }
}

There are many scenarios that we might want to test here, but let's have a look on one specific scenario: the datapoint changes, and the scenegraph should change accordingly.

[Test]
public void OivNode_DatasetChanges_SceneGraphIsUpdated()
{
  // Arrange
  var dataset = new Dataset();
  dataset.DataSamples = new[]
  {
    new DataSample(),
    new DataSample()
  }; // Initial samples

  var scatterPlotView = new ScatterPlotView(dataset);

  // Act
  dataset.DataSamples = new[]
  {
    new DataSample(),
    new DataSample(),
    new DataSample()
  }; // Set 3 other samples

  // Assert
  Assert.AreEqual(3, scatterPlotView.OivNode.GetNumChildren());
}  

Here, we create a plot view with a dataset that has two samples. The dataset is then modified to have three samples, and the test verifies that the scenegraph changes accordingly. Note that we don't inspect the scenegraph in detail here. This test verifies that the scene graph is modified when the dataset changes and should assert on only that.

Other tests might traverse the scene graph and verify the position and color of each of the spheres in the scene graph. Just make sure that you don't overspecify the test. Don't write a test that will fail if the color scale changes slightly! In general you should test that the scene graph behaves correctly, rather than re-creating the logic in the scene graph construction.

User interaction testing

So far we have tested that the plot reacts to changes in the data. How about user interaction testing? This is actually similar to the previous test: make an action and assess the scene graph. The difference is how the action is performed: we need to mimic user interaction.

Again - know what you are testing! If you are using Open Inventor draggers, you don't need to emulate the mouse. That is not your responsibility -- it's Open Inventor's responsibility to transform mouse movements into dragger movements!

Let's write a test that verifies that the probe behaves correctly. The probe is represented with a SoTabBoxDragger which is added to the scene graph by the ScatterPlotView class. Here is one example of a test:

[Test]
public void OivNode_ProbeIsDragged_DataPointsOutsideBoxAreSmaller()
{
  // Arrange
  var dataset = new Dataset();
  dataset.DataSamples = new[]
  {
    new DataSample { ValueDim1 = 0.1 },
    new DataSample { ValueDim2 = 0.9 }
  };

  var scatterPlotView = new ScatterPlotView(dataset);

  // Act
  scatterPlotView.BoxDragger.translation.Value = new SbVec3f(0.5f, 0, 0);

  // Assert
  var sphereForSample1 = ...traverse the scene graph to find first sphere
  var sphereForSample2 = ...traverse the scene graph to find second sphere
  Assert.AreEqual(0.1, sphereForSample1.radius.Value);
  Assert.AreEqual(1.0, sphereForSample2.radius.Value);
}

Here we insert two points into the dataset. The dragger is moved so that in only contains one of the points, and the test inspects the scene graph to verify that the sphere sizes are correct.

If you write your own draggers instead of using Open Inventor's built-in draggers, you may need to emulate actual mouse coordinates. Still, you should make abstractions so that you can pass synthetic mouse events to the nodes rather than emulating actual mouse events.

Scene graph inspection

How do we verify that the scene graph is correct? One might create a very rigid test that verifies every node and node connection. That quickly leads to an overspecified test which reproduces the logic in the production code, however.

For Open Inventor, it's practical to use a SoSearchAction and inspect the resulting path(s). VTK has a similar mechanism for inspecting the pipeline. Just make sure that you don't copy the logic of the production code.

The scene graph related to the data samples in our plotter can be inspected like this:

var searchAction = new SoSearchAction();
searchAction.SetInterest(SoSearchAction.Interests.ALL);
searchAction.SetType(typeof(SoSphere));
searchAction.SetSearchingAll(true);
searchAction.Apply(scatterPlotView.OivNode);            

// Get all the paths that lead to a SoSphere:
var pathList = searchAction.GetPaths();

int pathCount = pathList.Count;

// We can use the path count to assert against the number of samples

foreach (SoPath path in pathList)
{
  var sphereRoot = path.GetNode(path.Length-2) as SoSeparator;
  bool hasTranslation = false;
  for (int i = 0; i < sphereRoot.GetNumChildren(); ++i)
  {
    if (sphereRoot.GetChild(i) is SoTranslation)
    {
      // We can assert that the sphere is positioned with
      // a translation. We can also check the actual position
      hasTranslation = true;
    }
  }       
}

In this example, we inspect the relevant part of the scene graph and verify that

• There are N paths leading to data point spheres, which should equal to N samples
• The sphere positions are determined by a SoTranslation. We could also check the actual position of the SoTranslation

This could be extended to verify that the correct material is assigned to the relevant spheres. The possibilities are endless, but consider splitting up the test so that each test is asserting on only one responsibility.

Inspection code like this makes a test hard to read, and should be put into helper methods. A test call would look like this:

var pathsLeadingToSphere = OivTestHelper.GetPaths(plotView.OivRoot, typeof(SoSphere));

Assert.AreEqual(3, pathsLeadingToSphere.Count);

Assert.IsTrue(OivTestHelper.PathContainsNode(pathsLeadingToSphere[0], typeof(SoTranslation));

Of course, you will usually not traverse the entire scene graph of a view at once. In complex views, you should divide the scene graph into smaller parts that can be tested individually.

Low-level visualization

For low-level visualization like ray tracing or fragment shaders where your code is actually responsible for doing the rendering, a test-first first approach is a bit harder. It's difficult to write a test that specifies what the result should be because you are producing a bitmap rather than a state.

The first step would be to ensure that you have a good separation between the low-level rendering code and the higher-level tier that is setting up states and handling user interaction, as the latter can be unit tested more easily.

I haven't found any practical approach to do proper TDD of low level visualization, but you can write regression tests that verify that the results are still correct after optimizations, generalizations and bug fixes. Given that the rendering code is able to render to a bitmap, you can do bitmap comparisons and compare future test sessions to a set of reference images.

Summary

Like I mentioned at the beginning of this post, unit testing 3D graphics is not trivial. The most important point is that you should test the state or the scene graph of the rendering engine and trust that the rendering engine does its job translating this into pixels. If you don't trust it, perhaps it's a good idea to use something else...

One might argue that this scene graph traversal and inspection introduces logic and complexity to the tests. This contradicts somewhat with what I have written in Pillars of Unit Tests. I try to mitigate this by creating helper methods for scene graph traversal. There is some logic involved, but this logic is hidden and doesn't obscure the readability of the tests. When you think about it, this is conceptually the same as calling NUnit's equality comparison for arrays or other non-trivial equality checks.

NCrunch - my favourite test runner

What is your favourite test runner? I have been using many different test runners over the years. Once in a while I find a better one and switch to that. Like I mentioned in my previous blog post Pillars of Unit Tests, one of the most important things when establishing a test environment is the ease of use. Running the tests should not be a hurdle.

NCrunch

I stumbled upon NCrunch some time ago, a .Net test runner for Visual Studio. This is represents a whole new paradigm when it comes to running tests. Actually the developer does not need to run the tests anymore -- NCrunch does it for you while typing. You don't even need to save the file!

While you edit the code, NCrunch uses coloured dots to the left of the code to indicate the test status of that particular line.

Hopefully your code usually looks like this, with happy green dots covering everything. That means your code is covered by passing tests. Production code is to the left and test code to the right:

All systems operational

Let's try to introduce a bug... just for the fun of it. Red dots appear at all lines in the production code that are covered by failing tests. Note the red x on one of the lines in the test. This is the offending line that makes the test fail.



What if we comment out some tests so that parts of the production code is no longer covered by tests? NCrunch marks the non-covered lines with black dots... and all bets are off!

Pretty impressing, and quite useful. You'll find it at http://www.ncrunch.net/.

By the way, I am not affiliated with the authors of NCrunch in any way. I'm just a happy user.

Pillars of unit tests

What is a good test? It may seem like a trivial question; a test should flash red if something is wrong and be green otherwise. But how do we achieve that? There are some pillars, or golden rules, that should always be honoured:

Trustworthyness

Simple. If you don't trust the tests, they are not worth anything. You should be able to trust that tests 

    A) fail when they should

    B) don't fail when they shouldn't.

If a tests all of a sudden turns red and the response is "well, that test fails once in a while. It's normal", the test is not trustworthy.

What can we do to make tests more trustworthy?

• Don't rely on things that can change in each test execution. Don't use timers or random numbers in tests. If this randomness causes failing tests from time to time, developers stop trusting them. A test that fails from time to time should be seen as an indication of an intermittent problem in the system under test, not a problem in the test.
• Don't make assumptions on or introduce dependencies to the environment. If the tests depend on the file system, the graphics card or the phase of the moon, the tests will become fragile and fail for the wrong reason.
• Don't overspecify the test. Have a clear vision of what the test is verifying. Don't add a bunch of asserts unless you have a very specific reason for adding them. Usually, each test should contain only one assert. Tests that are overspecified will often fail for reasons that are not related to the test itself. What happens then? Developers will stop trusting the tests!

Consider this test, which verifies that the tool class StringTools is creating the reverse of a string: 

    [Test]
    public void ReverseString_CalledWithString_ReturnsStringInReverse()
    {
      // Arrange
      string input = "abc";

      // Act
      string output = StringTools.ReverseString(input);

      // Assert
      Assert.AreEqual("cba", output);
      Assert.AreEqual(3, output.Length); // This is overspecification
    }

After verifying that the reversed string is returned, the length is also asserted upon. That's overspecification! The first assert is already doing a perfectly valid and sufficient verification. The second assert only makes the test more fragile and less maintainable because we can't change the length of the test string without also changing that assert. It adds complexity without yielding any value.

Maintainability

One of the most common pitfalls when doing TDD is test maintenance. As a system grows, it's easy to forget about the tests. As specifications change, it becomes hard to adapt the tests to the new requirements. Treat your test code with the same care as your production code!

Whenever you have finished a test, consider refactoring it. Consider whether the testee class becomes hard to test. Perhaps it's time to refactor both the test class and the testee class.

If each of the tests for a specific test class is doing multiple lines of setup, it might be a good idea to refactor this into helper methods.

As an example, consider these tests, where several methods in the "TesteeClass" class is being tested:

    [Test]
    public void SomeMethod_CalledWithNull_ReturnsFalse()
    {
      // Arrange
      var testeeObject = new TesteeClass();
      testeeObject.Initialize();
      testeeObject.SomeProperty = new SomeOtherClass();

      // Act
      bool result = testeeObject.SomeMethod();

      // Assert
      Assert.IsFalse(result);
    }

    [Test]
    public void SomeOtherMethod_Called_ReturnsTrue()
    {
      // Arrange
      var testeeObject = new TesteeClass();
      testeeObject.Initialize();
      testeeObject.SomeProperty = new SomeOtherClass();

      // Act
      bool result = testeeObject.SomeOtherMethod();

      // Assert
      Assert.IsTrue(result);
    }

You enhance readability and maintainability with some refactoring:

    [Test]
    public void SomeMethod_CalledWithNull_ReturnsFalse()
    {
      // Arrange
      var testeeObject = this.MakeTesteeObject();

      // Act
      bool result = testeeObject.SomeMethod();

      // Assert
      Assert.IsFalse(result);
    }

    [Test]
    public void SomeOtherMethod_Called_ReturnsTrue()
    {
      // Arrange
      var testeeObject = this.MakeTesteeObject();

      // Act
      bool result = testeeObject.SomeOtherMethod();

      // Assert
      Assert.IsTrue(result);
    }

    private TesteeClass MakeTesteeObject()
    {
      var testeeObject = new TesteeClass();
      testeeObject.Initialize();
      testeeObject.SomeProperty = new SomeOtherClass();

      return testeeObject;
    }

Readability

Your tests need to be readable. They are your code-level functional requirement document. If a test is hard to read, it's hard to maintain. It is also hard to figure out why it fails.

Pretend like an axe murderer is going to read your tests. He knows where you live, and he gets really mad if he can't understand your tests. You don't want to make him mad.

• Avoid using loops and logic. It should be obvious for the reader what the test does. If a test contains loops, if's, logic and other constructs, the reader needs to think in order to understand the test.

Production code vs test code.

• Use the smallest possible dataset. If you develop an algorithm, use the smallest possible dataset needed to verify the algorithm. This will make it easier to read the test, and execution will be faster.
• Avoid using magic numbers. If a test contains cryptic numbers, the axe murderer will wonder whether the number has a meaning. Use the lowest possible number so that it's obvious that the number is just an arbitrary input number.

Consider these two tests, one using magic numbers and one using the lowest possible number:

    [Test]
    public void AddNumbers_CalledWithTwoNumbers_ReturnsSum()
    {
      // Arrange
      double number1 = 54254; // Does this number have a meaning??
      double number2 = 64333;

      // Act
      double sum = Calculator.AddNumbers(number1, number2);

      // Assert
      Assert.AreEqual(118587, sum);
    }

    [Test]
    public void AddNumbers_CalledWithTwoNumbers_ReturnsSum()
    {
      // Arrange
      double number1 = 1; // It's obvious -- it's just an arbitray number
      double number2 = 2;

      // Act
      double sum = Calculator.AddNumbers(number1, number2);

      // Assert
      Assert.AreEqual(3, sum); // It's easier to understand the expected result
    }

Ease of use

Although this item does not pertain to the tests themselves, it is equally important. It should be easy to run tests. They should run fast. Once it becomes a hurdle to run the tests, developers will stop running then. It also becomes hard to get into the smooth test-driven flow where you develop test and production code in parallel.

Make sure that your tests run fast, and choose a test runner that allows you to run tests easily. Visual Studio has a decent test runner if you code .Net. If you use ReSharper, you have an even better test runner.

Happy TDD'ing!

Why do TDD?

So what is test-driven development all about? Why do TDD?

The short version is: TDD is the practice of writing tests before, or in parallel with, the production code. The developer will know immediately whether the code is working as expected without starting the application. Moreover, the tests are run automatically, developers will be alerted immediately if they do changes to the code that introduce defects.

Numerous articles are written about the benefits of TDD. To summarize, TDD gives a higher code quality if it's done right.

Benefits of TDD from a technical point of view

So what's in it for us developers? Let's have a look on some of the benefits of doing TDD.

Bugs are caught earlier

Has it ever happened to you that you have developed something, and someone else (or you) introduces bugs a year later? Perhaps some new functionality was added, or some optimizations were done, and all of a sudden your favourite algorithm failed?

Was it hard to figure out when this bug was introduced and hence hard to fix it? Perhaps the bug even found its way to the customer?

Well, you are not alone! That happens to us all. The good news are; the probability of discovering the bug immediately is much higher if the existing code is covered by tests!

You do rather want to let a test find the defect... ...than having an angry customer find it

Refactor with confidence

Refactor often, they say. Frequent refactoring yields a continuous improvement of architecture as the codebase increases. So how do you know that the refactoring does not introduce defects? By having automated tests, of course! If you can refactor with a lower likelyhood of creating defects, you can refactor more often.

Better architecture

Now that's a bold claim. How can tests enhance the architecture? Because doing TDD with a poor architecture is painful. Good tests and a proper TDD approach requires that the production code follows the SOLID principles. You may not have heard about the SOLID principles, but you do most likely use them. These principles include commonly accepted best practices like the Single Responsibility Principle (let your class do one thing only), decoupling and dependency injection. 

If you write the test first, you are forced to follow these principles. If it turns out that a class is not testable, it usually means that you are violating one or more of these principles. Then it's a good idea to do refactoring, or perhaps the class should be redesigned altogether.

Bottom line is - TDD is an efficient design tool because it encourages a clean and decoupled design. Complex code is hard to test and is a bad idea to begin with!

Where to start

So how do you get started with test-driven development? That's a too large topic to cover in this blog post, but I highly recommend getting a book. You will save yourself from countless hours of frustration if you get a fundamental understanding of writing tests instead of reading random articles on the web.

The Art of Unit Testing by Roy Osherove is a very good book. Make sure that you get the 2nd edition, as this is more updated on tools and methodology.

One last word: remember that test-driven development is not magic. It will not magically solve all your problems and make your codebase bug free tomorrow. It's a tool that, if used correctly, will help you create software with fewer defects, higher quality and better architecture.

TDD is software development done the scientific way. Good luck!

Welcome to TDD Addict

Welcome to by blog about test-driven development (TDD)!

I am a software engineer in Blueback Reservoir, a company specializing in providing consulting services and software solutions for the global oil & gas exploration and production industry.

One of my favourite topics within software development is automated software testing. Every so often we all stumble upon various challenges related to unit testing, and I will publish random thoughts on the topic here. I hope that I can help others with improving their TDD skills by sharing my experiences with you.

Happy TDD'ing!