PHPackages texthtml/doctest - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)
1. [Directory](/)
2. /
3. [Testing & Quality](/categories/testing)
4. /
5. texthtml/doctest
ActiveProject[Testing & Quality](/categories/testing)
texthtml/doctest
================
Test code examples in PHP comments
v0.3.1(1y ago)91.0k1[1 PRs](https://github.com/texthtml/doctest/pulls)2AGPL-3.0-or-laterPHPPHP ^8.1CI passing
Since Jul 16Pushed 3mo ago1 watchersCompare
[ Source](https://github.com/texthtml/doctest)[ Packagist](https://packagist.org/packages/texthtml/doctest)[ RSS](/packages/texthtml-doctest/feed)WikiDiscussions main Synced 1mo ago
READMEChangelog (8)Dependencies (13)Versions (12)Used By (2)
doctest PHP
===========
[](#doctest-php)
Test your docblock code examples.
`doctest` looks for php examples in your functions, methods classes & interfaces comments and execute them to ensure they are correct.
How to write examples
=====================
[](#how-to-write-examples)
The simplest way is to add codeblocks in your comments, and use `assert()` to check for invariants. If, when executing the example there is an exception, the example will be marked as failed.
```
/**
* Compute the factorial of a non-negative $n
*
* ```php
* assert(factorial(0) === 1);
* assert(factorial(5) === 120);
* ```
*/
function factorial(int $n): int {
if ($n === 0) {
return 1;
}
if ($n < 0) {
throw new \InvalidArgumentException("unexpected negative integer: $n");
}
return $n * factorial($n - 1);
}
```
Assertions
----------
[](#assertions)
One easy way to throw exceptions when something is unexpected is to use [`assert()`](https://php.net/assert). But to make it nicer to write assertions and have better error messages automatically, you can call [the assertion helpers from webmozart/assert](https://packagist.org/packages/webmozart/assert#user-content-assertions)with the `self::assert*` shortcut:
```
self::assertEq(factorial(0), 1);
self::assertEq(factorial(5), 120);
```
### Testing exceptions
[](#testing-exceptions)
Sometimes we want to show that some code *will* throw an exception, we can do that by adding an inline comment anywhere in the example with the following format: `// @throws [exception class] [exception message]`
```
// @throws InvalidArgumentException unexpected negative integer: -10
factorial(-10);
```
Note: code after the exception won't be executed so any in-code assertions coming after the first exception won't be verified.
### Testing output
[](#testing-output)
By default `doctest` will make an example fail if it produce any output unless it's documented with one or more `@prints` inline comments anywhere in the example with the following format: `// @prints \[text\]. That's to make sure that any output produced is expected.
```
echo factorial(6); // @prints 720
echo factorial(10);
// the @prints annotations can be anywhere, only their order is important, not their exact positions
// @prints 3628800
```
Installation
============
[](#installation)
```
composer req --dev texthtml/doctest
```
Usage
=====
[](#usage)
Simply run the `doctest` command and it will look for examples to test in your `src/` folder. Call `doctest --help` for customizing where to look for examples and other options.
```
$ ./bin/doctest examples/factorial.php
[OK] factorial#1 (examples/factorial.php:7)
[OK] factorial#2 (examples/factorial.php:14)
[ERROR] factorial#3 (examples/factorial.php:20)
Expected output to be "". Got: "720"
[OK] factorial#4 (examples/factorial.php:25)
[ERROR] factorial#5 (examples/factorial.php:30)
unexpected negative integer: -10
[OK] factorial#6 (examples/factorial.php:35)
[ERROR] factorial#7 (examples/factorial.php:43)
Expected a value equal to 3628890. Got: 3628800
[OK] Number of success: 4
[ERROR] Number of failures: 3
```
TODO
====
[](#todo)
- Junit output
### Health Score
41
—
FairBetter than 89% of packages
Maintenance64
Regular maintenance activity
Popularity24
Limited adoption so far
Community15
Small or concentrated contributor base
Maturity53
Maturing project, gaining track record
Bus Factor1
Top contributor holds 57.1% of commits — single point of failure
How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.
**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.
**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.
**Maturity (30%)** — Project age, version count, PHP version support, and release stability.
### Release Activity
Cadence
Every ~134 days
Recently: every ~226 days
Total
8
Last Release
462d ago
### Community
Maintainers
[mathroc](/maintainers/mathroc)
---
Top Contributors
[](https://github.com/mathroc "mathroc (32 commits)")[![text-html-renovate[bot]](https://avatars.githubusercontent.com/u/6465918?v=4)](https://github.com/text-html-renovate[bot] "text-html-renovate[bot] (21 commits)")[![renovate[bot]](https://avatars.githubusercontent.com/in/2740?v=4)](https://github.com/renovate[bot] "renovate[bot] (3 commits)")
### Code Quality
TestsPHPUnit
Static AnalysisPHPStan
Code StylePHP\_CodeSniffer
Type Coverage Yes
### Embed Badge
```
[](https://phpackages.com/packages/texthtml-doctest)
```
### Alternatives
[infection/infection
Infection is a Mutation Testing framework for PHP. The mutation adequacy score can be used to measure the effectiveness of a test set in terms of its ability to detect faults.
2.2k26.2M1.8k](/packages/infection-infection)[behat/behat
Scenario-oriented BDD framework for PHP
4.0k96.8M2.0k](/packages/behat-behat)[sylius/sylius
E-Commerce platform for PHP, based on Symfony framework.
8.4k5.6M651](/packages/sylius-sylius)[vimeo/psalm
A static analysis tool for finding errors in PHP applications
5.8k77.5M6.7k](/packages/vimeo-psalm)[sulu/sulu
Core framework that implements the functionality of the Sulu content management system
1.3k1.3M152](/packages/sulu-sulu)[codeception/codeception
All-in-one PHP Testing Framework
4.9k86.2M2.9k](/packages/codeception-codeception)
PHPackages © 2026
[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)