Programming in D – Tutorial and Reference
Ali Çehreli

Other D Resources

Unit Testing

As it should be known by most people, any device that runs some piece of computer program contains software bugs. Software bugs plague computer devices from the simplest to the most complex. Debugging and fixing software bugs is among the less favorable daily activities of a programmer.

Causes of bugs

There are many reasons why software bugs occur. The following is an incomplete list roughly from the design stage of a program through the actual coding of it:

Unfortunately, there is still no software development methodology that ensures that a program will always work correctly. This is still a hot software engineering topic where promising solutions emerge every decade or so.

Discovering the bugs

Software bugs are discovered at various stages of the lifetime of the program by various types of tools and people. The following is a partial list of when a bug may be discovered, from the earliest to the latest:

Detecting bugs as early as possible reduces loss of money, time, and in some cases human lives. Additionally, identifying the causes of bugs that have been discovered by the end users are harder than identifying the causes of bugs that are discovered early, during development.

Unit testing for catching bugs

Since programs are written by programmers and D is a compiled language, the programmers and the compiler will always be there to discover bugs. Those two aside, the earliest and partly for that reason the most effective way of catching bugs is unit testing.

Unit testing is an indispensable part of modern programming. It is the most effective method of reducing coding errors. According to some development methodologies, code that is not guarded by unit tests is buggy code.

Unfortunately, the opposite is not true: Unit tests do not guarantee that the code is free of bugs. Although they are very effective, they can only reduce the risk of bugs.

Unit testing also enables refactoring the code (i.e. making improvements to it) with ease and confidence. Otherwise, it is common to accidentally break some of the existing functionality of a program when adding new features to it. Bugs of this type are called regressions. Without unit testing, regressions are sometimes discovered as late as during the QA testing of future releases, or worse, by the end users.

Risk of regressions discourage programmers from refactoring the code, sometimes preventing them from performing the simplest of improvements like correcting the name of a variable. This in turn causes code rot, a condition where the code becomes more and more unmaintainable. For example, although some lines of code would better be moved to a newly defined function in order to be called from more than one place, fear of regressions make programmers copy and paste the existing lines to other places instead, leading to the problem of code duplication.

Phrases like "if it isn't broken, don't fix it" are related to fear of regressions. Although they seem to be conveying wisdom, such guidelines cause the code to rot slowly and become an untouchable mess.

Modern programming rejects such "wisdom". To the contrary, to prevent it from becoming a source of bugs, the code is supposed to be "refactored mercilessly". The most powerful tool of this modern approach is unit testing.

Unit testing involves testing the smallest units of code independently. When units of code are tested independently, it is less likely that there are bugs in higher-level code that use those units. When the parts work correctly, it is more likely that the whole will work correctly as well.

Unit tests are provided as library solutions in other languages (e.g. JUnit, CppUnit, Unittest++, etc.) In D, unit testing is a core feature of the language. It is debatable whether a library solution or a language feature is better for unit testing. Because D does not provide some of the features that are commonly found in unit testing libraries, it may be worthwhile to consider library solutions as well.

The unit testing features of D are as simple as inserting assert checks into unittest blocks.

Activating the unit tests

Unit tests are not a part of the actual execution of the program. They should be activated only during program development when explicitly requested.

The dmd compiler switch that activates unit tests is ‑unittest.

Assuming that the program is written in a single source file named deneme.d, its unit tests can be activated by the following command: 

$ dmd deneme.d -w -unittest

When a program that is built by the ‑unittest switch is started, its unit test blocks are executed first. Only if all of the unit tests pass then the program execution continues with main().

unittest blocks

The lines of code that involve unit tests are written inside unittest blocks. These blocks do not have any significance for the program other than containing the unit tests: 

unittest {
    /* ... the tests and the code that support them ... */
}

Although unittest blocks can appear anywhere, it is convenient to define them right after the code that they test.

As an example, let's test a function that returns the ordinal form of the specified number as in "1st", "2nd", etc. A unittest block of this function can simply contain assert statements that compare the return values of the function to the expected values. The following function is being tested with the four distinct expected outcomes of the function: 

string ordinal(size_t number) {
    // ...
}

unittest {
    assert(ordinal(1) == "1st");
    assert(ordinal(2) == "2nd");
    assert(ordinal(3) == "3rd");
    assert(ordinal(10) == "10th");
}

The four tests above test that the function works correctly at least for the values of 1, 2, 3, and 10 by making four separate calls to the function and comparing the returned values to the expected ones.

Although unit tests are based on assert checks, unittest blocks can contain any D code. This allows for preparations before actually starting the tests or any other supporting code that the tests may need. For example, the following block first defines a variable to reduce code duplication: 

dstring toFront(dstring str, dchar letter) {
    // ...
}

unittest {
    immutable str = "hello"d;

    assert(toFront(str, 'h') == "hello");
    assert(toFront(str, 'o') == "ohell");
    assert(toFront(str, 'l') == "llheo");
}

The three assert checks above test that toFront() works according to its specification.

As these examples show, unit tests are also useful as examples of how particular functions should be called. Usually it is easy to get an idea on what a function does just by reading its unit tests.

Testing for exceptions

It is common to test some code for exception types that it should or should not throw under certain conditions. The std.exception module contains two functions that help with testing for exceptions:

For example, a function that requires that both of its slice parameters have equal lengths and that it works with empty slices can be tested as in the following tests: 

import std.exception;

int[] average(int[] a, int[] b) {
    // ...
}

