Unit Testing

From Joomla! Documentation

Revision as of 16:26, 4 March 2008 by Instance (Talk | contribs)

Unit Testing

Unit testing is an essential part of a good Quality Control program. For more information, visit the Wikipedia article on unit testing.

Unit Testing in Open Source

Open source projects, with multiple developers working in parallel around the world, can greatly benefit from unit testing. The main benefits are:

  • Unit tests help highlight cases where seemingly minor changes cause unexpected breakage.
  • Unit tests help clearly specify how a class should behave.
  • Unit tests can expose design flaws very early in development.
  • Unit tests make great examples. They are a great place for developers to learn how to use the code.

Unit Testing in Joomla!

Unit testing capabilities in Joomla are still at an early stage. The intention is to define more standards for developing tests, and then to expand the scope of available tests

The SVN repository contains code under the /testing path. /testing/trunk contains code based on the SimpleTest framework. In early December 2007, the development team elected to move to the PHPUnit framework.

Work on using PHPUnit has been done in /testing/branches/2007-12-17. Some new tests have been added, many old tests from the SimpleTest days are completely broken.

At this point, PHPUnit based tests only run in a command line environment.

Current Work

  • There is no longer any need to patch the main code to enable unit tests.
  • Basic techniques for mock objects are defined.
  • Strategies for dealing with local configuration is not yet complete, but there is a plan.
  • Files of the form class-sequence-type-test.php, for example JObject-0000-class-test.php use PHPUnit.
  • The JDate tests present a good example of a data-driven test, but they won't run on the current 1.5 code base (there are some proposed API changes as a result of unit test development).
  • Previously functional tests, such as JFTP, haven't been moved to the PHPUnit environment yet.

Running Unit Tests

Test files follow the form class-sequence-type-test.php, for example JObject-0000-class-test.php. For tests that are not class based, the first element refers to the object being tested. An example of this is the e-mail cloaking plugin test, which is called emailcloak-0000-mode1-test.php.

Joomla unit tests use a customized test "runner". Every test directory should have a "runtests.php" file. Runtests has a few options, mostly to allow the selection of specific tests. The command line options are:

--class-filter regex

e.g. --class-filter /JDate/ Selects only tests that have a class part that matches the regular expression.


Turns on additional debugging output.


Prints information on options and exits.

--sequence-filter regex

Selects only tests that have a sequence part that matches the regular expression.

--test-filter regex

Selects only tests that have a test part that matches the regular expression.

TODO: Expand command line parsing to add other features of the PHPUnit framework, such as output formats, code metrics reports, etc.

Writing Unit Tests

At risk of stating the obvious, in the "purest" case the purpose of a unit test is to isolate a unit of code from its environment and to test the operation of that code.

This isolation is usually achieved by writing simple stubs that emulate the code unit's environment. These stubs are known as "Mock Objects". Mock objects can be passive, by simply simulating the environment, or they can be more active, keeping track of how they are being used by the test unit and reporting any variations from the expected behaviour.

An interesting aspect of writing tests is that they become de facto detailed technical specifications of the interfaces between units of code. The fact that these specifications can be verified in an automated way makes them a superb resource when refactoring code.

The test code has a few templates designed to kick-start a test. They are:

/unittest/sample-datatest-php.txt /unittest/sample-simpletest.php.txt

Here are some example tests Unit_Testing_Example_Simple