README

DocTest

A PHP documentation testing tool that validates code examples in your markdown files. Write documentation with confidence — if it compiles and runs, it stays correct.

Why?

Code examples in documentation rot. APIs change, methods get renamed, return types evolve — but the docs stay frozen. DocTest extracts PHP code blocks from your markdown files, executes them in isolated processes, and verifies their output. If an example breaks, you'll know immediately.

• Tested documentation — code examples are verified on every CI run
• Invisible assertions — HTML comments keep assertions hidden from rendered docs
• Shiki compatible — handles // [!code hide], diff markers, highlights, and all Shiki annotations
• Process isolation — each example runs in its own process, no side effects
• Zero setup — run vendor/bin/doctest and it just works

Installation

composer require --dev testflowlabs/doctest

Quick Start

Write a PHP code block in any markdown file with an assertion in an HTML comment:

```php
echo 'Hello, World!';
```
<!-- doctest: Hello, World! -->

Run it:

vendor/bin/doctest

DocTest scans docs/ and README.md by default. That's it.

What Can It Do?

DocTest supports six assertion types, wildcards for dynamic output, code block attributes (ignore, no_run, throws, parse_error, setup, teardown), grouped examples with shared state, a bootstrap config for loading your project's autoloader, and bootstrap profiles for per-block environments via the .doctest/ directory. A few examples:

echo 2 + 3;

$prices = [10.5, 20.0, 30.75];
$total = array_sum($prices); // => 61.25

echo json_encode(['tool' => 'DocTest']);

For the full feature set — assertions, attributes, wildcards, groups, configuration, CLI options, CI integration, and framework bootstrap — see the Documentation.

Requirements

• PHP 8.4+

License

MIT