SimpleDocTestAdapter

Run and debug your C++ doctest test cases from the Visual Studio Test Explorer.

What it does

• Discovers the test cases of every doctest executable in your build output, grouped by source file (namespace level) and test suite (class level), with file and line so that a double click opens the source.
• Runs any selection, a few command lines per executable, and shows failed assertions, INFO/MESSAGE output and SUBCASE blocks with a clickable stack trace.
• Debugs a test case: a breakpoint in a CHECK is hit.
• Stays honest: a test executable that crashes or is killed leaves every affected test case failed with an explicit message, never silently dropped. Cancelling a run kills the executable.

How it works

The adapter never reads your sources or symbols. It runs the executable with --list-test-cases --reporters=xml --no-skip and trusts what doctest reports; running a selection is one more invocation with a --test-case filter and an xml report. An executable that does not mention doctest is never started.

Requirements

• Visual Studio 2022 or 2026 (Community, Professional or Enterprise), x64 or arm64.
• doctest 2.4.x or later: the xml reporter must be available (it is by default). Console applications; a windowed application needs an ExecutableOverride pointing at its console flavour.

Configuration

Everything is optional. A <SimpleDocTest> node of a .runsettings file offers CommandArguments, WorkingDirectory, ExecutableFilter, ExecutableOverrides, SubCaseSplitter, EnableDebugLogs, DiscoveryTimeoutSeconds and ExecutionTimeoutSeconds. See the reference.

<RunSettings>
  <SimpleDocTest>
    <CommandArguments>--test</CommandArguments>
    <ExecutableFilter>Tests\.exe$</ExecutableFilter>
  </SimpleDocTest>
</RunSettings>

Known limitations

• A test case name holding * or ? is selected with doctest's wildcard semantics: other test cases whose names match the pattern may run too (their results are ignored).
• Names outside the ANSI code page of the machine in an executable compiled without /utf-8 are reported the way MSVC compiled them (? for each character it could not encode).

Credits and licence

A clean rewrite of DoctestTestAdapter by Jase Mottershead, keeping its result rendering and its command line and encoding handling. MIT License. Source, issues and changelog: https://github.com/TheLapin34/SimpleDocTestAdapter.