Difference between revisions of "Unit Tests"

From PKP Wiki
Jump to: navigation, search
m (minor change)
m (Point to an Eclipse tutorial page)
Line 25: Line 25:
== Eclipse integration ==
== Eclipse integration ==
If you use Eclipse then you should install an external tool runner to integrate PHPUnit. This is a Wiki. Please feel free to add similar configurations for other CASE tools.
Please see the [[Configure Eclipse for PHPUnit]] tutorial.
"The first step is to create the launch configuration which tells Eclipse where to find PHP, PHPUnit and the test you want to run. To create a launch configuration, start up Eclipse and, from the top menu bar click run->external tools->open external tools dialogue. On that page click the New launch configuration icon in the top left hand corner. I've shown a sample launch configuration below. The string in the top box (/mnt/workspace/PHP/php53/saapi/cli/php) is the name of my PHP executable. On your system this might be something like /usr/local/php (Linux) or on Windows it will be the location of your php.exe. In the next box you add the text exactly as I have shown, Eclipse will resolve this to work space that you are using. In the final (lowest box) you need the location of your PHPUnit executable followed by the srting ${resource_path}, ${resource_path} is resolved by Eclipse to the entity that you will highlight when you want to execute a test (see later)."
Text and screenshot in this section are reproduced without alteration from [http://www.phpunit.de/wiki/Eclipse PHPUnit Wiki] in accordance with [http://creativecommons.org/licenses/by-nc-nd/2.5/ Creative Commons] License. Thanks to zoe.
= Developing Unit Tests =
= Developing Unit Tests =

Revision as of 14:46, 20 October 2009

Installing and Configuring your Test Environment


You'll need PEAR installed for the following steps to work. If you are on Linux simply install the corresponding package provided by your packaging system. If you are on Windows execute the "go-pear.bat" in the PHP installation directory and follow the on-screen instructions.

If you are on Linux you may also find some or all of the other required software pre-packaged for your distribution. Please check that before installing software manually.


On the command line execute

pear channel-discover pear.phpunit.de
pear install phpunit/PHPUnit

PKP Unit Test Framework

The PKP unit test framework can be checked out as part of the pkp library. You find it in pkp/tests.

You'll however have to use the unit test framework within an application to work properly.

Before starting your tests, please make copies of the files in "/lib/pkp/tests/config", remove the "TEMPLATES" placeholder and configure the pgsql and mysql database connection data.

Eclipse integration

Please see the Configure Eclipse for PHPUnit tutorial.

Developing Unit Tests

This is a very terse documentation of the PHPUnit features we usually use in our unit tests. It is meant to document PKP-specific usage of PHPUnit and as a cheat sheet for the most important PHPUnit functionality. It does not replace the PHPUnit manual. Please refer to the manual when you are using PHPUnit for the first time.


  • Unit test classes are called after the class they are testing, e.g. the test to test the "Config" class would be "ConfigTest".
  • PHPUnit uses it's own nomenclature do discover tests in directories. Therefore the file nomenclature is different from that of the PKP code itself. Files are named after the test class name with a ".php" postfix, e.g. the ConfigTest class would be found in the file "ConfigTest.php".
  • We'll use the same folder structure inside the tests directory that we use for the classes we test.

Which base class to extend

  • Unit tests that require database access extend "DatabaseTestCase".
  • All other test cases extend "PKPTestCase".

Test Documentation

  • One of the functions of a test case is documenting the class specification in a very detailed and precise way. Please make sure that your source code contains enough method and inline documentation so that an outsider can quickly understand how the class' API is to be used. This is not necessary if the test method name speaks for itself.
  • Use a @see annotation in the class comment that points to the tested class.

How to test exceptions

  • A test method that is annotated with "@expectedException ExceptionClass" will fail if it does not throw the declared exception.

PHPUnit annotations

Annotations have to be declared where they apply.

Please see the PHPUnit manual for details on each annotation.

Declaring Coverage

The @covers annotation indicates to the test coverage analyser the class or method to be covered by a given unit test. The @covers annotation is mandatory for all tests. The function format is always preferable to the class format. You'll very rarely write unit tests that cover a whole class.

  • method format: @covers ClassName::methodName
  • class format: @covers ClassName

Documenting Test Dependency

The @depends defines a logical dependency of one test case from another. You use the depends annotation if you want to document such dependency or if you want to use results from one test case as input to another test case. Test execution order is only dependent on the order of the methods in the test class, not on the @depends annotation.

Installing and Configuring the Build Environment


On the command line execute

pear channel-discover pear.phing.info
pear install phing/phing