6. Unit Tests

6.1. Introduction

Unit tests are an important componant in the CartoWeb development environment. The framework used for unit testing is based on PHPUnit2, a PEAR package. For more informations abouth PHPUnit2, see http://pear.php.net/reference/PHPUnit2-2.0.3/

PHPUnit2 is included in the libraries shipped with CartoWeb. Thus, no installation is needed to run and write new tests.

6.2. Writing Tests

Information about writing tests for CartoWeb can be separated into two parts. First part about writing Unit tests in general, useful for people new to PhpUnit. Then a part more specific about the infrastructure which is available in CartoWeb for writing tests.

6.2.1. General Information About Writing Tests

Test cases are located in directory tests, in a similar structure as the root directory:

client
    CartoclientTest.php
    CartoserverServiceTest.php
    AllTests.php
common
    BasicTypesTest.php
    AllTests.php
coreplugins
    AllTests.php
    ...
plugins
    AllTests.php
    ...
projects
    < all test for projects >
    ...
...
AllTests.php

Each directory including tests root directory has a file named AllTests.php. This is called a test suite. It is used to run all tests of a specific directory (ie "package").

Warning

All test case and test suite classes must have the name of their file relative path without extension, with '/' replaced by '_'. For instance, class client_CartoclientTest file name must be <cartoweb3_root>/tests/client/CartoclientTest.php.

The following example shows a test in common/BasicTypeTest.php file:

Example 6.1. Simple test case (BasicTypesTests.php)

<?php
require_once 'PHPUnit2/Framework/TestCase.php';
require_once(CARTOCLIENT_HOME . 'common/basic_types.php');

class common_BasicTypesTest extends PHPUnit2_Framework_TestCase {

        public function testBboxFrom2Points() {

                $bbox = new Bbox();
                $point1 = new Point(12, 34);
                $point2 = new Point(56, 78);
                $bbox->SetFrom2Points($point1, $point2);

                $this->assertEquals(12, $bbox->minx);
                $this->assertEquals(34, $bbox->miny);
                $this->assertEquals(56, $bbox->maxx);
                $this->assertEquals(78, $bbox->maxy);
        }
}
?>

Each function with name starting with 'test' will be considered as a test case by the automated test runner. You may also want to use functions setUp() and tearDown() to initialize and clean a test environment.

Method assertEquals tests if two values have the same values. If not, the test will be added to the final report as failure.

As stated previously, all test classes have to belong to a test suite. The next example shows how such a test suite is built, by grouping all tests together in the suite() method.

Example 6.2.  Test suite (AllTests.php)

<?php

require_once 'PHPUnit2/Framework/TestSuite.php';
require_once 'CartoclientTest.php';
require_once 'CartoserverServiceTest.php';

class client_AllTests {

        public static function suite() {

                $suite = new PHPUnit2_Framework_TestSuite;

                $suite->addTestSuite('client_CartoclientTest');
                $suite->addTestSuite('client_CartoserverServiceTest');

                return $suite;
        }
}
?>

All test suites are then grouped together into the root test suite. It is shown there for information.

Example 6.3.  Root directory's AllTests.php:

<?php

require_once 'PHPUnit2/Framework/TestSuite.php';
require_once 'client/AllTests.php';
require_once 'common/AllTests.php';

class AllTests {

        public static function suite() {

                $suite = new PHPUnit2_Framework_TestSuite;

                $suite->addTest(client_AllTests::suite());
                $suite->addTest(common_AllTests::suite());

                return $suite;
        }
}
?>

6.2.2. Specific Information for Tests

This section describes specific features developped in CartoWeb for running tests, and infrastructure classes for more simple test case writing.

6.2.2.1. HttpUnit Based Tests

To test features of the cartoclient, the HttpUnit software is used. It is written in Java, and there is no Php port. The http unit tests are run if you have a JVM in you path.

For more information about running HttpUnit tests, see the tests/client/httpunit/README file in the CartoWeb distribution.

6.2.2.2. Testing CartoWeb Plugins

Plugins are a main component in CartoWeb architecture. That's why there is support to maintain common code used for testing plugins. As described in Section 6.2.1, “General Information About Writing Tests” the tests for plugins have to mirror the file hierarchy of the base application. That's why there are coreplugins and plugins directories where test for core plugins and plugins are stored respectively.

Note

Tests are also available for projects. So, to test a plugin in a project, the path of the test will be <projectname>/plugin/<pluginname>

Testing plugins is separated into two tasks:

  1. Locally testing client, common or server classes. For plugin client classes, it requires a CartoClient environment available, and identically a CartoServer environment for testing server classes.
  2. Remote plugin tests, throught the webservice API. This kind of tests are related to the server plugins, that's why we chose to put them in the server folder of plugins.

For the first point mentionned above, general Unit tests rules apply, as described in Section 6.2.1, “General Information About Writing Tests”.

For the second point stated, a help class named client_CartoserverServiceTest can be extended by the testing classes. In turn, client_CartoserverServiceTest extends other classes which offer additional helpful methods. For the complete list of available methods, please have a look at the generate API docs (as more may be added in future). The main useful methods are createRequest() for initializing a new request, getMap() for lanching the request.

Tip

Having a look at an existing plugin test case is the best starting point for writing new tests.

6.3. Running Tests

Running tests is possible in two different ways:

  1. With command line.
  2. Through the web interface.

6.3.1. Command Line Interface

To run a test case or a test suite, type the following command in directory <cartoweb3_root>/tests:

<php-bin> phpunit.php <test-class>

Where <php-bin> is the PHP binary and <test-class> is the name of the test class (AllTests, client_AllTests, client_CartoclientTest, etc.).

Result should look like this:

PHPUnit 2.0.3 by Sebastian Bergmann.

.......F.....

Time: 0.0410950183868
There was 1 failure:
1) testpointtobbox
expected same: <113> was not: <123>
/home/yves/cartoweb3-proto2/tests/common/BasicTypesTest.php:59
/home/yves/cartoweb3-proto2/tests/phpunit.php:24

FAILURES!!!
Tests run: 12, Failures: 1, Errors: 0, Incomplete Tests: 0.
Content-type: text/html
X-Powered-By: PHP/5.0.1

In this case, 12 tests were run with one failure.

6.3.2. Web Interface

The web interface for running test is available at the address /runtests.php from the CartoWeb base path. It is possible to give a GET parameter named testsuite, which accepts the same parameter as the command line argument described in Section 6.3.1, “Command Line Interface”.

Important

To allow the web interface to be used, the configuration parameter allowTests has to be set to true. See FIXME_ADD_LINK about the configuration of these parameters.