This article has been updated as of November 2012 to reflect the latest information for running unit and system tests for Joomla version 3.0.
When you checkout the master branch of Joomla from Github.com (https://github.com/joomla/joomla-cms) you will see a folder called "tests". This folder contains unit and two types of system tests for the CMS. The unit tests use PHPUnit and the system tests use PHPUnit and Selenium. The unit tests perform tests on the CMS library files (libraries/cms). The Selenium and Webdriver system tests run Joomla! from a browser and test it as a user would.
As of 3.0, we are transitioning our system tests from the older Selenium RC (found in the
tests/system/suite folder) to the newer Webdriver methodolgy (found in
tests/system/webdriver). We will continue to use and maintain the older tests, but all new tests will be written using Webdriver.
Before you can run the tests, you need to install some programs on your local workstation, as documented below. This document explains how to run the these tests from your local workstation.
You may need to modify your PHP configuration. This is done by editing your
php.ini file and then restarting your Apache service.
Some of the CMS unit tests rely on the PHP extension Sqlite3. To run these tests, make sure that the following line in your php.ini file is uncommented:
The Webdriver system tests require PHP version 5.3.8 or later. They also require that the Curl extension is installed. Make sure the following line in your php.ini file is uncommented:
Both the unit and system tests rely on PHPUnit. PHPUnit is a testing framework that requires PHP to be installed on the local workstation. On most PHP installations, PHPUnit can be installed using the PEAR installation process, so that is what we document here. As of November 2012, PHPUnit 3.6 is recommended. PHP version 5.3.8 or later is required to run the Joomla system tests. You can run the unit tests with PHP 5.3.3 or later.
The latest installation instructions for PHPUnit are here: http://www.phpunit.de/manual/3.6/en/installation.html.
The PEAR commands are as follows:
pear config-set auto_discover 1
pear install pear.phpunit.de/PHPUnit
pear install phpunit/DbUnit, or
pear install pear.phpunit/DbUnit
pear install phpunit/PHPUnit_Selenium
If you're receiving errors on OSX/Linux about Duplicate package channel://pear.phpunit.de/File_Iterator-* found try:
sudo pear clear-cache
sudo pear install phpunit/File_Iterator
sudo pear install phpunit/Text_Template
sudo pear install --force --alldeps pear.phpunit.de/PHPUnit
For example, on XAMPP version 1.8.1 on Windows, you would do the following commands and install PHPUnit version 3.7.8. First you set pear for auto discover, as follows:
C:\xampp\php>pear config-set auto_discover 1 config-set succeeded
Next you install PHPUnit. This will work for a few minutes and should show something similar to the following:
C:\xampp\php>pear install pear.phpunit.de/PHPUnit Attempting to discover channel "pear.phpunit.de"... downloading channel.xml ... Starting to download channel.xml (804 bytes) ....done: 804 bytes Auto-discovered channel "pear.phpunit.de", alias "phpunit", adding to registry Attempting to discover channel "pear.symfony.com"... downloading channel.xml ... ... ... (some lines omitted to save space) ... install ok: channel://pear.phpunit.de/File_Iterator-1.3.3 install ok: channel://pear.phpunit.de/Text_Template-1.1.4 install ok: channel://pear.phpunit.de/PHP_Timer-1.0.4 install ok: channel://pear.symfony.com/Yaml-2.1.3 install ok: channel://pear.phpunit.de/PHP_TokenStream-1.1.5 install ok: channel://pear.phpunit.de/PHP_CodeCoverage-1.2.6 install ok: channel://pear.phpunit.de/PHPUnit_MockObject-1.2.1 install ok: channel://pear.phpunit.de/PHPUnit-3.7.8
Next, install DbUnit as follows:
C:\xampp\php>pear install phpunit/DbUnit downloading DbUnit-1.2.1.tgz ... Starting to download DbUnit-1.2.1.tgz (41,892 bytes) ............done: 41,892 bytes install ok: channel://pear.phpunit.de/DbUnit-1.2.1
Finally, to run the system tests you need to install the Selenium extension for PHPUnit, as follows:
C:\xampp\php>pear install phpunit/PHPunit_Selenium downloading PHPUnit_Selenium-1.2.10.tgz ... Starting to download PHPUnit_Selenium-1.2.10.tgz (37,389 bytes) ..........done: 37,389 bytes install ok: channel://pear.phpunit.de/PHPUnit_Selenium-1.2.10
At this point, PHPUnit should be set up and you can proceed to the next section.
If you get an error that your PEAR version is too low, run:
pear upgrade pear
pear install phpunit/PHPUnit . Windows users not using WAMP or XAMPP can use the same procedure, with substituting the location of your PHP installation for
In Ubuntu Linux, use the following commands to install PHPUnit:
sudo apt-get install php-pear
sudo pear channel-update pear.php.net
sudo pear upgrade-all
sudo pear channel-discover pear.phpunit.de
sudo pear channel-discover components.ez.no
sudo pear channel-discover pear.symfony-project.com
sudo pear install -a phpunit/PHPUnit
sudo pear install pear.phpunit/DbUnit
In Mac OSX with XAMPP, use the following commands to install PHPUnit:
$sudo /Applications/XAMPP/xamppfiles/bin/pear channel-discover pear.phpunit.de
$sudo /Applications/XAMPP/xamppfiles/bin/pear channel-discover pear.symfony-project.com
$sudo /Applications/XAMPP/xamppfiles/bin/pear channel-discover components.ez.no
$sudo /Applications/XAMPP/xamppfiles/bin/pear install -a phpunit/PHPUnit
If you are using MAMP, substitute the path to your PHP pear folder for
More detailed instructions can be found here: http://www.phpunit.de/manual/3.0/en/installation.html.
Once PHPUnit is installed, it's easy to run the unit tests. The command that runs the tests is called
phpunit. This file is found in your PHP folder. For example, in Windows with Xampp, it would be
c:/xampp/php/phpunit. In Linux, with Xampp, it might be
/opt/lampp/bin/phpunit. If you add this to your operating system path, you can execute it from any folder without using the full path name.
When you run
phpunit it looks for a PHPUnit configuration XML file (either
phpunit.xml.dist). The CMS unit tests are run from the Joomla root folder, where you will find the
phpunit.xml.dist file. This file is included in the Git repository and can be used as is or customized (by making a copy called
To run all of the unit tests from the command line:
The following example runs the entire unit test suite using the
phpunit.xml.dist file in Windows.
C:\xampp\htdocs\joomla_development\cms-trunk>phpunit PHPUnit 3.6.11 by Sebastian Bergmann. Configuration read from C:\xampp\htdocs\joomla_development\cms-trunk\phpunit.xml.dist IIIIIIII....................SS.......S......................... 63 / 234 ( 26%) ............................................ISSISSSSSSSSSSI.... 126 / 234 ( 53%) ...IIIIIIIIII.I.I.I.IIIIIIIIIIIIIIIII..IIIIIIIIS.IIIIII..II..SS 189 / 234 ( 80%) SI..I........I...I...I...I.III.I............. Time: 13 seconds, Memory: 21.25Mb OK, but incomplete or skipped tests! Tests: 234, Assertions: 281, Incomplete: 67, Skipped: 19. Generating code coverage report in Clover XML format ... done Generating code coverage report in HTML format ... done
The dots indicate a successful test. If you have errors or failures, they will show as "E" or "F" letters and a detailed message for each will show. If you are generating code coverage or other logs, you can see the folders where these are generated in the XML file. In the default file, all of the logs are generated in
build/logs, with coverage information in a folder called
You can create your own phpunit.xml file by copying the phpunit.xml.dist file and making the desired changes. For example, if you don't want to create the coverage information, remove the
log type="coverage-html" element.
You can run unit tests one at a time or by folder. The following example runs all of the tests in the
C:\xampp\htdocs\joomla_development\cms-trunk>phpunit tests/unit/suites/libraries /feed PHPUnit 3.6.11 by Sebastian Bergmann. Configuration read from C:\xampp\htdocs\joomla_development\cms-trunk\phpunit.xml
....................SS.......S................................... 65 / 99 ( 65%) ..................................
Time: 1 second, Memory: 8.25Mb
OK, but incomplete or skipped tests!
You can also specify a single test simply by specifying it's full path name in the command.
The older Selenium RC system tests are in the folder tests/system/suite. Before you can run the system tests, you need to install and download the Selenium Server program and configure your test environment, as shown below.
Selenium Server (formerly Selenium RC) is the package that allows us to run Selenium tests from PHP (instead of Java). To download it, just go to the Selenium site http://seleniumhq.org/download/ and download the Selenium Server file (for example, selenium-server-standalone-2.25.0.jar) to a folder.
For example, in Windows if you create a folder called
C:\selenium and copy this file there. In that folder, create a Windows bat file (such as selenium.bat though the name does not matter) or Linux shell script that runs the following command:
java -Xms40m -Xmx256m -jar selenium-server-2.25.0.jar
(Obviously you will need to use the exact name of the .jar file for the version you downloaded.) The -Xms and -Xmx arguments run the server program allocating more memory to Java than the default. That seems to help prevent intermittent errors when running a long suite of system tests.
If the Java executable is not on your path, then you will need to indicate the full path to it, like the following:
"c:\program files (x86)\Java\jre6\bin\java.exe" -Xms40m -Xmx256m -jar selenium-server-2.25.0.jar
This program needs to be running in the background before you can run any Selenium functional tests. So just run this program from a Bat file and it will continue to run in the background in a console window until you close it (for example, with Ctrl+C).
To run the Selenium tests, we have to tell Selenium how to navigate and login to our local Joomla! installation. This is done by creating a PHP file called
tests/system/servers/configdef.php. The Joomla! download includes a file called
tests/system/servers/config-def.php-dist. This is a sample file that you can use to create the real file. Copy this file to a file called
tests/system/servers/configdef.php and edit it to reflect your test systems configuration. There are comments in the file that tell you how to do this.
At this point, we are ready to actually run the tests. There are two steps to running a test. First, you need to make sure the Selenium Server process is running in the background. To do this, just execute the command (bat file or shell script) you created when you installed Selenium. This will continue to run (in a console window) until you cancel it. You do not need to stop and start this for each test. Just run it once and let it run in the background.
Once Selenium is running, you need to execute the system tests. These are executed the same way we did the unit tests, except for our starting directory.
To run all tests from the command line in Windows, change to the
tests/system folder and run the following command
By default, this will use the
tests/system/phpunit.xml.dist file that is included with the Joomla checkout. This will run all of the tests listed in the phpunit.xml.dist file. You should see two browser windows open. One will display Selenium commands that are being executed. The other will show the Joomla! website and the various screens that are being opened and closed as the tests are run. As each test is completed, you will see comments in the console window describing each step in the test.
Note that the entire suite of tests takes about one hour to run. When they are done, you will get a summary display showing how many tests were run and whether there were errors or failures. If there are errors or failures, the line of code from the test program that generated the error or failure will also show. An error occurs when the test encounters an actual PHP error. A failure occurs when the test gets a result that is different than expected (when one of the assert statements in the test is not as expected).
If you use the default phpunit.xml.dist file, a file
tests/system/suite/logs/junit.xml will be created at the conclusion of the test. This file can be interpreted by Eclipse and any other program that works with JUnit unit tests. It provides a graphical way to see the test results.
As with the unit tests, you can run selected system tests by folder or file. For example, the following command will run all of the tests in the acl folder:
To run a the article0001Test.php tests:
Webdriver is the newer system test program from Selenium. In general, all new Joomla system tests should be written with Webdriver.
The Webdriver tests are in the folder
tests/system/webdriver. This folder has the following subfolders:
There is also a file called
bootstrap.php in the webdriver folder. This is used to auto-load the required classes. Inside the tests folder we have a file called
JoomlaWebdriverTestCase.php. This file is the parent class for all Webdriver tests and has a number of useful methods.
Running the Webdriver tests is exactly the same as running the old system tests except for the starting directory. The steps are:
This will by default use the configuration file
tests/system/webdriver/tests/phpunit.xml.dist, which is included with the CMS checkout. You can customize this by copying it to phpunit.xml and editing as desired. You do not need to delete the
phpunit.xml.dist file because the
phpunit.xml file takes priority if both are found.
Webdriver tests only open one browser window. Like the Selenium RC system tests, Webdriver tests are relatively slow -- similar to a very fast data entry person using the application.
You can run selected Webdriver tests by folder or by file just as you do for the other system tests or for the unit tests. The only difference is the starting folder.
In Eclipse, you can set up Debug and External Tools launch configurations that make it easy to debug or run unit and system tests. See Running Automated Tests from Eclipse.