|Last updated||10th February 2006|
I’ve recently begun to get into using Test Driven Development in almost everything I can at the moment. However having been spoilt slightly by CFCUnit and JSUnit with their HTML GUIs I found the text runner in PHPUnit2 to be lacking for my personal needs and taste.
After a bit of searching I could not find any existing HTML Runners for PHPUnit2. But along with an article on writing custom runners, some digging in the PHPUnit2 API and taking inspiration from the interface of CFCUnit I created the PHPUnit2 HTML Runner.
This is a simple GUI for PHPUnit2 and provides the following functionality:
- instant visual feedback for test(s)
- run multiple test cases and/or test suites at once
- extra information for test errors and failures
- history of recently performed tests
- execution time for each individual test (requires PEAR Benchmark package)
Installation & Usage
Download the zip file and unzip to a web browsable directory on your machine (such as ‘HTMLRunner’) and browse to the directory (e.g. http://localhost/HTMLRunner/index.php).
You will be presented with the homepage which contains the form for entering the tests to run and some basic instructions.
Test cases and suites are defined by providing the path and name of the file (without the .php extension), with each test on a new line. The runner will assume the name of the file is also the name of the test case/suite to run, e.g. ‘util/HistoryTest’ will contain a test case class of ‘HistoryTest’.
util/HistoryTest fake/fake_pathTest test/PHPUnit2/Tests/OneTestCase
In this example the util/HistoryTest.php and fake/fake_pathTest.php test cases which are part of the HTML Runner will be run along with the PHPUnit2 test test/PHPUnit2/Tests/OneTestCase.php which is installed in the PEAR/test directory with the standard PHPUnit2 installation. Note that the util/HistoryTest test case requires that the util directory is writable to run.
The results use a combination of colour coding, icons and plain text to enable easy identification of the results of the test(s).
Firstly an overall status of all the tests performed is displayed in plain text along with the total tests performed, tests with errors and tests that failed. This overall status message is re-enforced by use of a coloured bullet point (see below).
Each individual test case is then presented with an overall status for that test using a coloured bullet point, plain text of the status and numbers for total tests performed, errors and failures. Each test is then presented with its name, execution time (if PEAR Benchmark package is present), test status – represented by icon and plain text – and any assertation messages.
The coloured bullet points, used for the overall status of all the tests and the individual test cases, are as follows:
- Test(s) were successful
- Test(s) caused one or more errors
- Test(s) failed
For each test that failed extended detail is included, which is linked from the assertation message in the test results for quick navigation to the extended detail.
The extended detail is separated out into a section for each individual test case and then each test failure contains:
- test name
- line of test within the test case
- assertation function used in test
- assertation message
- original caught exception message
This is intended to aid in the debugging of test failures and this extra detail has proved quite useful to myself so far and is very similar to the experience that CFCUnit provides me.
Please note the following quirks of the current version of the PHPUnit2 HTML Runner:
- If any of the paths or filenames provided do not point to a test case/suit file that can be included by PHP no attempt to run those test cases will be made, furthermore no details of un-included test cases will not currently be provided in the results.
- Unlike the text runner provided with PHPUnit2 the HTML Runner will not attempt to validate the syntax of a test file or related files. This is an intended feature as it is currently only really viable to check whether file is syntaxually valid PHP or not, whereas I would prefer to know the exact errors. This means that any errors/exceptions which are un-caught will be output to screen and may cause the runner to fail. I would recommend enabling display_errors and setting the reporting level to E_ALL for the runner.
- When tests are in a seperate folder to the class definition they are testing the test will fail if the class definition being tested has any relative includes/requires within it. Reported 2006-03-01 by Glen Ogilvie