unittest {
    /* Must throw for uneven slices */
    assertThrown(average([1], [1, 2]));

    /* Must not throw for empty slices */
    assertNotThrown(average([], []));
}

Normally, assertThrown ensures that some type of exception is thrown without regard to the actual type of that exception. When needed, it can test against a specific exception type as well. Likewise, assertNotThrown ensures that no exception is thrown whatsoever but it can be instructed to test that a specific exception type is not thrown. The specific exception types are specified as template parameters to these functions: 

    /* Must throw UnequalLengths for uneven slices */
    assertThrown!UnequalLengths(average([1], [1, 2]));

    /* Must not throw RangeError for empty slices (it may
     * throw other types of exceptions) */
    assertNotThrown!RangeError(average([], []));

We will see templates in a later chapter.

The main purpose of these functions is to make code more succinct and more readable. For example, the following assertThrown line is the equivalent of the lengthy code below it: 

    assertThrown(average([1], [1, 2]));

// ...

    /* The equivalent of the line above */
    {
        auto isThrown = false;

        try {
            average([1], [1, 2]);

        } catch (Exception exc) {
            isThrown = true;
        }

        assert(isThrown);
    }
Test driven development

Test driven development (TDD) is a software development methodology that prescribes writing unit tests before implementing functionality. In TDD, the focus is on unit testing. Coding is a secondary activity that makes the tests pass.

In accordance to TDD, the ordinal() function above can first be implemented intentionally incorrectly: 

import std.string;

string ordinal(size_t number) {
    return "";    // ← intentionally wrong
}

unittest {
    assert(ordinal(1) == "1st");
    assert(ordinal(2) == "2nd");
    assert(ordinal(3) == "3rd");
    assert(ordinal(10) == "10th");
}

void main() {
}

Although the function is obviously wrong, the next step would be to run the unit tests to see that the tests do indeed catch problems with the function: 

$ dmd deneme.d -w -unittest
$ ./deneme 
core.exception.AssertError@deneme(10): unittest failure

The function should be implemented only after seeing the failure, and only to make the tests pass. Here is just one implementation that passes the tests: 

import std.string;

string ordinal(size_t number) {
    string suffix;

    switch (number) {
    case  1: suffix = "st"; break;
    case  2: suffix = "nd"; break;
    case  3: suffix = "rd"; break;
    default: suffix = "th"; break;
    }

    return format("%s%s", number, suffix);
}

unittest {
    assert(ordinal(1) == "1st");
    assert(ordinal(2) == "2nd");
    assert(ordinal(3) == "3rd");
    assert(ordinal(10) == "10th");
}

void main() {
}

Since the implementation above does pass the unit tests, there is reason to trust that the ordinal() function is correct. Under the assurance that the tests bring, the implementation of the function can be changed in many ways with confidence.

Unit tests before bug fixes

Unit tests are not a panacea; there will always be bugs. If a bug is discovered when actually running the program, it can be seen as an indication that the unit tests have been incomplete. For that reason, it is better to first write a unit test that reproduces the bug and only then to fix the bug to pass the new test.

Let's have a look at the following function that returns the spelling of the ordinal form of a number specified as a dstring: 

import std.exception;
import std.string;

dstring ordinalSpelled(dstring number) {
    enforce(number.length, "number cannot be empty");

    dstring[dstring] exceptions = [
        "one": "first", "two" : "second", "three" : "third",
        "five" : "fifth", "eight": "eighth", "nine" : "ninth",
        "twelve" : "twelfth"
    ];

    dstring result;

    if (number in exceptions) {
        result = exceptions[number];

    } else {
        result = number ~ "th";
    }

    return result;
}

unittest {
    assert(ordinalSpelled("one") == "first");
    assert(ordinalSpelled("two") == "second");
    assert(ordinalSpelled("three") == "third");
    assert(ordinalSpelled("ten") == "tenth");
}

void main() {
}

The function takes care of exceptional spellings and even includes a unit test for that. Still, the function has a bug yet to be discovered: 

import std.stdio;

void main() {
    writefln("He came the %s in the race.",
             ordinalSpelled("twenty"));
}

The spelling error in the output of the program is due to a bug in ordinalSpelled(), which its unit tests fail to catch: 

He came the twentyth in the race.

Although it is easy to see that the function does not produce the correct spelling for numbers that end with the letter y, TDD prescribes that first a unit test must be written to reproduce the bug before actually fixing it: 

unittest {
// ...
    assert(ordinalSpelled("twenty") == "twentieth");
}

With that improvement to the tests, now the bug in the function is being caught during development: 

core.exception.AssertError@deneme(3274338): unittest failure

The function should be fixed only then: 

dstring ordinalSpelled(dstring number) {
// ...
    if (number in exceptions) {
        result = exceptions[number];

    } else {
        if (number[$-1] == 'y') {
            result = number[0..$-1] ~ "ieth";

        } else {
            result = number ~ "th";
        }
    }

    return result;
}
Exercise

Implement toFront() according to TDD. Start with the intentionally incomplete implementation below. Observe that the unit tests fail and provide an implementation that passes the tests. 

dstring toFront(dstring str, dchar letter) {
    dstring result;
    return result;
}

unittest {
    immutable str = "hello"d;

    assert(toFront(str, 'h') == "hello");
    assert(toFront(str, 'o') == "ohell");
    assert(toFront(str, 'l') == "llheo");
}

void main() {
}

... the solution