Unit testing

How to install and run


  1. Do a normal install on the machine you wish to test on. 
  2. Create a phpunit.xml file in your config directory. It should contain the following settings:

    <?xml version="1.0" encoding="UTF-8"?>
  3. Run the following script from the command line: testing/unittest/cli/init.php

Note for Windows users

You will need to install composer.phar into the root rogo directory manually from https://getcomposer.org/download/


Ensure the php module php_pdo_mysql is enabled

  1. Run the following command to run the test suite: vendor/bin/phpunit -c testing/unittest/config/phpunit.xml

Creating a unit test

All unit tests should be placed in the testing/unittest/tests directory of rogo.

The naming convention for the file is <classname>Test.php e.g. if we had a class example.class.php that would have a unit test exampleTest.php.

Writing a unit test

Carrying on the example from above the unit test itself would look like the following:

Example phpunit test
// This file is part of Rogō
// Rogō is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
// Rogō is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// GNU General Public License for more details.
// You should have received a copy of the GNU General Public License
// along with Rogō.  If not, see <http://www.gnu.org/licenses/>.

use testing\unittest\unittestdatabase;

 * Test package description
 * @author
 * @version
 * @copyright
 * @package tests
class exampletest extends unittestdatabase {
     * Get init data set from yml
     * @return dataset
    public function getDataSet() {
        return new PHPUnit_Extensions_Database_DataSet_YamlDataSet($this->get_base_fixture_directory() . "exampleTest" . DIRECTORY_SEPARATOR . "example.yml");
     * Description of logical function tested
     * @group example
    public function test_example_logicalfunction() {
		// test something

All unit tests should extend the unittestdatabase class. This is so phpunit can set-up and tear-down the test database, as well as give the test access to the rogo config and database objects.

The group statement in the test_example phpdoc is useful when you only want to run tests on a specifc part of rogo i.e. vendor/bin/phpunit --group example -c testing/unittest/config/phpunit.xml, would only run  the example unit tests.

Accessing the config object

In the test_example_logicalfunction if you wanted to access the rogo config object all you would have to do is use the $this->config variable.

Accessing the db object

In the test_example_logicalfunction if you wanted to access the rogo database object all you would have to do is use the $this->db variable.


To create datasets within the unit tests YAML fixtures are loaded during set-up. Fixtures can also be loaded during tests to check the current database state against its expected state.

When writing a unit test at the bare minimum the getDataSet function must be defined in order for phpunit to create the initial dataset.

All fixtures should be placed in a subdirectory of the testing/unittest/fixtures directory of rogo. The sub directory should be named after the test i.e. testing/unittest/fixtures/exampleTest.

When am I expected to write unittests?

Whenever you submit a pull request for a bug fix or a new feature to the develop branch it is expected that you also submit the relevant unit tests.

Code coverage

Useful information

The extension php5-xdebug is a requirement if you wish to use code coverage.

If you are interested in running code coverage on your unit tests the following needs to be added to testing/unittest/config/phpunit.xml

  <whitelist processUncoveredFilesFromWhitelist="true">
    <directory suffix=".class.php">PATH TO DIRECTORY</directory>
    <file>PATH TO FILE</file>
      <directory suffix=".class.php">PATH TO DIRECTORY</directory>
      <file>PATH TO FILE</file>
    <log type="coverage-html" target="PATH TO REPORT"/>

Note this is not in the repository version so please do not submit it during a pull request.

Additional information