Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 36 ยท Tooling and Interop

Unit Tests and Contracts in D

Test D code with built-in unittest blocks and design by contract: assert, in and out contracts, class invariants, enforce, error versus exception, and a C test-runner stand-in.

D builds testing into the language. You do not need a framework to start: a unittest block placed next to the code runs automatically when you compile with -unittest (or dub test). Together with contracts (preconditions, postconditions and invariants), you get executable documentation of what code promises.

D code is read-only on this site. The C stand-ins implement a tiny test runner and contract macros so you can see the control flow and the failure reports.

unittest blocks

D
int clamp(int x, int lo, int hi)
{
    return x < lo ? lo : (x > hi ? hi : x);
}

unittest
{
    assert(clamp(5, 0, 10) == 5);
    assert(clamp(-3, 0, 10) == 0);
    assert(clamp(99, 0, 10) == 10);
}

With -unittest, the compiler includes every unittest block and runs them before main. A failed assert stops the program with a message such as core.exception.AssertError@source/app.d(9): Assertion failure. Without the flag the blocks are not compiled in at all, so tests cost nothing in production.

Good habits:

  • Put the test right after the function so it doubles as an example. Documentation comments /// combined with a /// unittest become the function's example in generated docs (a documented unittest).
  • Name blocks with a user attribute for readability, or with comments: @("clamp handles bounds") unittest { ... }.
  • Test errors too: assertThrown!Exception(parse("bad")) and assertNotThrown from std.exception.
  • Use dub test for the whole project and dub test -- --filter pattern with a test runner library such as unit-threaded for filtering and reports.

assert, enforce and Error versus Exception

Tool Meaning Stripped in -release?
assert(cond, msg) a programmer bug if false yes
enforce(cond, msg) a run-time condition (bad input, I/O failure) no
throw new Exception(...) recoverable problem the caller may handle no
Error (e.g. AssertError) unrecoverable bug; do not catch not applicable

Use assert for things that should never happen if the program is correct. Use enforce to validate input from outside, because it stays in release builds.

Contracts: in, out, invariant

A function can state what it requires and guarantees:

D
int integerSqrt(int n)
in (n >= 0, "negative input")
out (r; r * r <= n && (r + 1) * (r + 1) > n)
{
    int r = 0;
    while ((r + 1) * (r + 1) <= n) r++;
    return r;
}
  • in (condition, "message") is the precondition, checked on entry: the caller's duty.
  • out (r; condition) is the postcondition, checked on exit with the result named r: the function's duty.
  • -release removes both. Contract failures are bugs, not recoverable errors.

Classes and structs can add invariants that must hold whenever a public method is entered or leaves:

D
class Account
{
    private long cents;
    this(long c) { cents = c; }

    invariant { assert(cents >= 0); }

    void withdraw(long amount)
    in (amount > 0)
    {
        cents -= amount;       // invariant checked on exit: catches overdrafts
    }
}

Inheritance follows the Liskov rule automatically: an override may weaken preconditions and strengthen postconditions.

A test runner in C

The program below registers test functions, runs each, and reports pass or fail with the failing expression and line, like D's assert. A failure does not stop the other tests; D's built-in runner stops at the first failing unittest in a module, but libraries such as unit-threaded continue.

C Stand-in: tiny unit-test runner

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

The last test is wrong on purpose so you can read a failure report. Fix its expected value to 10 to see all four pass.

Contracts as macros

C has assert from <assert.h>. Two small macros give the in/out vocabulary:

C Stand-in: preconditions and postconditions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Coverage and other tools

dmd -cov or dub test --coverage writes .lst files marking each line with its execution count, so you can see untested branches. -profile finds slow functions, and -profile=gc finds allocations. For fuzzing, build with -fsanitize options on LDC.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. When do unittest blocks run?

    The compiler includes them with -unittest and runs them at startup.
  2. 2. Which should validate user input in a release build?

    assert, in, out and invariant disappear with -release; enforce stays.
  3. 3. Whose duty is a function's in contract?

    A precondition describes what callers must provide.
  4. 4. What does a class invariant check?

    Invariants are checked on entry and exit of public methods and after construction.

Summary

  • unittest blocks live beside the code and run with -unittest or dub test.
  • assert is for bugs and vanishes in -release; enforce is for run-time conditions.
  • in, out and invariant express design by contract.
  • Use -cov to find untested lines.

Next: Interoperating with C