dox parses code and comments of your test classes and publishes them as executable specification.
Comments, both inside the method body as well as doc comments of methods and classes, are interpreted as markdown and rendered as HTML. So you can create pleasant-to-read documentation (like this one) that still contains executable code which will be presented like this
$some = 1 + 2; $code = 'Hello'; $more = $code . 'World';
The code is executed when running the test suite so it can (and should) contain assertions
$this->assertEquals(3, $some); $this->assertEquals('HelloWorld', $more);
For more information see these specifications
or check out the source code of the file containing this documentation.
I write all of of my executable specification using methods whose names imitate the gherkin
syntax. To see examples check out the other specifications of this this project.
These methods start with either
then and use underscores as placeholders
for arguments to create sentences. For example
In order to make these methods more readable, they are parsed specially and presented in a structured way, filling the argument placeholders. The result looks like below. Hover over a step to see its code or check out the source code of this file.
If you would like to publish your project on
dox.rtens.org, drop me a line and I'll add it.
You can also host dox yourself.
To do so install dox on your host and the project to the configuration. The best way is to
configureProjects method in
$project = $this->configuration->addProject('example-name');
The default folder is in
user/projects/<projectName> but you can also overwrite it
$this->assertPathEndsWith('user/projects/example-name', $project->getFullProjectFolder()); $project->setFullProjectFolder('/some/absolute/path'); $this->assertPathEndsWith('/some/absolute/path', $project->getFullProjectFolder());
You can either download the files manually into the folder or provide the URL to a git repository to have it downloaded automatically.
You can send a test report to dox to have the status of each scenario displayed in color: passed, failed, pending, unknown.
For example for dox the commands would be
$ php vendor/phpunit/phpunit/phpunit.php --log-tap build/report.tap $ curl -X POST --data-binary @build/report.tap http://dox.rtens.org/projects/rtens-dox/reports
For more information see the specification.