Unit Tests

UnitTest:
    unittest FunctionBody

Unit tests are a series of test cases applied to a module to determine if it is working properly. Ideally, unit tests should be run every time a program is compiled.

Unit tests are a special function defined like:

unittest {
  ...test code...
}

There can be any number of unit test functions in a module, including within struct, union and class declarations. They are executed in lexical order. Stylistically, a unit test for a function should appear immediately following it.

A compiler switch, such as -unittest for dmd, will cause the unittest test code to be compiled and incorporated into the resulting executable. The unittest code gets run after static initialization is run and before the main() function is called.

Additionally, this switch enables the conditional version(unittest) statement, enabling your code to take a different path depending on whether you're compiling with unittests or not.

For example, given a class Sum that is used to add two values:

class Sum {
  int add(int x, int y) { return x + y; }

  unittest
  {
    Sum sum = new Sum;
    assert(sum.add(3,4) == 7);
    assert(sum.add(-2,0) == -2);
  }
}

Documented Unittests

Documented unittests allow the developer to deliver code examples to the user, while at the same time automatically verifying that the examples are valid. This avoids the frequent problem of having outdated documentation for some piece of code.

If a declaration is followed by a documented unittest, the code in the unittest will be inserted in the example section of the declaration:

/// Math class
class Math
{
    /// add function
    static int add(int x, int y) { return x + y; }

    ///
    unittest
    {
        assert(add(2, 2) == 4);
    }
}

///
unittest
{
    auto math = new Math();
    auto result = math.add(2, 2);
}

The above will generate the following documentation:

class Math;

Math class

Example:

auto math = new Math;
auto result = math.add(2, 2);

int add(int x, int y);

add function

Example:

assert(add(2, 2) == 4);

A unittest which is not documented, or is marked as private will not be used to generate code samples.

There can be multiple documented unittests and they can appear in any order. They will be attached to the last non-unittest declaration:

/// add function
int add(int x, int y) { return x + y; }


/// code sample generated
unittest
{
    assert(add(1, 1) == 2);
}

/// code sample not generated because the unittest is private
private unittest
{
    assert(add(2, 2) == 4);
}

unittest
{
    /// code sample not generated because the unittest isn't documented
    assert(add(3, 3) == 6);
}

/// code sample generated, even if it only includes comments (or is empty)
unittest
{
    /** assert(add(4, 4) == 8); */
}

The above will generate the following documentation:

int add(int x, int y);

add function

Examples:
code sample generated

assert(add(1, 1) == 2);

Examples:
code sample generated, even if it is empty or only includes comments

/** assert(add(4, 4) == 8); */

Versioning

The version identifier unittest is predefined if the compilation is done with unit tests enabled.