Skip to main content

Features

Key Features and Design Goals​

doctest was designed from the ground up to be as lightweight and non-intrusive as possible. These key characteristics should be preserved.

Transparent Independence:​

  • All test-related content can be removed from the binary executable by defining the DOCTEST_CONFIG_DISABLE identifier
  • Very small and easy to integrate - single-header
  • Extremely low compile-time footprint - approximately 25ms compile-time overhead for including the header in a file
  • Fastest possible assertion macros - 50k assertions can be compiled in 30 seconds (or even less than 10 seconds)
  • Does not pull in any headers when included (except in the translation unit that implements the library)
  • Everything is in the doctest namespace (implementation details are in the nested detail namespace)
  • All macros have prefixes - some macros also have unprefixed versions by default, but this is optional - see configuration
  • Zero warnings even with the most aggressive flags (on all tested compilers!!!)
    • -Weverything -pedantic for Clang
    • -Wall -Wextra -pedantic and >> over 35 << other warnings not covered by these flags for GCC - see here
    • /Wall for MSVC
  • Unrecognized command line options do not throw errors, and prefixes are supported for interoperability with client command line parsing
  • Options can be set programmatically and argc/argv passed from the command line do not have to be processed
  • Warnings themselves are not disabled

Extremely Portable​

Some of this content is outdated

  • Standard-compliant C++11 code - should work with any compiler with C++11 features (use tag 1.2.9 for C++98 and earlier compilers)
  • Tested with GCC: 4.8, 4.9, 5, 6, 7, 8, 9, 10, 11, 12
  • Tested with Clang: 3.5, 3.6, 3.7, 3.8, 3.9, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 (XCode 10+)
  • Tested with MSVC: 2015, 2017, 2019, 2022 (32-bit mode)
  • Tested on every commit with GitHub Actions
    • Warnings are treated as errors even at the most aggressive warning levels - see here
    • Static analysis on CI - Cppcheck / Clang-Tidy / Coverity Scan / OCLint / Visual Studio Analyzer
    • Output of all tests is compared against a previously known good reference run output
    • All tests built and run in Debug/Release modes
    • All tests run under valgrind on Linux (unfortunately not under OSX)
    • All tests run under address, UB, and thread sanitizers on Linux/OSX
    • Tests run in over 300 different configurations on UNIX (Linux + OSX) and Windows

Other Features​

  • Really easy to get started - it's just 1 header file - see tutorial
  • Very lightweight, unobtrusive, and portable - see sections above - and benchmarks
  • Provides a way to remove all test-related content from binaries using the DOCTEST_CONFIG_DISABLE macro
  • Automatic test registration - no need to manually add them to a collection
  • Subcases - an intuitive way to share common setup and teardown code for test cases (alternatives like test fixtures are also supported)
  • Templated test cases - parameterized by type
  • Support for logging macros to capture local variables and strings - as messages when assertions fail - with lazy stringification and minimal allocations wherever possible!
  • Crash handling support - using UNIX signals and Windows SEH
  • Thread-safe - assertions (and logging) can be used from multiple threads spawned by a single test case - example
  • Extensible reporter system (can also be used to implement event listeners)
  • Output is identical - byte for byte - across all compilers on all platforms
  • A binary (exe/dll) can use the test runner of another binary - so tests end up in a single registry - example
  • Support for BDD-style testing
  • A core assertion macro for comparisons - standard C++ operators are used for comparisons (less than, equal to, greater than...) - but the full expression is decomposed and the values of the left and right expressions are logged
  • Assertions can be used outside of a testing context - example
  • Assertion macros for exceptions - if something should or should not throw
  • Floating-point comparison support - see the Approx() helper
  • Powerful mechanism for stringification of user types - including exceptions!
  • Tests can be grouped in test suites
  • Test case decorators such as description / skip / may_fail / should_fail / expected_failures / timeout
  • Can be used without exceptions and RTTI - check out DOCTEST_CONFIG_NO_EXCEPTIONS
  • Powerful command line with many options
  • Can report the duration of test cases
  • Tests can be filtered by their name/file/test suite using wildcards
  • Subcases can be filtered using wildcards and by specifying the nesting level at which these filters should work
  • Failures can (optionally) break into the debugger on Windows and Mac
  • Integration with Visual Studio's output window for failed tests
  • A main() can be provided when implementing the library with the DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN identifier
  • Tests can be written in headers - they still get registered only once in the executable/shared object
  • Range-based execution of tests in the binary - see example python script
  • Extension headers for extra functionality that doesn't need to go into the main doctest.h header
  • Colored output in the console
  • Control over the order of test execution
  • Different doctest::Context instances can be created and run multiple times in a single execution of the program
  • Ability to query if code is currently running in a test - doctest::is_running_in_test
  • Tests can be registered in CTest with the use of doctest_discover_tests(<target>) from scripts/cmake/doctest.cmake

There is a list of planned features that are all important and large - see the roadmap.