By default Testament looks for test files on "./tests/*.nim". You can overwrite this pattern glob using pattern <glob>. The default working directory path can be changed using --directory:"folder/subfolder/".
Testament uses the nim compiler on PATH. You can change that using --nim:"folder/subfolder/nim". Running JavaScript tests with --targets:"js" requires a working NodeJS on PATH.
This is a minimal example to understand the basics, not very useful for production, but easy to understand:
$ mkdir tests $ echo "assert 42 == 42" > tests/test0.nim $ testament run test0.nim PASS: tests/test0.nim C ( 0.2 sec) $ testament r test0 PASS: tests/test0.nim C ( 0.2 sec)
$ testament pattern "tests/*.nim"
To search for tests deeper in a directory, use
$ testament pattern "tests/**/*.nim" # one level deeper $ testament pattern "tests/**/**/*.nim" # two levels deeper
Generate HTML Reports testresults.html from unittests, you have to run at least 1 test before generating a report:
$ testament html
Example "template" to edit and write a Testament unittest:
discard """ # What actions to expect completion on. # Options: # "compile": expect successful compilation # "run": expect successful compilation and execution # "reject": expect failed compilation. The "reject" action can catch # {.error.} pragmas but not {.fatal.} pragmas because # {.fatal.} pragmas guarantee that compilation will be aborted. action: "run" # The exit code that the test is expected to return. Typically, the default # value of 0 is fine. Note that if the test will be run by valgrind, then # the test will exit with either a code of 0 on success or 1 on failure. exitcode: 0 # Provide an `output` string to assert that the test prints to standard out # exatly the expected string. Provide an `outputsub` string to assert that # the string given here is a substring of the standard out output of the # test. output: "" outputsub: "" # Whether to sort the output lines before comparing them to the desired # output. sortoutput: true # Each line in the string given here appears in the same order in the # compiler output, but there may be more lines that appear before, after, or # in between them. nimout: ''' a very long, multi-line string''' # This is the Standard Input the test should take, if any. input: "" # Error message the test should print, if any. errormsg: "" # Can be run in batch mode, or not. batchable: true # Can be run Joined with other tests to run all togheter, or not. joinable: true # On Linux 64-bit machines, whether to use Valgrind to check for bad memory # accesses or memory leaks. On other architectures, the test will be run # as-is, without Valgrind. # Options: # true: run the test with Valgrind # false: run the without Valgrind # "leaks": run the test with Valgrind, but do not check for memory leaks valgrind: false # Can use Valgrind to check for memory leaks, or not (Linux 64Bit only). # Command the test should use to run. If left out or an empty string is # provided, the command is taken to be: # "nim $target --hints:on -d:testing --nimblePath:tests/deps $options $file" # You can use the $target, $options, and $file placeholders in your own # command, too. cmd: "nim c -r $file" # Maximum generated temporary intermediate code file size for the test. maxcodesize: 666 # Timeout seconds to run the test. Fractional values are supported. timeout: 1.5 # Targets to run the test into (c, cpp, objc, js). targets: "c js" # flags with which to run the test, delimited by `;` matrix: "; -d:release; -d:caseFoo -d:release" # Conditions that will skip this test. Use of multiple "disabled" clauses # is permitted. disabled: "bsd" # Can disable OSes... disabled: "win" disabled: "32bit" # ...or architectures disabled: "i386" disabled: "azure" # ...or pipeline runners disabled: true # ...or can disable the test entirely """ assert true assert 42 == 42, "Assert error message"
Expected to fail:
discard """ errormsg: "undeclared identifier: 'not_defined'" """ assert not_defined == "not_defined", "not_defined is not defined"
Non-Zero exit code:
discard """ exitcode: 1 """ quit "Non-Zero exit code", 1
Standard output checking:
discard """ output: ''' 0 1 2 3 4 5 ''' """ for i in 0..5: echo i
JavaScript tests:
discard """ targets: "js" """ when defined(js): import jsconsole console.log("My Frontend Project")
Compile-time tests:
discard """ action: "compile" """ static: assert 9 == 9, "Compile time assert"
Tests without Spec:
assert 1 == 1
See also: