Details

Version 0.5.1
Last updated 10th February 2006
Requirements
  • PHPUnit2
Links
Screenshots
Changelog
0.5.1
  • Fix to Formatter when trying to pick up original exception, provided by Glen Ogilvie.
  • Added comments to Formatter to document the functionality.
0.5.0
  • Initial version.

About

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.

Running multiple tests with PHPUnit2 HTML Runer

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’.

Example Usage

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.

Results

The results use a combination of colour coding, icons and plain text to enable easy identification of the results of the test(s).

Results display for multiple tests with PHPUnit2 HTML Runner

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:

Green
Test(s) were successful
Blue
Test(s) caused one or more errors
Red
Test(s) failed

Extended Detail

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.

Extended exception detail for failed test

Known Issues

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

Next Steps

Leave a Tip

If you find this code useful you can leave a donation towards the continued development & support.

Comments are disabled on this post.