Testing and Documentation

23.1 std/unittest

testament (the compiler's test runner) supports expected output, error specs, and categories.

Third-party options: balls, unittest2 (Status, faster and parallel), property testing with nim-quickcheck/fuzzy.

import std/unittest
import ../src/calc

suite "calculator":
  setup:
    let c = newCalc()
  teardown:
    discard

  test "addition":
    check c.add(2, 3) == 5

  test "division by zero raises":
    expect DivByZeroDefect:
      discard c.divide(1, 0)

  test "skipped on windows":
    when defined(windows): skip()
    check true

nim c -r tests/test_calc.nim
nimble test                 # runs tests/t*.nim

23.2 Documentation

runnableExamples blocks are compiled and run during nim doc, which keeps docs and tests in sync.

Doc comments use RST or Markdown (Nim 2 supports both).

## Module-level docs at the top of the file.

proc area*(r: float): float =
  ## Returns the area of a circle with radius `r`.
  ##
  ## .. code-block:: nim
  ##   echo area(2.0)
  runnableExamples:
    doAssert area(1.0) > 3.14
  PI * r * r

nim doc --project --index:on --outdir:htmldocs src/mylib.nim
nim doc --git.url:https://github.com/me/mylib src/mylib.nim
nimble doc