PEPr - PEAR_TestListener (RFC)

Table of contents
  1. Introduction
  2. Overview
  3. Installing
  4. Setting up
  5. Credits
  6. Classes Source Code
  7. Examples
  8. ChangeLog

1. Introduction

In waiting future version 3.4.0 of PHPUnit that will allow to define our own listeners into the phpunit.xml XML configuration file, we have no way until now, to run a test suite and log results as we want.

Only standard logging solutions provided with PHPUnit 3.3.x are : 

PHPUnit 3.3.16 by Sebastian Bergmann.

Usage: phpunit [switches] UnitTest [UnitTest.php]
       phpunit [switches] <directory>

  --log-graphviz <file>    Log test execution in GraphViz markup.
  --log-json <file>        Log test execution in JSON format.
  --log-tap <file>         Log test execution in TAP format to file.
  --log-xml <file>         Log test execution in XML format to file.

  --test-db-dsn <dsn>      DSN for the test database.
  --test-db-log-rev <rev>  Revision information for database logging.
  --test-db-prefix ...     Prefix that should be stripped from filenames.
  --test-db-log-info ...   Additional information for database logging.

Of course there is a solution, not simple, that will change the contents of main function available in almost all PEAR packages tests suites.

Lets have a look on basic main function implementation with PEAR::XML_Util package.

Code below shows a cut-down version of original XML_Util/tests/AllTests.php (1.2.1)

PHP code
  1. <?php
  2. class XML_Util_AllTests
  3. {
  4.     public static function main()
  5.     {
  6.         PHPUnit_TextUI_TestRunner::run(self::suite());
  7.     }
  8.  
  9.     public static function suite()
  10.     {
  11.         $suite = new PHPUnit_Framework_TestSuite(
  12.             'XML_Util Full Suite of Unit Tests');
  13.  
  14.         $phpt = new PHPUnit_Extensions_PhptTestSuite(XML_UTIL_DIR_PHPT);
  15.         $suite->addTestSuite($phpt);
  16.  
  17.         return $suite;
  18.     }
  19. }
  20. ?>
generated by Generic Syntax Highlighter - GeSHi

PHPUnit_TextUI_TestRunner::run accept two parameters, where second ($arguments) is optional. You can then give values like a list of listeners attached to the test suite to be notifed and lot more. But you have to add lot of code to do it.

As we will see in next chapter, PEAR_TestListener, allow of course to do this kind of behavior, but add much more.

2. Overview

PEAR_TestListener provides :

3. Installing

Using PEAR installer, it's very easy. Just have to run this command : 

pear install http://pear.laurent-laville.org/get/PEAR_TestListener-0.3.0b2.tgz

Install by hand :

  1. Get the release archive at http://pear.laurent-laville.org/get/PEAR_TestListener-0.3.0b2.tgz
  2. Extract it to a temporary folder
  3. Copy files PEAR/TestListener.php and PEAR/TestRunner.php into a directory that is listed in the include_path of your php.ini

4. Setting up

If you have test suites organized as PEAR::XML_Util (see in Introduction chapter). In most case it's true with PEAR packages that have PHPUnit 3 compatible test suites.

You have only to change the highlighted yellow line PHPUnit_TextUI_TestRunner::run(self::suite()); in main function, by these two lines. No more no less ! 

include_once 'PEAR/TestRunner.php';
PEAR_TestRunner::run(self::suite());

You don't believe it ? No problem test to see the magic dream become a reality :)

5. Credits

I would like to thanks here 3 guys that encouraged me (by their comments) to improve PEAR_TestListener from what it was (0.2.0) to current result (0.3.0).
In alphabetic order:

Special Thanks to Sebastian Bergmann, author of PHPUnit, without who, this proposal wouldn't have any sense.

Appendix A. Classes Source Code

  1. PEAR_TestRunner
  2. PEAR_TestListener
  3. PEAR_TestListener_Configuration

Appendix B. Examples

  1. Basic usage with PHP_CodeSniffer 1.2.0RC2
  2. Complex usage with PHP_CodeSniffer 1.2.0RC2
  3. Complex usage with PHP_Reflector
  4. Basic usage with a XML configuration file and XML_Util 1.2.1
  5. Advanced usage with a XML configuration file and XML_Util 1.2.1

Appendix C. ChangeLog