# doctest/doctest

**Attribution required: if you use, quote, or summarise this content, you must credit and link back to [awesome-repositories.com](https://awesome-repositories.com/repository/doctest-doctest).**

6,765 stars · 691 forks · C++ · MIT

## Links

- GitHub: https://github.com/doctest/doctest
- Homepage: https://bit.ly/doctest-docs
- awesome-repositories: https://awesome-repositories.com/repository/doctest-doctest.md

## Topics

`c-plus-plus` `cpp` `cpp11` `cpp14` `cpp17` `cpp20` `cpp23` `doctest` `header-only` `single-file` `tdd` `testing` `testing-framework` `unit-testing`

## Description

doctest is a lightweight C++ unit testing framework and assertion library. It provides a single-header implementation that eliminates complex build dependencies, allowing developers to write and execute test cases directly within their source code.

The framework is distinguished by its focus on compile-time performance and binary overhead. It uses conditional compilation guards to strip all testing logic and metadata from production binaries. Additionally, it features hierarchical subcases that re-execute parent setup code to isolate different execution paths within a single test case.

Its capability surface includes a thread-safe test runner with support for parameterized tests, test suites, and custom reporters. It provides specialized tools for validating expressions, comparing floating point values, and verifying exception behavior. The system also integrates with build tools such as CMake and Bazel.

The entire framework is provided as a single-header library to simplify integration.

## Tags

### Software Engineering & Architecture

- [Single-File Framework Distributions](https://awesome-repositories.com/f/software-engineering-architecture/single-file-framework-distributions.md) — Distributed as a single-header library to eliminate complex build dependencies and simplify project integration.
- [Hierarchical Subcases](https://awesome-repositories.com/f/software-engineering-architecture/test-execution-wrapping/hierarchical-subcases.md) — Implements hierarchical subcases that re-execute parent setup code to isolate different execution paths within a single test.
- [Binary Test Stripping](https://awesome-repositories.com/f/software-engineering-architecture/binary-test-stripping.md) — Strips all testing logic and metadata from production binaries using conditional compilation guards to eliminate overhead. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/configuration.md))
- [Conditional Compilation Utilities](https://awesome-repositories.com/f/software-engineering-architecture/conditional-compilation-utilities.md) — Uses preprocessor macros to toggle the inclusion of testing logic and metadata during the build process.
- [Exception Support Configurations](https://awesome-repositories.com/f/software-engineering-architecture/error-handling/exception-logic-structures/exception-handling-strategies/exception-handling-policies/exception-support-configurations.md) — Supports environments where exceptions are disabled by allowing the removal of try-catch blocks and the exception system. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/configuration.md))
- [Exception Verification](https://awesome-repositories.com/f/software-engineering-architecture/error-handling/exception-logic-structures/exception-handling-strategies/exception-verification.md) — Verifies that specific code paths throw expected exception types or contain specific error messages. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/assertions.md))
- [Thread-Safe Registries](https://awesome-repositories.com/f/software-engineering-architecture/thread-safe-logging/thread-safe-assertion-recording/thread-safe-registries.md) — Uses atomic operations and mutexes to allow safe test registration and execution across concurrent threads.

### Testing & Quality Assurance

- [Unit Testing Frameworks](https://awesome-repositories.com/f/testing-quality-assurance/unit-testing-frameworks.md) — Provides a fast, thread-safe runner to execute automated unit tests and verify code correctness. ([source](https://github.com/doctest/doctest/blob/master/README.md))
- [Assertion Libraries](https://awesome-repositories.com/f/testing-quality-assurance/assertion-libraries.md) — Ships a set of thread-safe macros for validating boolean expressions and capturing variable states during runtime failures.
- [Expression Decomposition](https://awesome-repositories.com/f/testing-quality-assurance/expression-decomposition.md) — Evaluates boolean expressions and prints expanded variable values upon failure to simplify debugging. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/assertions.md))
- [Test Grouping Utilities](https://awesome-repositories.com/f/testing-quality-assurance/general-testing-utilities/test-utilities-assertions/test-lifecycle-execution-control/test-grouping-utilities.md) — Provides nested subcases to group related assertions and share setup code within a single test case. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/testcases.md))
- [Expression Decomposition](https://awesome-repositories.com/f/testing-quality-assurance/software-testing/testing-frameworks/test-frameworks/assertions-and-validation/assertion-validation-utilities/expression-decomposition.md) — Evaluates boolean expressions and automatically prints the expanded values of variables upon failure to simplify debugging. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/features.md))
- [Test Case Definitions](https://awesome-repositories.com/f/testing-quality-assurance/software-testing/testing-frameworks/test-frameworks/assertions-and-validation/test-case-definitions.md) — Supports creating named units of execution using standard or BDD-style scenario syntax. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/testcases.md))
- [Test Execution Runners](https://awesome-repositories.com/f/testing-quality-assurance/software-testing/testing-frameworks/test-frameworks/execution-and-infrastructure/test-execution-runners.md) — Provides a thread-safe execution engine for filtering, running, and reporting the results of test suites.
- [Test Discovery Mechanisms](https://awesome-repositories.com/f/testing-quality-assurance/test-discovery-mechanisms.md) — Automatically identifies and registers test cases using static initialization, removing the need for manual test lists.
- [Test Execution Filtering](https://awesome-repositories.com/f/testing-quality-assurance/test-execution-filtering.md) — Includes a powerful filtering system to select specific test cases or suites using wildcard patterns. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/commandline.md))
- [Hierarchical Suite Grouping](https://awesome-repositories.com/f/testing-quality-assurance/test-suite-architectures/hierarchical-suite-grouping.md) — Implements hierarchical subcases that re-execute parent setup code for granular shared state management. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/tutorial.md))
- [Automatic Test Discovery](https://awesome-repositories.com/f/testing-quality-assurance/testing-infrastructure-management/test-execution-management/test-registries/automatic-test-discovery.md) — Automatically collects and tracks test cases using static initialization to eliminate manual registration lists. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/features.md))
- [Nested Setup Nodes](https://awesome-repositories.com/f/testing-quality-assurance/testing-infrastructure-management/test-orchestration/test-setup-orchestrators/nested-setup-nodes.md) — Implements hierarchical subcases that re-execute parent setup code to isolate different execution paths. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/features.md))
- [Compilation Performance Optimizations](https://awesome-repositories.com/f/testing-quality-assurance/assertion-macros/compilation-performance-optimizations.md) — Reduces compile times by converting complex assertion macros into single function calls. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/configuration.md))
- [Concurrent Assertion Validation](https://awesome-repositories.com/f/testing-quality-assurance/concurrent-assertion-validation.md) — Allows assertion and logging macros to be called safely from multiple threads to verify concurrent behavior. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/faq.md))
- [Concurrent Software Testing](https://awesome-repositories.com/f/testing-quality-assurance/concurrent-software-testing.md) — Provides a thread-safe environment for verifying concurrent behavior in C++ software.
- [Test Execution Overrides](https://awesome-repositories.com/f/testing-quality-assurance/general-testing-utilities/test-configuration/test-execution-overrides.md) — Allows configuring test execution options, such as failure limits and filters, via code or command-line. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/main.md))
- [Custom Failure Messaging](https://awesome-repositories.com/f/testing-quality-assurance/general-testing-utilities/test-failure-debugging-tools/failure-verification-tools/custom-failure-messaging.md) — Provides detailed diagnostic messages by capturing local variables and strings during assertion failures. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/features.md))
- [Test Reporters](https://awesome-repositories.com/f/testing-quality-assurance/general-testing-utilities/test-reporters.md) — Implements an extensible reporter system and event listeners to format and deliver test outcomes. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/features.md))
- [Result Formatters](https://awesome-repositories.com/f/testing-quality-assurance/general-testing-utilities/test-reporters/external-result-reporters/tap-result-exporters/result-formatters.md) — Enables exporting test results into various formats, including console text and XML, for external analysis. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/reporters.md))
- [Test Result Reporters](https://awesome-repositories.com/f/testing-quality-assurance/general-testing-utilities/test-reporters/test-result-reporters.md) — Provides a pluggable event listener model to format and route test results to various output sinks.
- [Test Execution Controls](https://awesome-repositories.com/f/testing-quality-assurance/general-testing-utilities/test-utilities-assertions/test-lifecycle-execution-control/test-execution-controls.md) — Provides control over test flow by distinguishing between non-fatal assertions and fatal requirements. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/tutorial.md))
- [Test Parameterization](https://awesome-repositories.com/f/testing-quality-assurance/general-testing-utilities/test-utilities-assertions/test-lifecycle-execution-control/test-parameterization.md) — Enables executing the same test logic multiple times using different types or generated sets of values. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/features.md))
- [Type-Parameterized Tests](https://awesome-repositories.com/f/testing-quality-assurance/general-testing-utilities/test-utilities-assertions/test-lifecycle-execution-control/test-parameterization/type-parameterized-tests.md) — Allows executing the same test logic across different data types to verify multiple implementations satisfy a common interface. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/parameterized-tests.md))
- [Parallel Test Execution](https://awesome-repositories.com/f/testing-quality-assurance/parallel-test-execution.md) — Supports executing test cases and assertions across multiple threads for verifying multi-threaded behavior. ([source](https://github.com/doctest/doctest/blob/master/examples/all_features/concurrency.cpp))
- [Expression Decomposition](https://awesome-repositories.com/f/testing-quality-assurance/software-testing/testing-frameworks/test-frameworks/assertions-and-validation/assertion-validation-utilities/assertion-libraries/execution-assertions/assertion-failure-handlers/expression-decomposition.md) — Decomposes assertions into string representations only upon failure to improve performance and provide detailed diagnostics.
- [Test Metadata](https://awesome-repositories.com/f/testing-quality-assurance/software-testing/testing-frameworks/test-frameworks/assertions-and-validation/test-case-definitions/test-metadata.md) — Allows attaching metadata to tests to control execution timeouts, expected failure counts, or skip status. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/features.md))
- [Embedded Test Runners](https://awesome-repositories.com/f/testing-quality-assurance/software-testing/testing-frameworks/test-frameworks/execution-and-infrastructure/test-execution-runners/embedded-test-runners.md) — Allows integrating a test runner within a functional application to execute tests alongside production logic. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/main.md))
- [Test Fixture Systems](https://awesome-repositories.com/f/testing-quality-assurance/software-testing/testing-frameworks/test-frameworks/execution-and-infrastructure/test-infrastructure-configuration/test-fixture-systems.md) — Implements fixture systems using classes or structures to share member variables and methods across multiple tests. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/testcases.md))
- [Cross-Binary Registry Sharing](https://awesome-repositories.com/f/testing-quality-assurance/testing-infrastructure-management/test-execution-management/test-registries/cross-binary-registry-sharing.md) — Enables multiple binaries to contribute to a single test summary by sharing the test registry via a shared library. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/main.md))
- [Test Suite Organization](https://awesome-repositories.com/f/testing-quality-assurance/unit-testing-frameworks/test-suite-organization.md) — Provides mechanisms to organize test cases into named suites for bulk execution and command-line filtering. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/features.md))

### Development Tools & Productivity

- [Testing Logic Stripping](https://awesome-repositories.com/f/development-tools-productivity/build-time-code-stripping/testing-logic-stripping.md) — Allows stripping all testing logic and metadata from production binaries via configuration flags. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/features.md))
- [Header-Only Libraries](https://awesome-repositories.com/f/development-tools-productivity/header-only-libraries.md) — Supplies a single-header implementation to eliminate complex build dependencies and simplify project integration.
- [Build System Integration](https://awesome-repositories.com/f/development-tools-productivity/build-system-integration.md) — Integrates test execution and discovery into build systems like CMake and Bazel to automate verification.
- [Command Line Configuration](https://awesome-repositories.com/f/development-tools-productivity/command-line-configuration.md) — Allows the configuration of test execution options and behavior via command-line flags or code overrides. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/commandline.md))
- [Test Logging Utilities](https://awesome-repositories.com/f/development-tools-productivity/debugging-profiling-testing/test-execution-management/test-logging-utilities.md) — Captures expressions lazily and prints them only upon subsequent assertion failure to provide diagnostic context. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/logging.md))
- [Test Integration](https://awesome-repositories.com/f/development-tools-productivity/header-only-libraries/test-integration.md) — Enables test cases to be embedded within header files using conditional guards to minimize compilation overhead. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/faq.md))

### Programming Languages & Runtimes

- [Compile-Time Optimization](https://awesome-repositories.com/f/programming-languages-runtimes/compile-time-optimization.md) — Minimizes compilation overhead and binary size by streamlining expression decomposition and stripping metadata.
- [Compilation Speed Optimizations](https://awesome-repositories.com/f/programming-languages-runtimes/compiler-interpreter-internals/compiler-infrastructure/compiler-optimizations/compilation-speed-optimizations.md) — Decreases compilation overhead by utilizing streamlined machinery that avoids complex expression decomposition. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/faq.md))
- [Exception-Free Configurations](https://awesome-repositories.com/f/programming-languages-runtimes/runtime-exception-handling/exception-free-configurations.md) — Operate without using exceptions to meet strict environment constraints or performance requirements. ([source](https://github.com/doctest/doctest/blob/master/doc/markdown/faq.md))

### Part of an Awesome List

- [Thread-Safe Assertions](https://awesome-repositories.com/f/awesome-lists/devops/concurrency-threading/thread-safe-assertions.md) — Provides a thread-safe assertion library for verifying runtime logic outside of standard test cases. ([source](https://github.com/doctest/doctest/blob/master/README.md))
- [Developer Tools](https://awesome-repositories.com/f/awesome-lists/devtools/developer-tools.md) — Fast, feature-rich testing framework