Archer is a library for standardizing PHP unit testing, continuous integration, and documentation behavior across multiple projects using a convention-over-configuration approach. It brings together several high-quality libraries to help improve the quality of a project's test suite and reporting tools.
The use of Archer requires that the host project conforms to a set of conventions. In return, it provides the following benefits:
- Configuration-free, best-practice unit testing and test coverage reports with PHPUnit and Xdebug.
- Improved mock object support courtesy of Phake.
- Configuration-free generation of API documentation using Sami.
- Automated configuration of repository and Travis CI.
- Build artifact publication to project GitHub Pages.
- Configuration-free integration with Coveralls for excellent test coverage metrics.
- PHPUnit must be available in the user's PATH.
- Projects must use Composer.
- Projects must conform to the expected project layout.
- Projects must use a PHP namespace with a vendor and project prefix, for example
Icecave\Archer
. - The Xdebug PHP extension is required for test coverage reports.
- The openssl PHP extension is required for build artifact publication.
Archer expects projects to be laid out using the directory structure below:
. # Project / git root
├── src/ # PHP source files
└── test/
└── suite/ # PHPUnit test suite
Add icecave/archer to the project's composer.json
file as a
development dependency:
composer require icecave/archer:~1 --dev
This will create a new composer.json
file if it does not exist, and update all dependencies. The archer
executable should now be available at vendor/bin/archer
:
vendor/bin/archer --version
Set up the git repository and Travis CI configuration files using the update command.
vendor/bin/archer update --authorize
This command will prompt for a GitHub username and password in order to authorize Archer to publish build artifacts from Travis CI. For more information about security, please see the Security section of the Woodhouse documentation.
The changes made by Archer should now be committed to the repository, and pushed back to GitHub:
git add -A
git commit -m 'Adding Archer integration.'
git push
And that's it! The project is now set up to use Archer.
Archer provides a wrapper around PHPUnit for unit testing support. Arguments and options to this command are
passed on to PHPUnit. The test suite can be run by executing archer
with no parameters:
vendor/bin/archer
Running archer
with no arguments is equivalent to archer test
.
vendor/bin/archer test # canonical form
vendor/bin/archer # shortcut to 'test' (no arguments or options allowed)
vendor/bin/archer t # shortcut to 'test'
vendor/bin/archer t --stop-on-failure # arguments are forwarded to PHPUnit
$ vendor/bin/archer
Using PHP: /path/to/php
Using PHPUnit: /path/to/phpunit
PHPUnit 3.7.13 by Sebastian Bergmann.
Configuration read from /path/to/project/vendor/icecave/archer/res/phpunit/phpunit.xml
............................................................... 63 / 414 ( 15%)
............................................................... 126 / 414 ( 30%)
............................................................... 189 / 414 ( 45%)
............................................................... 252 / 414 ( 60%)
............................................................... 315 / 414 ( 76%)
............................................................... 378 / 414 ( 91%)
....................................
Time: 1 second, Memory: 14.00Mb
OK (414 tests, 915 assertions)
In addition to PHPUnit's test doubles, Archer includes Phake - an alternative mocking library - and handles the configuration necessary to integrate Phake and PHPUnit.
Phake's mocking system is easier to work with, requiring less setup and providing more flexibility than PHPUnit mocks. For this reason it is the recommended mocking system.
For some tests a test-double is not suitable and a fixture class needs to be used. For this reason, Archer will, at
test time only, autoload any classes that follow the PSR-0 standard from the test/src
directory, in
addition the classes normally loaded by Composer.
Test coverage reports provide a useful metric for determining how thoroughly a project is tested. The test coverage
report can be generated by executing archer coverage
. The HTML test coverage report will be generated in the
artifacts/tests/coverage
directory, which can be opened in any web browser.
vendor/bin/archer coverage # canonical form
vendor/bin/archer c # shortcut to 'coverage'
vendor/bin/archer c --stop-on-failure # passing arguments to PHPUnit
$ vendor/bin/archer c
Using PHP: /path/to/php
Using PHPUnit: /path/to/phpunit
PHPUnit 3.7.13 by Sebastian Bergmann.
Configuration read from /path/to/project/vendor/icecave/archer/res/phpunit/phpunit.coverage.xml
............................................................... 63 / 414 ( 15%)
............................................................... 126 / 414 ( 30%)
............................................................... 189 / 414 ( 45%)
............................................................... 252 / 414 ( 60%)
............................................................... 315 / 414 ( 76%)
............................................................... 378 / 414 ( 91%)
....................................
Time: 1 second, Memory: 17.00Mb
OK (414 tests, 915 assertions)
Generating code coverage report in HTML format ... done
For a live example see the test coverage report for Archer's own test suite.
Archer provides support for Coveralls. There is nothing to configure; simply enable Coveralls support for the project, and Archer will publish test coverage information to Coveralls when a build occurs on Travis CI.
API documentation provides a useful addition to any project's overall documentation strategy. Static, searchable API
documentation can be generated by executing archer documentation
. The API documentation will be generated in the
artifacts/documentation/api
directory, which can be opened in any web browser.
Note that the search panel of the API documentation uses AJAX, which browsers often disable for local files. For
example, Chrome must be started with the --allow-file-access
and --allow-file-access-from-files
switches in order
to support the search panel locally.
vendor/bin/archer documentation # canonical form
vendor/bin/archer d # shortcut to 'documentation'
For a live example see the API documentation for Pathogen.
Archer provides a command called update
to assist in keeping git repository and Travis CI configuration
consistent across multiple projects.
The generated configuration ensures that:
- Travis CI knows how to run the tests, build the coverage report, and publish build artifacts.
- Travis CI builds against all relevant versions of PHP.
- Travis CI builds are much less likely to fail because of GitHub API throttling.
- Test and build artifacts are ignored by Git.
- Archived versions of projects do not include development artifacts like the test suite.
vendor/bin/archer update # canonical form
vendor/bin/archer u # shortcut to 'update'
Wouldn't it be great if everyone could see that 100% test coverage report? Then it would be obvious how much care and effort went into producing a quality product. With Archer, this is as simple as authorizing a project.
To authorize a project, simply run the update
command with the --authorize
option. The command will prompt for a
GitHub username and password, and use these to create an encrypted configuration file used to publish artifacts from
Travis CI.
vendor/bin/archer update --authorize # canonical form
vendor/bin/archer u -a # shortcut to 'update --authorize'
Once the authorization has been set up, artifacts are published to the project's gh-pages
branch under a directory
named artifacts
whenever Travis builds the repository's default branch.
The directory structure is as follows:
artifacts/
├── images/ # Build status and coverage badges, organised by theme
└── tests/
└── coverage/ # Test coverage reports
Once published, a project's test coverage report is available through GitHub's Pages system. As an example, Archer's own coverage reports are published to http://icecavestudios.github.io/archer/artifacts/tests/coverage/.
Note that the above URL redirects to a custom domain, but it is still served through GitHub Pages.
To quickly convey information about the quality of a project it is often desirable to use 'badges' (or 'shields') that can easily be displayed in a project's README.md or other documentation, such as at the top of this document.
Although Coveralls provides dynamic badges to convey test coverage information, Archer automatically publishes a similar badge image when Coveralls is not enabled.