Joomla! Documentation™

Introduction

As of February 2010, a tests folder has been added to the Joomla! SVN download. This folder contains a growing library of unit and functional tests. The unit tests use PHPUnit and the functional tests use PHPUnit and Selenium. The unit tests perform tests primarily on the Joomla! framework. The Selenium functional tests actually run Joomla! from a browser and test it as a user would.

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 functional tests from your local workstation.

Install PHPUnit

Both the unit and functional tests rely on PHPUnit. On most PHP installations, this can be installed using the standard PEAR installation process.

For example, on XAMPP version 1.7.3 on Windows, you would do the following commands:

• cd c:\xampp\php
• install phpunit/PHPUnit

More detailed instructions can be found here: http://www.phpunit.de/manual/3.0/en/installation.html.

Install Selenium RC

Selenium RC is the package that allows you to run Selenium tests from PHP or other programming languages. To install it, just go to the Selenium site http://seleniumhq.org/projects/remote-control and download the package. Then unzip the file into a folder.

For example, in Windows if you create a folder called C:\selenium and unzip this file there, it will create a folder called selenium-server-1.0.1. In that folder, create a Windows bat file or Linux shell script that runs the following command:

java -jar selenium-server.jar -browserSessionReuse

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" -jar selenium-server.jar -browserSessionReuse

Note the argument browserSessionReuse is used to allow you to run multiple tests without closing and re-opening the browser each time. Save this file so you can easily find and execute it when needed.

This program needs to be running in the background before you can run any Selenium functional tests.

Create a Selenium Configuration File

To run the Selenium tests, we have to tell Selenium how to navigate and login to your local Joomla! installation. This is done by creating a PHP file called 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.

Run the Test Suite

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 RC process is running in the background. To do this, just execute the command (bat file or shell script) you created when you installed Selenium RC. This will continue to run until you cancel it.

Once Selenium RC is running, you need to execute the functional tests. There are several ways you can do this.

To run all tests from the command line, change to the tests/system folder and run the following command:

phpunit.bat --bootstrap servers\configdef.php suite\TestSuite.php

This will run all of the tests in the TestSuite.php file. You should see a series of messages display in the console telling you what tests are being run and what the tests are doing. You should also 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.

The tests will run for a few minutes, depending on the speed of your system. 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.

Tips

• Make sure you run the tests on a clean database that has been installed with sample data. If you have made database changes, you should re-install Joomla! or otherwise put the database back to it's original post-installed state.
• If you find errors or failures when you run the tests, you can run the tests against the Joomla! trunk to see if the problems are in trunk or just in your branch.
• If you maintain more than one local Joomla! project (for example, one for trunk, another for a branch), you will need to make sure to have a configdef.php file for each that has the right path and login information. You can watch the browser window while the tests are running to make sure you are testing the URL that you expect.
• If you use Eclipse, you can use the External Tools Configurations option to create launch configurations to run the tests. For example, to create a launch configuration to run the test suite of the currently-selected Eclipse project, you would enter the location that points to your phpunit.bat file, set the Working Directory to "${project_loc}\tests\system", and set the arguments to --bootstrap servers\configdef.php suite\TestSuite.php. This is shown in the screenshot below.

Then you can run this from inside Eclipse and the console output will show in the Eclipse console. Note that you still need to have the Selenium RC program running in the background first, before running the suite. Note that you need to select a file in the current project before running this command so the {project_loc} variable is set correctly.