Introduction

unittest2 is a library for writing unit tests for your Nim programs in the spirit of xUnit.

Features of unittest2 include:

• Beautiful and compact user experience adapted for both humans and CI
• Test separation with each test running in its own procedure
• Strict exception handling with support for exception tracking
• JUnit-compatible XML test reports for tooling integration
• Two-phase execution model as building block for advanced test scheduling and reporting features

unittest2 is an evolution of the unittest module in Nim - porting, while not trivial should at least be easy.

Installing

nimble install unittest2

or add a dependency in your .nimble file:

requires "unittest2"

Usage

See unittest2.html documentation generated by nim buildDocs.

Create a file that contains your unit tests:

import unittest2

suite "Suites can be used to group tests":
  test "A test":
    check: 1 + 1 == 2

Compile and run the unit tests:

nim c -r test.nim

The generated tests have a few command line options that can be viewed with --help:

nim c -r test.nim --help

See the tests for more examples!

Operation

unittest2 has two modes of operation: two-phase "collect-and-run" and single-pass "compatiblity".

The single-pass mode is currently default and broadly similar to how unittest works: suites and tests are run in the order they are encountered in the test files.

In "collect" mode a two-phase runner is used, first making a discovery pass to collect all tests then running them in a separate execution phase - this allows features such as test listing, progress indicators and in the future, smarter test scheduling strategies involving parallel and fully isolated execution.

The two-phase "collect" mode runs into a few notable incompatibilites with respect to the traditional unittest model:

• globals and code inside suite but not part of setup, test etc runs for all modules before tests are run
  • this change in execution order may result in test failures and odd performance quirks
• when re-running tests with filters, the globals end up being processed before filtering - this problem affects unittest also
• running with process isolation may lead to surprises such as resource conflicts (sockets, databases, files ..) and poor performance as both the "collection" process and the execution process ends up running the same global section of the code

Porting code to the two-phase mode includes:

• moving code in suite into setup, teardown and similar locations
• removing order-dependency from tests ensuring that each test can be run independently

The two-phase mode will at some point become the default execution model for unittest2 - it is enabled when the compatibility mode is turned off by passing -d:unittest2Compat=false to the compilation process.

Porting code from unittest

• Replace import unittest with import unittest2
• unittest2 places each test in a separate proc which changes the way templates inside tests are interpreted - some code changes may be necessary
• prepare the code for two-phase operation by reducing reliance on globals and test execution order

Testing unittest2

# this calls a task in "config.nims"
nim test

License

MIT

Credits

• original author: Zahary Karadjov

• initial fork author: Ștefan Talpalaru <stefantalpalaru@yahoo.com>

• current maintainer: Status R&D (https://status.im).

• homepage: https://github.com/status-im/nim-unittest2