Table of Contents
This page refers to VuFind 1.x; for notes on VuFind 2.x unit tests, see this page.
This page is aimed at developers who want to test that their changes have not broken existing VuFind functionality or who are interested in creating standard tests for new VuFind components. If you are interested in testing performance rather than functionality, see the Testing Performance page instead.
The test modules provided with VuFind use the PHPUnit testing framework. The framework can be installed using PEAR (see details on the project's homepage). Once installed, you will have a phpunit command line tool that you can use to run tests.
The VuFind unit tests can be found in the tests directory of your VuFind installation.
The layout of the tests directory is designed to mirror the main VuFind application. Tests should be placed in a directory that corresponds with the component being tested. For example, the tests for “web/sys/SolrUtils.php” are found in “tests/web/sys/SolrUtilsTest.php”.
Every directory of the tests directory should contain an AllTests.php file which runs all tests in that directory and in the directory's children. This means that you can add tests to a directory and have them automatically run as part of VuFind's test suite. However, there are two important notes related to this:
- If you add the first file to a directory, make sure that the directory's AllTests.php is set up to auto-load other tests. You can copy this logic from an existing AllTests.php file.
- If you add a new directory, make sure that AllTests.php in the new directory's parent is set up to load the new directory's AllTests.php, which you should create. This code can be copied from other existing AllTests.php examples.
Although most unit tests are intended to test individual features of an application (and this is a good practice whenever possible), VuFind's test suite also makes use of Selenium to perform integration testing of the entire application. These special integration tests are found in the Selenium subdirectory of VuFind's tests directory. Inside the Selenium directory, tests are separated into suites that test related functionality. If you need to create a new suite, just copy the AllTests.php file from one of the existing Selenium subdirectories and then edit the top-level Selenium AllTests.php file to incorporate the additional suite.
Setting up Selenium
In order for the Selenium tests to work, you need to install a couple extra pieces of software:
- You should download the latest version of the Selenium RC (remote control) package here. VuFind expects to find the server portion of the package in /usr/local/selenium – you may want to unpack the archive and then create a symbolic link from /usr/local/selenium to the appropriate selenium-server-xxx directory. (Note that as of this writing, 1.0.3 is the current version of Selenium RC).
- PHPunit has integrated selenium drivers and hence we extend the “PHPUnit_Extensions_SeleniumTestCase” class in our test classes.
Selenium tests will be run in a “headless” environment where the browser is launched and tests are run, but the X Window session doesn't actually render to any physical screen.The virtual frame buffer server “Xvfb” is needed for this and can be installed using the following command:
sudo apt-get install xvfb
To launch a new virtual frame buffer we bind it to display,and export the display variable.
Xvfb -ac :99 export DISPLAY=:99
To start selenium RC server, we fire the following command in the directory the selenium jar file exists :
java -jar selenium-server.jar
The firefox browser path need to be exported in the PATH and LD_LIBRARY_PATH variables.this can be added to the .profile file.
PATH : /usr/bin/firefox LD_LIBRARY_PATH : /usr/bin/firefox
Running Selenium Tests
A script “auto_test.sh” at path “/vufind/tests” contains the code to export the display variable for Xvfb, start the Xvfb ( Xframe buffer ) and also the Selenium RC server.
The auto_test.sh script is called from the build.xml file and is executed when phing.sh is started up.It brings up the Xframe buffer and the Selenium RC server.it records their Pids and when after the tests are completed,during phing.sh's shutdown,both the processes are shutdown.
For the purpose of testing we have a sample of 10 MARC format records which are imported into VUFIND at the beginning of the tests. Tests are fired against these records and at the end of the testing process, the records are deleted from the system.To ensure that the test records are distinctive, they carry a prefix “testsample#”.
The sample file “catalog_INCR-TEST_SAMPLE.mrc” is placed in “vufind/tests” directory.
Before you run the Selenium tests, you need to have a running instance of VuFind. There are some Phing tasks set up which will help you automate this process. The “startup” task spins up a VuFind instance for testing, and the “shutdown” task turns it off and cleans up after it.
These tasks make a couple of important assumptions:
- They only work under Linux; VuFind is not currently designed to be tested under Windows.
- They assume that you have an Ubuntu-style Apache setup, where configuration files can be dropped into a “conf.d” folder in order to be automatically included.
If you look at the top of the build.xml file in the root of VuFind, you will see that there are several parameters that you can override to make the tasks work on your local system. Any of these can be overridden from the command line using the “-D” switch. You may find it convenient to create a phing.sh script to save you the trouble of constantly retyping all of these settings. Here is an example, adapted from Demian's test server:
#!/bin/sh phing -Dapachectl="sudo /etc/init.d/apache2" -Dmysqlrootpass=mypasswd -Dvufindurl=http://localhost/vufind $*
Assuming you have this script in place in the root of your VuFind development directory, you can go through the testing process like this:
cd $VUFIND_HOME ./phing.sh startup phpunit tests/Selenium/AllTests.php ./phing.sh shutdown
Building a New Selenium Test
A base class has been created in tests/Selenium/lib/SeleniumTestCase.php which you can extend to create more tests. The base class takes care of connecting to Selenium for you so you only have to worry about the actual testing. You can look at existing Selenium tests to see how this works in action.
Bugs can be tested as part of continuous integration process. This will ensure that any new code didn't reverse the fix for a bug. The steps to add tests for Bugs is as follows:
Write the selenium-phpunit based test for the bug.
If the test needs a special MARC record to be reproduced, create one and preferably edit its ID value (in the 001 field) to “testbug#” where # will be your bug number.
Create a Directory with name “Bug#” under the existing directory called “Bugs” in
The directory name must start with word “Bug”, # is the number to identify the bug
In you Bug# directory place your unit test file and the MARC record (if any). It is recommended that you name your test class SeleniumBugTest# (where # matches the directory number).
Example :~/vufind/tests/Selenium/Bugs/Bug1$ ll -rwxr-xr-x 1 2096 2011-05-03 13:33 SeleniumBugTest1.php* --> Unit test for the Bug. -rwxr-xr-x 1 539 2011-05-10 12:34 heb.mrc* --> Marc record to the particular Bug.
If necessary, you may have more than one Unit test for a particular Bug or more than one MARC record too (i.e. SeleniumBugTest1a.php, SeleniumBugTest1b.php, etc.). The automated script will add all the tests and also import all the MARC files in a Bug directory.