PhpUnit testing
This is documentation for the 7.1 version of Rogo. Release date to be confirmed.
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> <db_engine>The database table type you wish to run Rogo, it will default to the one your main Rogo site is installed on (optional)</db_engine> <db_help_engine>The database table type you wish to run the help system on, it will default to the one your main Rogo site is installed on (optional)</db_help_engine> </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
- Run the following command to run the test suite:
vendor/bin/phpunit -c testing/unittest/config/phpunit.xml
If you are developing a patch that makes changes to the Rogo database you will need to reinitialise your unit test database with the --clean option to ensure that it is in place.
php testing/unittest/cli/init.php --clean
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 { /** * Generate data for test. * @throws \testing\datagenerator\not_found */ public function datageneration() : void { // generate data with datagenerator functions } /** * 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
to query the database you simply use the query function:
The function takes an array as a parmater:
key | description | example |
---|---|---|
table | table we are selecting from | table' => 'test' |
orderby | order by columns | 'orderby' => array('c2') |
columns | columns we are interested in | 'columns' => array('c1','c2') |
where | filter to apply - an array (column, value, operator) | 'where' => array(array('column' => 'c2', 'value' => 1, 'operator' => '=') |
The function returns a results array you can use the phpunit assertEquals fucntion to comapre against an expected result set.
$querytable = $this->query(array('columns' => array('property_id', 'idMod'), 'table' => 'properties_modules')); // example result set array(0 => array( 'property_id' => 1, 'idMod' => 2 ), array( 'property_id' => 2, 'idMod' => 4 ), )
If you need to do more and wanted to access the rogo database object all you would have to do is use the $this->db
variable.
Base Datasets
Default data is loaded into the test database on every test run. This is the minimum data required by Rogo to function.
Datasets are implemented using YAML fixtures.
All base fixtures should be placed in the testing/fixtures/base
directory of rogo.
For example in the below function the academic year 2016/17 is created along with enroling the default student onto the default module in that academic year.
The default data generated by this dataset load can be access directly in unit tests with the following functions:
function | description | direct access in unit test |
---|---|---|
get_base_admin | returns user data (an array) for the default admin user | $this->admin |
get_base_student | returns user data (an array) for the default student user | $this->student |
get_base_module | returns user data (an array) for the default module | $this->module |
get_base_faculty | returns user data (an array) for the default faculty | $this->faculty |
get_base_school | returns user data (an array) for the default school | $this->school |
The internal rogo id can also be accessed for objects within the test database using the following functions:
function | description |
---|---|
get_user_id(name) | get the id of the user |
get_module_id(name) | get the id of the module |
get_faculty_id(name) | get the id of the faculty |
get_school_id(name) | get the id of the school |
The active user can be set using hte following function:
function | description |
---|---|
set_active_user(id, state, impersonate) | id = the user id state = USEROBJECT_DEEFAULT - standard user USEROBJECT_DEMO - user running in demo mode USEROBJECT_IMPERSONATE - user is impersonating someone else impersonate = the user id of the user to impersonate |
Data Generation
Each unit tests must implement the datageneration function. Within this function additional data is loaded into the tes database required by the test.
All data generators are in the testing/datagenerator/generator/core
directory of rogo.
For example in the below function the academic year 2016/17 is created along with enroling the default student onto the default module in that academic year.
/** * Generate data for test. * @throws \testing\datagenerator\not_found */ public function datageneration() : void { $datagenerator = $this->get_datagenerator('academic_year', 'core'); $datagenerator->create_academic_year(array('calendar_year' => 2016, 'academic_year' => '2016/17')); $datagenerator = $this->get_datagenerator('modules', 'core'); $datagenerator->create_enrolment(array('userid' => $this->student['id'], 'moduleid' => $this->module, 'calendar_year' => 2016)); }
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
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.