UnitTest:unittestBlockStatement
Unit tests are a builtin framework of test cases applied to a module to determine if it is working properly. A D program can be run with unit tests enabled or disabled.
Unit tests are a special function defined like:
unittest{ ...test code...}Individual tests are specified in the unit test usingAssertExpressions. UnlikeAssertExpressions used elsewhere, the assert is not assumed to hold, and upon assert failure the program is still in a defined state.
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.
Unit tests, when enabled, are run after all static initialization is complete and before themain() function is called.
For example, given a classSum that is used to add two values, a unit test can be given:
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); }}
When unit tests are enabled, theversion identifierunittest is predefined.
A unittest may be attributed with any of the global function attributes. Such unittests are useful in verifying the given attribute(s) on a template function:
void myFunc(T)(T[] data){if (data.length > 2) data[0] = data[1];}@safenothrowunittest{auto arr = [1,2,3]; myFunc(arr);assert(arr == [2,2,3]);}
This unittest verifies thatmyFunc contains only@safe,nothrow code. Although this can also be accomplished by attaching these attributes tomyFunc itself, that would preventmyFunc from being instantiated with typesT that have@system or throwing code in theiropAssign method, or other methods thatmyFunc may call. The above idiom allowsmyFunc to be instantiated with such types, yet at the same time verify that the@system and throwing behavior is not introduced by the code withinmyFunc itself.
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 theexample section of the declaration:
/// Math classclass Math{/// add functionstaticint 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:
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 functionint add(int x,int y) {return x + y; }/// code sample generatedunittest{assert(add(1, 1) == 2);}/// code sample not generated because the unittest is privateprivateunittest{assert(add(2, 2) == 4);}unittest{/// code sample not generated because the unittest isn't documentedassert(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:
(add(1, 1) == 2);