Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Command-Line Options

unittest2 supports runtime options via command-line arguments and environment variables. Command-line options take precedence.

Core Flags

  • --help: Print usage and exit.
  • --xml:<file> or --xml=<file>: Write a JUnit-compatible XML report using JUnitOutputFormatter.
  • --console: Force console output formatter (ConsoleOutputFormatter).
  • --output-level:<level> or --output-level=<level>: Set the OutputLevel. One of VERBOSE, COMPACT, FAILURES, NONE.
  • --verbose or -v: Shortcut for --output-level=VERBOSE.

Environment Variables

You can configure unittest2 using environment variables. To maintain compatibility with the built-in unittest module, both UNITTEST2_ and NIMTEST_ prefixes are supported.

VariableValuesDescription
UNITTEST2_OUTPUT_LVLVERBOSE, COMPACT, FAILURES, NONESets the default output verbosity.
UNITTEST2_ABORT_ON_ERROR(any)If defined, stops the test run immediately after the first failure.
NIMTEST_COLORalways, neverExplicitly enables or disables colored output.
NIMTEST_NO_COLOR(any)If defined, disables colored output (unless NIMTEST_COLOR is set to always).

Compatibility Fallbacks

For seamless integration with existing tools and CI pipelines, unittest2 also recognizes these standard Nim testing variables:

  • NIMTEST_OUTPUT_LVL: Fallback for UNITTEST2_OUTPUT_LVL. Recognizes PRINT_ALL (VERBOSE), PRINT_FAILURES (FAILURES), and PRINT_NONE (NONE).
  • NIMTEST_ABORT_ON_ERROR: Fallback for UNITTEST2_ABORT_ON_ERROR.

Parameter Parsing Behavior

By default, unittest2 parses the current process arguments automatically.

To disable this behavior (e.g., if your application needs to handle its own arguments):

nim c -d:unittest2DisableParamFiltering=true -r test.nim -- --your-app-args

Then you can call parseParameters manually in your test harness if you still want unittest2 to process some of the arguments.