This space is archived
For current information please use the current ExamSys documentation
Unit testing
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:
<?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
If you are interested in running code coverage on your unit tests the following needs to be added to testing/unittest/config/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.