How to install and run

Installation

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:

   phpunit.xml

   Code Block
   language 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>

3. Run the following script from the command line: testing/unittest/cli/init.php

Running

...

php testing/unittest/cli/init.php --clean

Creating a unit test

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

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 ExamSys
//
// 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
    }
}

...

The group statement in the test_example phpdoc is useful when you only want to run tests on a specific part of ExamSys 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 ExamSys 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 returns a results array you can use the phpunit assertEquals fucntion to compare against an expected result set.

query function example

$querytable = $this->query(array('columns' => array('property_id', 'idMod'), 'table' => 'properties_modules'));

// example result set
[0 =>
	[
		'property_id' => 1,
		'idMod' => 2,
	],
	[
		'property_id' => 2,
		'idMod' => 4,
	],
]

If you need to do more and wanted to access the ExamSys 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 ExamSys to function.

...

Data Generation

Each unit tests must implement the datageneration function. Within this function additional data is loaded into the test database required by the test.

...

For example in the below function the academic year 2016/17 is created along with enrolling the default student onto the default module in that academic year.

Example datagenerator

/**
  * 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 unit tests?

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

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.

Additional information

• PHPUnit Documentation

• YAML

...