Difference between revisions of "Unit Tests"

From PKP Wiki
Jump to: navigation, search
(Added some usage documentation (e.g. annotations))
(How to document tests.)
Line 52: Line 52:
 
* Unit tests that require database access extend "DatabaseTestCase".
 
* Unit tests that require database access extend "DatabaseTestCase".
 
* All other test cases extend "PKPTestCase".
 
* All other test cases extend "PKPTestCase".
 +
 +
== 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.
 +
* Use a @see annotation in the class comment that points to the tested class.
  
 
== How to test exceptions ==
 
== How to test exceptions ==

Revision as of 19:52, 19 October 2009

Installing and Configuring your Test Environment

PEAR

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.

PHPUnit

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.

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.

"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)."

File:Screenshot-External Tools .png

Text and screenshot in this section are reproduced without alteration from PHPUnit Wiki in accordance with Creative Commons License. Thanks to zoe.

Installing and Configuring the Build Environment

Phing

On the command line execute

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

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.

Nomenclature

  • 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".

Which base class to extend

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

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