How to install and run

Installation

Do a normal install on the machine you wish to test on.
Create a phpunit.xml file in your config directory. It should contain the following settings:
phpunit.xml
<?xml version="1.0" encoding="UTF-8"?> <rogo> <db_database>phpunit_database_schema_name</db_database> <db_user>username</db_user> <db_password>password</db_password> <data>path_to_user_data_directory</data> </rogo>
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/

Running

Ensure the php module php_pdo_mysql is enabled

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

<?php
// 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
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// 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.

Datasets

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

phpunit.xml

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

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

Unit testing