Actions

Difference between revisions of "Running Automated Tests for the Joomla CMS"

From Joomla! Documentation

(add information for running unit tests and debugging -- in process)
(Install PHPUnit)
(44 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 +
{{RightTOC}}
 
== Introduction ==
 
== 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 system (or functional) tests. The unit tests use PHPUnit and the system tests use PHPUnit and Selenium. The unit tests perform tests primarily on the Joomla! framework. The Selenium system tests actually run Joomla! from a browser and test it as a user would.
+
'''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 <code>tests/system/suite</code> folder) to the newer Webdriver methodolgy (found in <code>tests/system/webdriver</code>). 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.
 
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.
 +
 +
== PHP Requirements ==
 +
You may need to modify your PHP configuration. This is done by editing your <code>php.ini</code> file and then restarting your Apache service.
 +
 +
=== CMS Unit Tests ===
 +
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:
 +
* For Windows: <code>extension=php_sqlite3.dll</code>
 +
* For Linux: <code>extension=php_sqlite3.so</code>
 +
 +
=== Webdriver System Tests ===
 +
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:
 +
* For Windows: <code>extension=php_curl.dll</code>
 +
* For Linux: <code>extension=php_curl.so</code>
  
 
== Install PHPUnit ==
 
== Install PHPUnit ==
Both the unit and functional tests rely on PHPUnit. PHPUnit is a testing framework that requires PHP to be installed on the local workstation. XAMP / WAMP users can use the PHP installation that comes with them. Otherwise, you may need to install PHP, and the PEAR package, on your local workstation. More detailed instructions can be found at [http://www.php.net/manual/en/install.php http://www.php.net/manual/en/install.php].
+
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, PNPUnit 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.
  
On most PHP installations, PNPUnit can be installed using the standard PEAR installation process.
+
The latest installation instructions for PHPUnit are here: [http://www.phpunit.de/manual/3.6/en/installation.html http://www.phpunit.de/manual/3.6/en/installation.html].
  
For example, on XAMPP version 1.7.3 on Windows, you would do the following commands:
+
The PEAR commands are as follows:
 +
* <code>pear config-set auto_discover 1</code>
 +
* <code>pear install pear.phpunit.de/PHPUnit</code>
 +
* <code>pear install pear.phpunit/DbUnit</code>, or <code>pear install pear.phpunit/DbUnit</code>
 +
* <code>pear install phpunit/PHPUnit_Selenium</code>
  
* <code>cd c:\xampp\php</code>
+
If you're receiving errors on OSX/Linux about ''Duplicate package channel://pear.phpunit.de/File_Iterator-* found'' try:
* <code>pear channel-discover pear.phpunit.de</code>
+
* <code>sudo pear clear-cache</code>
* <code>pear channel-discover pear.symfony-project.com</code>
+
* <code>sudo pear install phpunit/File_Iterator</code>
* <code>pear install phpunit/PHPUnit</code>
+
* <code>sudo pear install phpunit/Text_Template</code>
 +
* <code>sudo pear install --force --alldeps pear.phpunit.de/PHPUnit</code>
  
If you get error about PEAR version too low, run:
+
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:
  
* <code>pear upgrade pear</code>
+
C:\xampp\php>pear config-set auto_discover 1
 +
config-set succeeded
  
and repeat <code>pear install phpunit/PHPUnit</code>
+
Next you install PHPUnit. This will work for a few minutes and should show something similar to the following:
.
+
Windows users not using WAMP or XAMPP can use the same procedure, with substituting the location of your PHP installation for <code>cd c:\xampp\php</code>.
+
  
In Ubuntu Linux, use the following commands to install PHPUnit:
+
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
  
* <code>$sudo pear channel-discover pear.phpunit.de</code>
+
Next, install DbUnit as follows:
* <code>$sudo pear channel-discover pear.symfony-project.com</code>
+
* <code>$sudo pear install phpunit/PHPUnit</code>
+
  
More detailed instructions can be found here: [http://www.phpunit.de/manual/3.0/en/installation.html http://www.phpunit.de/manual/3.0/en/installation.html].
+
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
  
== Running Unit Tests ==
+
Finally, to run the system tests you need to install the Selenium extension for PHPUnit, as follows:
Once PHPUnit is installed, you can run the unit tests. To run a unit test from the command line:
+
# Change to the folder <code><joomla root>/tests/unit</code>
+
# Execute the command <code>phpunit <test name or folder></code>
+
For example, to execute the test called "tests\unit\suite\libraries\joomla\utilities\JStringTest.php", you would type the command
+
* <code>phpunit tests\unit\suite\libraries\joomla\utilities\JStringTest.php</code>
+
  
When you run this, you will see output similar to the following:
+
C:\xampp\php>pear install phpunit/PHPunit_Selenium
<pre>
+
downloading PHPUnit_Selenium-1.2.10.tgz ...
C:\xampp\htdocs\joomla_development\j16_trunk\tests\unit>phpunit suite\libraries\
+
Starting to download PHPUnit_Selenium-1.2.10.tgz (37,389 bytes)
joomla\utilities\jstringtest.php
+
..........done: 37,389 bytes
PHPUnit 3.4.11 by Sebastian Bergmann.
+
install ok: channel://pear.phpunit.de/PHPUnit_Selenium-1.2.10
  
............................................................ 60 / 89
+
At this point, PHPUnit should be set up and you can proceed to the next section.  
.............................
+
  
Time: 26 seconds, Memory: 7.00Mb
+
===Troubleshooting PHPUnit Installation===
 +
If you get an error that your PEAR version is too low, run:
  
OK (89 tests, 89 assertions)
+
* <code>pear upgrade pear</code>
</pre>
+
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.
+
  
You can execute all of the tests in a folder by specifying a folder instead of a file. For example, to run all of the tests in the folder "tests\unit\suite\libraries\joomla\utilities", you would enter
+
and repeat <code>pear install phpunit/PHPUnit</code>
* <code>phpunit tests\unit\suite\libraries\joomla\utilities</code>
+
.
 +
Windows users not using WAMP or XAMPP can use the same procedure, with substituting the location of your PHP installation for <code>cd c:\xampp\php</code>.
  
This command will produce output similar to that shown below:
+
In Ubuntu Linux, use the following commands to install PHPUnit:
<pre>
+
C:\xampp\htdocs\joomla_development\j16_trunk\tests\unit>phpunit suite\libraries\
+
joomla\utilities
+
PHPUnit 3.4.11 by Sebastian Bergmann.
+
  
............................................................  60 / 317
+
* <code>sudo apt-get install php-pear</code>
............................................................ 120 / 317
+
* <code>sudo pear channel-update pear.php.net</code>
............................................................ 180 / 317
+
* <code>sudo pear upgrade-all</code>
............................................................ 240 / 317
+
* <code>sudo pear channel-discover pear.phpunit.de</code>
............................................................ 300 / 317
+
* <code>sudo pear channel-discover components.ez.no</code>
...FFFF..........
+
* <code>sudo pear channel-discover pear.symfony-project.com</code>
 +
* <code>sudo pear install -a phpunit/PHPUnit</code>
 +
* <code>sudo pear install pear.phpunit/DbUnit</code>
  
Time: 27 seconds, Memory: 11.00Mb
+
In Mac OSX with XAMPP, use the following commands to install PHPUnit:
 +
* <code>$sudo /Applications/XAMPP/xamppfiles/bin/pear channel-discover  pear.phpunit.de</code>
 +
* <code>$sudo /Applications/XAMPP/xamppfiles/bin/pear channel-discover  pear.symfony-project.com</code>
 +
* <code>$sudo /Applications/XAMPP/xamppfiles/bin/pear channel-discover  components.ez.no</code>
 +
* <code>$sudo /Applications/XAMPP/xamppfiles/bin/pear install -a phpunit/PHPUnit</code>
  
There were 4 failures:
+
If you are using MAMP, substitute the path to your PHP pear folder for <code>/Applications/XAMPP/xamppfiles/bin/</code>.
  
1) JUtilityTest::testGetHash
+
More detailed instructions can be found here: [http://www.phpunit.de/manual/3.0/en/installation.html http://www.phpunit.de/manual/3.0/en/installation.html].
Failed asserting that two strings are equal.
+
--- Expected
+
+++ Actual
+
@@ @@
+
-ce114e4501d2f4e2dcea3e17b546f339
+
+0cbc6611f5540bd0809a388dc95a615b
+
  
 +
== Running Unit Tests ==
 +
===Run Suite from XML File===
 +
Once PHPUnit is installed, it's easy to run the unit tests. The command that runs the tests is called <code>phpunit</code>. This file is found in your PHP folder. For example, in Windows with Xampp, it would be <code>c:/xampp/php/phpunit</code>. In Linux, with Xampp, it might be <code>/opt/lampp/bin/phpunit</code>. If you add this to your operating system path, you can execute it from any folder without using the full path name.
  
2) JUtilityTest::testGetToken with data set "default" (NULL, false)
+
When you run <code>phpunit</code> it looks for a PHPUnit configuration XML file (either <code>phpunit.xml</code> or <code>phpunit.xml.dist</code>). The CMS unit tests are run from the Joomla root folder, where you will find the <code>phpunit.xml.dist</code> file. This file is included in the Git repository and can be used as is or customized (by making a copy called <code>phpunit.xml</code>).  
Failed asserting that <string:adca734617ce829cc979492d6d037416> matches expected
+
<boolean:false>.
+
  
 +
To run all of the unit tests from the command line:
 +
# Change Joomla root folder
 +
# Execute the command <code>phpunit</code>.
  
3) JUtilityTest::testGetToken with data set "false" (false, false)
+
The following example runs the entire unit test suite using the <code>phpunit.xml.dist</code> file in Windows.
Failed asserting that <string:adca734617ce829cc979492d6d037416> matches expected
+
<boolean:false>.
+
  
 +
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
  
4) JUtilityTest::testGetToken with data set "true" (true, true)
+
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 <code>build/logs</code>, with coverage information in a folder called <code>coverage</code>.
Expectation failed for method name is equal to <string:getFormToken> when invoke
+
d 1 time(s).
+
Method was expected to be called 1 times, actually called 0 times.
+
  
 +
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 <code>log type="coverage-html"</code> element.
  
FAILURES!
+
===Run Selected Unit Tests===
Tests: 317, Assertions: 361, Failures: 4.</pre>
+
You can run unit tests one at a time or by folder. The following example runs all of the tests in the <code>libraries/feed</code> folder:
In this case, we have 4 test failures with details about each.
+
  
== System Tests ==
+
C:\xampp\htdocs\joomla_development\cms-trunk>phpunit tests/unit/suites/libraries
Before you can run the system tests, you need to install and set up the Selenium RC package and configure your test environment, as shown below.
+
/feed
 +
PHPUnit 3.6.11 by Sebastian Bergmann.
 +
 +
Configuration read from C:\xampp\htdocs\joomla_development\cms-trunk\phpunit.xml
  
=== Install Selenium RC ===
+
....................SS.......S................................... 65 / 99 ( 65%)
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 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 <code>C:\selenium</code> and unzip this file there, it will create a folder called selenium-server-1.0.1. 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:
+
Time: 1 second, Memory: 8.25Mb
  
<code>java -jar selenium-server.jar -browserSessionReuse</code>
+
OK, but incomplete or skipped tests!
  
If the Java executable is not on your path, then you will need to indicate the full path to it, like the following:
+
You can also specify a single test simply by specifying it's full path name in the command.
  
<code>c:\program files (x86)\Java\jre6\bin\java.exe" -jar selenium-server.jar -browserSessionReuse</code>
+
== Selenium RC System Tests ==
 +
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.
  
Note the argument <code>browserSessionReuse</code> 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.
+
=== Download Selenium Server ===
 +
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/ http://seleniumhq.org/download/] and download the Selenium Server file (for example, selenium-server-standalone-2.25.0.jar) to a folder.
  
This program needs to be running in the background before you can run any Selenium functional tests.
+
For example, in Windows if you create a folder called <code>C:\selenium</code> 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:
  
If You are using Firefox 3.6.x you will run in problems with this configuration. Check out this link: http://www.qaautomation.net/?p=15 how to get it working on Firefox 3.6.x.
+
<code>java -Xms40m -Xmx256m -jar selenium-server-2.25.0.jar</code>
  
=== Create a Selenium Configuration File ===
+
(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.
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 <code>configdef.php</code>. The Joomla! download includes a file called <code>tests/system/servers/config-def.php-dist</code>. This is a sample file that you can use to create the real file. Copy this file to a file called <code>tests/system/servers/configdef.php</code> and edit it to reflect your test systems configuration. There are comments in the file that tell you how to do this.
+
  
=== Run the System Test Suite ===
+
If the Java executable is not on your path, then you will need to indicate the full path to it, like the following:
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.  
+
<code>"c:\program files (x86)\Java\jre6\bin\java.exe" -Xms40m -Xmx256m -jar selenium-server-2.25.0.jar</code>
  
To run all tests from the command line in Windows, change to the <code>tests/system</code> folder and run the following command (the phpunit.bat file comes from the PHPUnit installation):
+
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).
  
<code>phpunit.bat --bootstrap servers\configdef.php suite\TestSuite.php </code>
+
=== Create a Selenium Configuration File ===
 +
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 <code>tests/system/servers/configdef.php</code>. The Joomla! download includes a file called <code>tests/system/servers/config-def.php-dist</code>. This is a sample file that you can use to create the real file. Copy this file to a file called <code>tests/system/servers/configdef.php</code> and edit it to reflect your test systems configuration. There are comments in the file that tell you how to do this.
  
In Linux, the command is:
+
=== Run the System 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 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.
  
<code>phpunit --bootstrap servers/configdef.php suite/TestSuite.php </code>
+
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.
  
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.
+
To run all tests from the command line in Windows, change to the <code>tests/system</code> folder and run the following command
  
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.
+
<code>phpunit</code>
  
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.
+
By default, this will use the <code>tests/system/phpunit.xml.dist</code> 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.
  
== Tips ==
+
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).  
* 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 the default phpunit.xml.dist file, a file <code>tests/system/suite/logs/junit.xml</code> 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.
  
== Eclipse Users ==
+
===Run Selected Tests===
In Eclipse, you can set up Debug and External Tools launch configurations that make it easy to debug or run unit and system tests.
+
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:
  
=== Run a Single Unit Test ===
+
<code>phpunit suite/acl</code>
You can create an External Tools launch configuration that lets you run any unit test simply by pointing to the test file and pressing the Run button. Here are the steps:
+
* open the Run&rarr;External Tools&rarr;External Tools Configuration menu and press the button labeled "New Launch Configuration"
+
* enter the location that points to your phpunit.bat file (for example, <code>c:\xampp\php\phpunit.bat</code>).
+
* set the Working Directory to <code>${project_loc}\tests\unit</code>
+
* set the arguments to <code>c:\xampp\php\phpunit --verbose "${resource_loc}"</code>.
+
This is shown in the screenshot below.
+
  
[[Image:unit_test_tutorial_screenshot_20100405-01.png]]
+
To run a the article0001Test.php tests:
  
=== Debug a Single Unit Test ===
+
<code>phpunit suite/articles/article0001Test.php</code>
  
=== Run a Single System Test ===
+
==Webdriver Tests==
You can create a configuration to make it easy to run any single test in your project. To do this:
+
Webdriver is the newer system test program from Selenium. In general, all new Joomla system tests should be written with Webdriver.
* open the Run&rarr;External Tools&rarr;External Tools Configuration menu and press the button labeled "New Launch Configuration"
+
* enter the location that points to your phpunit.bat file (for example, <code>c:\xampp\php\phpunit.bat</code>).
+
* set the Working Directory to <code>${project_loc}\tests\system</code>
+
* set the arguments to <code>--bootstrap servers\configdef.php ${selected_resource_loc}</code>.
+
This is shown in the screenshot below.
+
  
[[Image:Selenium_tutorial_screenshot_20100211.png]]
+
The Webdriver tests are in the folder <code>tests/system/webdriver</code>. This folder has the following subfolders:
 +
* '''Pages:''' Contains the page class files for the CMS.
 +
* '''SeleniumClient:''' Contains the Nearsoft library files. These are files that allow us to write the Webdriver tests in PHP (instead of Java). They are maintained on Gihub at [https://github.com/Nearsoft/PHP-SeleniumClient https://github.com/Nearsoft/PHP-SeleniumClient].
 +
* '''tests:''' Contains the folders with the test programs. These use the Pages files.
  
To use this configuration,
+
There is also a file called <code>bootstrap.php</code> in the webdriver folder. This is used to auto-load the required classes. Inside the tests folder we have a file called <code>JoomlaWebdriverTestCase.php</code>. This file is the parent class for all Webdriver tests and has a number of useful methods.
# make sure the Selenium RC process is running (for example, by running the "selenium.bat" file you created when you installed Selenium RC earlier)
+
# select the desired test file by clicking on it in the PHP Explorer view or in the edit area
+
# start this launch configuration
+
The selected test file will be run and you will see the browser session open and run the test script. The test results will be reported in the Eclipse console.
+
+
=== Debug a Single System Test ===
+
  
=== Run the System Test Suite ===
+
===Run All Webdriver Tests===
To create a launch configuration to run the Test Suite of the currently-selected Eclipse project:
+
Running the Webdriver tests is exactly the same as running the old system tests except for the starting directory. The steps are:
* enter the location that points to your phpunit.bat file
+
* Make sure the Selenium Server is running in the background.
* set the Working Directory to <code>${project_loc}\tests\system</code>
+
* Change directory to the <code>tests/system/webdriver/tests</code> folder.
* set the arguments to <code>--bootstrap servers\configdef.php suite\TestSuite.php</code>.
+
* Execute the command: <code>phpunit</code>
This is shown in the screenshot below.
+
  
[[Image:Selenium_tutorial_screenshot_20100205.png]]
+
This will by default use the configuration file <code>tests/system/webdriver/tests/phpunit.xml.dist</code>, 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 <code>phpunit.xml.dist</code> file because the <code>phpunit.xml</code> file takes priority if both are found.
  
: The argument <code>suite\TestSuite.php</code> identifies the test that you wish to run. To run a different test, change this argument to the test that you wish to run. For example, to run com_users user0001Test.php, you would use <code>suite\com_users\user0001Test.php</code>. Remember that we have already set the Working Directory as \tests\system.  
+
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.
  
: 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 <code>{project_loc}</code> variable is set correctly.
+
===Run Selected Webdriver Tests===
 +
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.
  
 +
== 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. When you run the entire system test suite, the first test does a clean re-install for you automatically. This tests the installation and also makes sure the database is in an expected state.
 +
* If you find errors or failures when you run the tests, you can run the tests against the Joomla! master branch to see if the problems are in master or just in your branch.
  
 +
== Eclipse Users ==
 +
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|Running Automated Tests from Eclipse]].
  
[[Category:Bug Squad]] [[Category:Development]] [[Category:Testing]]
+
[[Category:Bug Squad]] [[Category:Development]] [[Category:Testing]] [[Category:Automated Testing]] [[Category:Joomla! 2.5]][[Category:Joomla! 3.x]]

Revision as of 17:27, 22 February 2013

Contents

Introduction

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.

PHP Requirements

You may need to modify your PHP configuration. This is done by editing your php.ini file and then restarting your Apache service.

CMS Unit Tests

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:

  • For Windows: extension=php_sqlite3.dll
  • For Linux: extension=php_sqlite3.so

Webdriver System Tests

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:

  • For Windows: extension=php_curl.dll
  • For Linux: extension=php_curl.so

Install PHPUnit

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, PNPUnit 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 pear.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.

Troubleshooting PHPUnit Installation

If you get an error that your PEAR version is too low, run:

  • pear upgrade pear

and repeat 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 cd c:\xampp\php.

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 /Applications/XAMPP/xamppfiles/bin/.

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

Running Unit Tests

Run Suite from XML File

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 or 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 phpunit.xml).

To run all of the unit tests from the command line:

  1. Change Joomla root folder
  2. Execute the command phpunit.

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

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.

Run Selected Unit Tests

You can run unit tests one at a time or by folder. The following example runs all of the tests in the libraries/feed folder:

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.

Selenium RC System Tests

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.

Download Selenium Server

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

Create a Selenium Configuration File

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.

Run the System 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 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

phpunit

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.

Run Selected Tests

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:

phpunit suite/acl

To run a the article0001Test.php tests:

phpunit suite/articles/article0001Test.php

Webdriver 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:

  • Pages: Contains the page class files for the CMS.
  • SeleniumClient: Contains the Nearsoft library files. These are files that allow us to write the Webdriver tests in PHP (instead of Java). They are maintained on Gihub at https://github.com/Nearsoft/PHP-SeleniumClient.
  • tests: Contains the folders with the test programs. These use the Pages files.

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.

Run All Webdriver Tests

Running the Webdriver tests is exactly the same as running the old system tests except for the starting directory. The steps are:

  • Make sure the Selenium Server is running in the background.
  • Change directory to the tests/system/webdriver/tests folder.
  • Execute the command: phpunit

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.

Run Selected Webdriver Tests

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.

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. When you run the entire system test suite, the first test does a clean re-install for you automatically. This tests the installation and also makes sure the database is in an expected state.
  • If you find errors or failures when you run the tests, you can run the tests against the Joomla! master branch to see if the problems are in master or just in your branch.

Eclipse Users

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.