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.
Please see our 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 works well with our usual PKP file name nomenclature. Files are named after the test class name with a ".inc.php" postfix, e.g. the ConfigTest class would be found in the file "ConfigTest.inc.php".
- We'll use the same folder structure inside the tests directory that we use for the classes we test.
- Tests for PKP library classes will be in "lib/pkp/tests". Tests for PKP application classes will be in "/tests".
Which base class to extend
- Unit tests that require database access extend "DatabaseTestCase".
- All other test cases extend "PKPTestCase".
- 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.
Annotations have to be declared where they apply.
Please see the PHPUnit manual for details on each annotation.
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.
Running Unit Tests
If you have followed our tutorial to Configure Eclipse for PHPUnit then running tests will be very easy.
Select the test
Installing and Configuring the Build Environment
On the command line execute
pear channel-discover pear.phing.info pear install phing/phing