Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

PHPUnit: Difference between revisions

From MoodleDocs
(Link to composer download page so the instructions for installing composer are always up to date.)
m (Protected "PHPUnit": Developer Docs Migration ([Edit=Allow only administrators] (indefinite)))
 
(18 intermediate revisions by 10 users not shown)
Line 1: Line 1:
{{Template:Migrated|newDocId=/general/development/tools/phpunit}}
{{Moodle 2.3}}
{{Moodle 2.3}}
=What is PHPUnit=
=What is PHPUnit=
PHPUnit by Sebastian Bergmann is an advanced unit testing framework for PHP. It is installed as Composer dependency and is not part of Moodle installation. To run PHPUnit tests, you have to manually install it on your development computer or test server.
PHPUnit by Sebastian Bergmann is an advanced unit testing framework for PHP. It is installed as Composer dependency and is not part of Moodle installation. To run PHPUnit tests, you have to manually install it on your development computer or test server.


Read the excellent guide at
Read the excellent guide at
* [http://phpunit.de/manual/current/en/index.html PHPUnit Manual]
* [https://phpunit.de/documentation.html PHPUnit Manual]
 
=Installation of PHPUnit via Composer=
=Installation of PHPUnit via Composer=
* Install Composer
* Install Composer
Instructions for installing composer on all platforms are here: https://getcomposer.org/download/
Instructions for installing composer on all platforms are here: https://getcomposer.org/download/
https://getcomposer.org/download/


Install the composer.phar file to your moodle folder.
* Execute Composer installer
* Execute Composer installer
  cd /your/moodle/dirroot
  cd /your/moodle/dirroot


  php composer.phar install
  php composer.phar install
(If that gives you connection problems try...)
(If that gives you connection problems try...)
  php composer.phar install --prefer-source
  php composer.phar install --prefer-source
Troubleshooting:
Troubleshooting:
* On Windows if you are behind a proxy you will need to setup an environment variable called HTTP_PROXY with a value detailing your HTTP Proxy address and port before composer will correctly download files.
* On Windows if you are behind a proxy you will need to setup an environment variable called HTTP_PROXY with a value detailing your HTTP Proxy address and port before composer will correctly download files.
Line 36: Line 29:
Detailed instructions:
Detailed instructions:
* [http://getcomposer.org/doc/00-intro.md Composer documentation]
* [http://getcomposer.org/doc/00-intro.md Composer documentation]
Detailed instructions:
Detailed instructions:
* [[PHPUnit installation in Windows]]
* [[PHPUnit installation in Windows]]
* [[PHPUnit installation in OS X]]
* [[PHPUnit installation in OS X]]
== Uninstalling previous PEAR based version ==
== Uninstalling previous PEAR based version ==
Before using composer, this page used to suggest to install phpunit via PEAR. If you did so, you may wish to uninstall that package now. This should work:
Before using composer, this page used to suggest to install phpunit via PEAR. If you did so, you may wish to uninstall that package now. This should work:
   $ pear uninstall phpunit/DbUnit
   $ pear uninstall phpunit/DbUnit
   $ pear uninstall phpunit/PHPUnit
   $ pear uninstall phpunit/PHPUnit
= PHPUnit versions =
The following table shows what PHPUnit version is installed in which Moodle version when using the default composer setup.
{| class="wikitable" border="1"
|-
! Moodle version
! PHPUnit version
!Links
|-
| Moodle 3.11 - 4.0
| PHPUnit 9.5
|[https://phpunit.readthedocs.io/en/9.5/ Documentation]
|-
| Moodle 3.10
| PHPUnit 8.5
|[https://phpunit.readthedocs.io/en/8.5/ Documentation]
|-
| Moodle 3.7 - 3.9
| PHPUnit 7.5
|[https://phpunit.readthedocs.io/en/7.5/ Documentation]
|-
| Moodle 3.4 - 3.6
| PHPUnit 6.5
|[https://phpunit.de/manual/6.5/en/ Documentation]
|-
| Moodle 3.2 - 3.3
| PHPUnit 5.5
|[https://phpunit.de/manual/5.5/en/ Documentation]
|-
| Moodle 3.1
| PHPUnit 4.8.27
|[https://phpunit.de/manual/4.8/en/ Documention 4.8]
|}


=Initialisation of test environment=
=Initialisation of test environment=
 
Our PHPUnit integration requires a dedicated database and dataroot. First, add a new dataroot directory and prefix into your config.php, you can find examples in config-dist.php (scroll down to 'Section 9').
Our PHPUnit integration requires a dedicated database and dataroot. First, add a new dataroot directory and prefix into your config.php, you can find examples in config-dist.php (scroll down to 'Section 9').
 
  $CFG->phpunit_prefix = 'phpu_';
  $CFG->phpunit_prefix = 'phpu_';
  $CFG->phpunit_dataroot = '/home/example/phpu_moodledata';
  $CFG->phpunit_dataroot = '/home/example/phpu_moodledata';
Some PHPUnit tests require a live internet connection. If your system does not have a direct connection to the Internet, you also need to specify your proxy in config.php - even though you normally specify it by using the admin settings user interface. (If you do not use a proxy, you can skip this step.) Check the settings on the relevant admin settings page, or from the mdl_config table in your database, if you are unsure of the correct values.
Some PHPUnit tests require a live internet connection. If your system does not have a direct connection to the Internet, you also need to specify your proxy in config.php - even though you normally specify it by using the admin settings user interface. (If you do not use a proxy, you can skip this step.) Check the settings on the relevant admin settings page, or from the mdl_config table in your database, if you are unsure of the correct values.
  // Normal proxy settings
  // Normal proxy settings
  $CFG->proxyhost = 'wwwcache.example.org';
  $CFG->proxyhost = 'wwwcache.example.org';
Line 65: Line 82:
  $CFG->proxyuser = 'systemusername';
  $CFG->proxyuser = 'systemusername';
  $CFG->proxypassword = 'systempassword';
  $CFG->proxypassword = 'systempassword';
From Moodle 2.8.5 onwards, you can also provide specific database settings for unit testing (if these are not provided, the standard database settings will be used):
From Moodle 2.8.5 onwards, you can also provide specific database settings for unit testing (if these are not provided, the standard database settings will be used):
<pre>$CFG->phpunit_dbtype    = 'pgsql';      // 'pgsql', 'mariadb', 'mysqli', 'mssql', 'sqlsrv' or 'oci'
<pre>$CFG->phpunit_dbtype    = 'pgsql';      // 'pgsql', 'mariadb', 'mysqli', 'mssql', 'sqlsrv' or 'oci'
$CFG->phpunit_dblibrary = 'native';    // 'native' only at the moment
$CFG->phpunit_dblibrary = 'native';    // 'native' only at the moment
Line 74: Line 89:
$CFG->phpunit_dbuser    = 'postgres';  // your database username
$CFG->phpunit_dbuser    = 'postgres';  // your database username
$CFG->phpunit_dbpass    = 'some_password';  // your database password</pre>
$CFG->phpunit_dbpass    = 'some_password';  // your database password</pre>
Then you need to initialise the test environment using following command.
Then you need to initialise the test environment using following command.
  cd /home/example/moodle
  cd /home/example/moodle
  php admin/tool/phpunit/cli/init.php
  php admin/tool/phpunit/cli/init.php
This command has to be repeated after any upgrade, plugin (un)installation or if you have added tests to a plugin you are developing:
This command has to be repeated after any upgrade, plugin (un)installation or if you have added tests to a plugin you are developing:


'''NOTE:''' make sure that your php cli executable (or the one you want to use) is correctly on your path as the individual init scripts will call it repeatedly. Also, ensure en_AU locale is installed on your server.
'''NOTE:''' make sure that your php cli executable (or the one you want to use) is correctly on your path as the individual init scripts will call it repeatedly. Also, ensure en_AU locale is installed on your server.
== LDAP ==
== LDAP ==
If you want to run LDAP unit tests you must have a working, configured LDAP environment on your test server. There must be a basic LDAP tree structure in place or tests will fail with "Search: No such object". Build an LDAP tree structure in a new shell prompt:
If you want to run LDAP unit tests you must have a working, configured LDAP environment on your test server. There must be a basic LDAP tree structure in place or tests will fail with "Search: No such object". Build an LDAP tree structure in a new shell prompt:
<pre>
<pre>
$ ldapadd -H ldap://127.0.0.1 -D "cn=admin,dc=yourcomputer,dc=local" -W
$ ldapadd -H ldap://127.0.0.1 -D "cn=admin,dc=yourcomputer,dc=local" -W
Line 95: Line 105:
ou:YOURCOMPUTER
ou:YOURCOMPUTER
</pre>
</pre>
In config.php tell Moodle where to look for your test LDAP environment:
In config.php tell Moodle where to look for your test LDAP environment:
<pre>
<pre>
// Constants for auth/ldap tests.
// Constants for auth/ldap tests.
Line 117: Line 125:
define('TEST_LDAPLIB_DOMAIN', 'dc=yourcomputer,dc=local');
define('TEST_LDAPLIB_DOMAIN', 'dc=yourcomputer,dc=local');
</pre>
</pre>
=Test execution=
=Test execution=
 
To execute all test suites from main configuration file execute the <syntaxhighlight lang="php">vendor/bin/phpunit</syntaxhighlight> script from your <syntaxhighlight lang="php">$CFG->dirroot</syntaxhighlight> directory.
To execute all test suites from main configuration file execute the <code>vendor/bin/phpunit</code> script from your <code>$CFG->dirroot</code> directory.
 
  cd /home/example/moodle
  cd /home/example/moodle
  vendor/bin/phpunit
  vendor/bin/phpunit
The rest of examples uses <syntaxhighlight lang="php">phpunit</syntaxhighlight>, please substitute it with <syntaxhighlight lang="php">vendor/bin/phpunit</syntaxhighlight> or create a shortcut in your dirroot.
In IDEs, you may need to specify the path to the PHPUnit configuration file. Use the absolute path to <syntaxhighlight lang="php">phpunit.xml</syntaxhighlight> from your <syntaxhighlight lang="php">$CFG->dirroot</syntaxhighlight>.


The rest of examples uses <code>phpunit</code>, please substitute it with <code>vendor/bin/phpunit</code> or create a shortcut in your dirroot.


In IDEs, you may need to specify the path to the PHPUnit configuration file. Use the absolute path to <code>phpunit.xml</code> from your <code>$CFG->dirroot</code>.
There is an alternative script for running of tests via web interface: <syntaxhighlight lang="php">admin/tool/phpunit/webrunner.php</syntaxhighlight>. Use this as the last resort only when you cannot use the command-line interface on your test server. It will most probably break due to permissions problems if you try to execute it both from command-line and from webrunner. This feature is not officially supported.
 
 
There is an alternative script for running of tests via web interface: <code>admin/tool/phpunit/webrunner.php</code>. Use this as the last resort only when you cannot use the command-line interface on your test server. It will most probably break due to permissions problems if you try to execute it both from command-line and from webrunner. This feature is not officially supported.




===How to run only some tests===
===How to run only some tests===
==== Running a single test quickly (PHPUnit 9) ====
{{Moodle 3.11}}
The fastest way to run a single test in PHPUnit 9.5 and higher (Moodle 3.11 and higher) is to use the filter argument:
<syntaxhighlight lang="bash">
vendor/bin/phpunit --filter tool_dataprivacy_metadata_registry_testcase
</syntaxhighlight>
To run all tests provided by the single component, use suite and the name it has in the phpunit.xml file. Example:
<syntaxhighlight lang="bash">
vendor/bin/phpunit --testsuite workshopform_accumulative_testsuite
</syntaxhighlight>
Alternatively if you have config files built for each component:
<syntaxhighlight lang="bash">
vendor/bin/phpunit -c mod/workshop/form/accumulative/
</syntaxhighlight>
==== Running a single test quickly (PHPUnit 8) ====
{{Moodle 3.10}}
The fastest way to run a single test in PHPUnit 8.5 and lower (Moodle 3.10 and lower):
<syntaxhighlight lang="bash">
vendor/bin/phpunit my/tests/filename.php
</syntaxhighlight>
so, run this command in the CLI to see a real test in action:
<syntaxhighlight lang="bash">
vendor/bin/phpunit cohort/tests/cohortlib_test.php
</syntaxhighlight>
You can also run a single test method inside a class:
<syntaxhighlight lang="bash">
vendor/bin/phpunit --filter test_function_name path/to/file.php
</syntaxhighlight>
Note: You should be careful because it may be possible to run tests this way which are not included in the normal run if, for example, the file is not placed in the correct location. If you use this method, do at least one full test run (or --group run, as below) to ensure the test can be found.


==== Running a single test quickly ====
Filters can also be applied to capture a group of similar tests across all testsuites:
 
<syntaxhighlight lang="bash">
The fastest way to run a single test is:
vendor/bin/phpunit --filter test_flag_user
 
</syntaxhighlight>
vendor/bin/phpunit my_test_class_name my/tests/filename.php
It is also possible to run all tests in a component (subsystem or plugin) by using the testsuite option:
 
<syntaxhighlight lang="bash">
This is faster than other methods because it avoids the need to search for the test file, but you should be careful because it may be possible to run tests this way which are not included in the normal run. If you use this method, do at least one full test run (or --group run, as below) to ensure the test can be found.
vendor/bin/phpunit --testsuite mod_forum_testsuite
 
vendor/bin/phpunit --testsuite core_privacy_testsuite
Please note the path name is optional if the testcase class and file names are standardised as described in [[Writing PHPUnit tests]].
vendor/bin/phpunit --testsuite core_privacy_testsuite --filter test_component_is_compliant
 
</syntaxhighlight>
==== Using the @group annotation ====
==== Using the @group annotation ====
If you add annotations like
If you add annotations like
 
<syntaxhighlight lang="php">
<code php>
namespace qtype_stack;
/**
/**
  * Unit tests for {@link stack_cas_keyval}.
  * Unit tests for {@link stack_cas_keyval} @ qtype/stack/tests/cas_keyval_test.php.
  * @group qtype_stack
  * @group qtype_stack
  */
  */
class qtype_stack_cas_keyval_exception_testcase extends basic_testcase {
class cas_keyval_test extends \basic_testcase {
</code>
</syntaxhighlight>
 
to all the classes in your plugin, then you can run just the tests for your plugin by doing
to all the classes in your plugin, then you can run just the tests for your plugin by doing
  phpunit --group qtype_stack
  phpunit --group qtype_stack
Therefore, it is suggested that you annotate all your tests with the Frankenstyle name of your plugin.
Therefore, it is suggested that you annotate all your tests with the Frankenstyle name of your plugin.
==== Using multiple phpunit.xml files ====
==== Using multiple phpunit.xml files ====
It's easy to create alternative phpunit.xml files defining which tests must be run together. For reference, take a look to the default /phpunit.xml available in your base directory once the testing environment has been initialised. After creating the custom file you will be able to run those tests with
It's easy to create alternative phpunit.xml files defining which tests must be run together. For reference, take a look to the default /phpunit.xml available in your base directory once the testing environment has been initialised. After creating the custom file you will be able to run those tests with
  vendor/bin/phpunit -c path/to/your/alternative/phpunit/file.xml
  vendor/bin/phpunit -c path/to/your/alternative/phpunit/file.xml
Also, for commodity, you can use this command:
Also, for commodity, you can use this command:
  php admin/tool/phpunit/cli/util.php --buildcomponentconfigs
  php admin/tool/phpunit/cli/util.php --buildcomponentconfigs
It will, automatically, create one valid phpunit.xml file within each component (plugin or subsystem) and other important directories, so later you will be able to execute tests like
It will, automatically, create one valid phpunit.xml file within each component (plugin or subsystem) and other important directories, so later you will be able to execute tests like
  vendor/bin/phpunit -c mod/forum[/phpunit.xml]  // Note that it's not needed to specify the name of the file (if it is 'phpunit.xml').
  vendor/bin/phpunit -c mod/forum[/phpunit.xml]  // Note that it's not needed to specify the name of the file (if it is 'phpunit.xml').
  vendor/bin/phpunit -c question
  vendor/bin/phpunit -c question
Line 181: Line 202:
  vendor/bin/phpunit -c lib/dml
  vendor/bin/phpunit -c lib/dml
  ...
  ...
or, also
or, also
  cd directory/with/phpunit.xml
  cd directory/with/phpunit.xml
  phpunit
  phpunit
=External test resources=
=External test resources=
{{Moodle 2.6}}
{{Moodle 2.6}}
By default Moodle phpunit tests contact http://download.moodle.org server when testing curl related functionality. Optionally you may checkout a local copy of the test scripts and access it instead:
By default Moodle phpunit tests contact http://download.moodle.org server when testing curl related functionality. Optionally you may checkout a local copy of the test scripts and access it instead:
# clone https://github.com/moodlehq/moodle-exttests to web directory
# clone https://github.com/moodlehq/moodle-exttests to web directory
# add to your config.php or modify phpunit.xml file <code php>define('TEST_EXTERNAL_FILES_HTTP_URL', 'http://localhost/moodle-exttests');</code>
# add to your config.php or modify phpunit.xml file <syntaxhighlight lang="php">define('TEST_EXTERNAL_FILES_HTTP_URL', 'http://localhost/moodle-exttests');</syntaxhighlight>
 
=Writing new tests=
=Writing new tests=
* read [http://www.phpunit.de/manual/current/en/ official PHPUnit online documentation]
* read [http://www.phpunit.de/manual/current/en/ official PHPUnit online documentation]
* see [[Writing PHPUnit tests]]
* see [[Writing PHPUnit tests]]
=Conversion of existing SimpleTests=
=Conversion of existing SimpleTests=
* see [[SimpleTest conversion]]
* see [[SimpleTest conversion]]
=PHPUnit support in IDEs=
=PHPUnit support in IDEs=
* [[Setting up Eclipse]]
* [[Setting up Eclipse]]
* [[Setting up Netbeans]]
* [[Setting up Netbeans]]
* [[Setting up PhpStorm]]
* [[Setting up PhpStorm]]
=Common Unit Test Problems=
=Common Unit Test Problems=
[[Common unit test problems]]
[[Common unit test problems]]
=Performance=
=Performance=
A typical run of full PHPUnit tests for Moodle 2.7 takes 10-20 minutes depending on the machine. If tests run slowly for you:
A typical run of full PHPUnit tests for Moodle 2.7 takes 10-20 minutes depending on the machine. If tests run slowly for you:
* Ensure you are using a database and filesystem running on the same machine that is running the tests (not on a remote server).
* Ensure you are using a database and filesystem running on the same machine that is running the tests (not on a remote server).
* Apply developer-only performance settings to your database: [[Postgres Tuning For Developers]]
* Apply developer-only performance settings to your database: [[Postgres Tuning For Developers]]
=Command line tips=
=Command line tips=
* Run all tests for a plugin (mod_mymodule in this example): vendor/bin/phpunit --testsuite=mod_mymodule_testsuite  
* Run all tests for a plugin (mod_mymodule in this example): vendor/bin/phpunit --testsuite=mod_mymodule_testsuite  
* Run only named test: vendor/bin/phpunit --filter=test_my_test_function_name
* Run only named test: vendor/bin/phpunit --filter=test_my_test_function_name
* Display each test name before running it (useful e.g. if it crashes before the end and you want to know which test it was running at that point) vendor/bin/phpunit --debug (you will probably want to redirect this to a file as it gets very long).
* Display each test name before running it (useful e.g. if it crashes before the end and you want to know which test it was running at that point) vendor/bin/phpunit --debug (you will probably want to redirect this to a file as it gets very long).
[[Category:Unit testing]]


[[Category:Unit testing]]
[[ja:PHPUnit]]

Latest revision as of 05:33, 29 June 2022

Important:

This content of this page has been updated and migrated to the new Moodle Developer Resources. The information contained on the page should no longer be seen up-to-date.

Why not view this page on the new site and help us to migrate more content to the new site!

Moodle 2.3

What is PHPUnit

PHPUnit by Sebastian Bergmann is an advanced unit testing framework for PHP. It is installed as Composer dependency and is not part of Moodle installation. To run PHPUnit tests, you have to manually install it on your development computer or test server.

Read the excellent guide at

Installation of PHPUnit via Composer

  • Install Composer

Instructions for installing composer on all platforms are here: https://getcomposer.org/download/

Install the composer.phar file to your moodle folder.

  • Execute Composer installer
cd /your/moodle/dirroot
php composer.phar install

(If that gives you connection problems try...)

php composer.phar install --prefer-source

Troubleshooting:

  • On Windows if you are behind a proxy you will need to setup an environment variable called HTTP_PROXY with a value detailing your HTTP Proxy address and port before composer will correctly download files.
  • You may be prompted for github credentials when installing composer dependencies.
    • This is used to generate an personal access token to avoid being rate limited by github.
    • If you have Two Factor Authentication enabled on your github account, or do not wish to supply your own credentials you will need to generate a token manually:
    • ( See composer issue #2280 for further details of this bug.)


Detailed instructions:

Detailed instructions:

Uninstalling previous PEAR based version

Before using composer, this page used to suggest to install phpunit via PEAR. If you did so, you may wish to uninstall that package now. This should work:

  $ pear uninstall phpunit/DbUnit
  $ pear uninstall phpunit/PHPUnit

PHPUnit versions

The following table shows what PHPUnit version is installed in which Moodle version when using the default composer setup.

Moodle version PHPUnit version Links
Moodle 3.11 - 4.0 PHPUnit 9.5 Documentation
Moodle 3.10 PHPUnit 8.5 Documentation
Moodle 3.7 - 3.9 PHPUnit 7.5 Documentation
Moodle 3.4 - 3.6 PHPUnit 6.5 Documentation
Moodle 3.2 - 3.3 PHPUnit 5.5 Documentation
Moodle 3.1 PHPUnit 4.8.27 Documention 4.8

Initialisation of test environment

Our PHPUnit integration requires a dedicated database and dataroot. First, add a new dataroot directory and prefix into your config.php, you can find examples in config-dist.php (scroll down to 'Section 9').

$CFG->phpunit_prefix = 'phpu_';
$CFG->phpunit_dataroot = '/home/example/phpu_moodledata';

Some PHPUnit tests require a live internet connection. If your system does not have a direct connection to the Internet, you also need to specify your proxy in config.php - even though you normally specify it by using the admin settings user interface. (If you do not use a proxy, you can skip this step.) Check the settings on the relevant admin settings page, or from the mdl_config table in your database, if you are unsure of the correct values.

// Normal proxy settings
$CFG->proxyhost = 'wwwcache.example.org';
$CFG->proxyport = 80;
$CFG->proxytype = 'HTTP';
$CFG->proxybypass = 'localhost, 127.0.0.1, .example.org';
// Omit the next lines if your proxy doesn't need a username/password:
$CFG->proxyuser = 'systemusername';
$CFG->proxypassword = 'systempassword';

From Moodle 2.8.5 onwards, you can also provide specific database settings for unit testing (if these are not provided, the standard database settings will be used):

$CFG->phpunit_dbtype    = 'pgsql';      // 'pgsql', 'mariadb', 'mysqli', 'mssql', 'sqlsrv' or 'oci'
$CFG->phpunit_dblibrary = 'native';     // 'native' only at the moment
$CFG->phpunit_dbhost    = '127.0.0.1';  // eg 'localhost' or 'db.isp.com' or IP
$CFG->phpunit_dbname    = 'mytestdb';     // database name, eg moodle
$CFG->phpunit_dbuser    = 'postgres';   // your database username
$CFG->phpunit_dbpass    = 'some_password';   // your database password

Then you need to initialise the test environment using following command.

cd /home/example/moodle
php admin/tool/phpunit/cli/init.php

This command has to be repeated after any upgrade, plugin (un)installation or if you have added tests to a plugin you are developing:

NOTE: make sure that your php cli executable (or the one you want to use) is correctly on your path as the individual init scripts will call it repeatedly. Also, ensure en_AU locale is installed on your server.

LDAP

If you want to run LDAP unit tests you must have a working, configured LDAP environment on your test server. There must be a basic LDAP tree structure in place or tests will fail with "Search: No such object". Build an LDAP tree structure in a new shell prompt:

$ ldapadd -H ldap://127.0.0.1 -D "cn=admin,dc=yourcomputer,dc=local" -W
dn:dc=yourcomputer,dc=local
objectClass:dcObject
objectClass:organizationalUnit
dc:yourcomputer
ou:YOURCOMPUTER

In config.php tell Moodle where to look for your test LDAP environment:

// Constants for auth/ldap tests.
define('TEST_AUTH_LDAP_HOST_URL', 'ldap://127.0.0.1');
define('TEST_AUTH_LDAP_BIND_DN', 'cn=admin,dc=yourcomputer,dc=local');
define('TEST_AUTH_LDAP_BIND_PW', '*');
define('TEST_AUTH_LDAP_DOMAIN', 'dc=yourcomputer,dc=local');

// Constants for enrol/ldap tests.
define('TEST_ENROL_LDAP_HOST_URL', 'ldap://127.0.0.1');
define('TEST_ENROL_LDAP_BIND_DN', 'cn=admin,dc=yourcomputer,dc=local');
define('TEST_ENROL_LDAP_BIND_PW', '*');
define('TEST_ENROL_LDAP_DOMAIN', 'dc=yourcomputer,dc=local');

// Constants for lib/ldap tests.
define('TEST_LDAPLIB_HOST_URL', 'ldap://127.0.0.1');
define('TEST_LDAPLIB_BIND_DN', 'cn=admin,dc=yourcomputer,dc=local');
define('TEST_LDAPLIB_BIND_PW', '*');
define('TEST_LDAPLIB_DOMAIN', 'dc=yourcomputer,dc=local');

Test execution

To execute all test suites from main configuration file execute the

vendor/bin/phpunit

script from your

$CFG->dirroot

directory.

cd /home/example/moodle
vendor/bin/phpunit

The rest of examples uses

phpunit

, please substitute it with

vendor/bin/phpunit

or create a shortcut in your dirroot. In IDEs, you may need to specify the path to the PHPUnit configuration file. Use the absolute path to

phpunit.xml

from your

$CFG->dirroot

.


There is an alternative script for running of tests via web interface:

admin/tool/phpunit/webrunner.php

. Use this as the last resort only when you cannot use the command-line interface on your test server. It will most probably break due to permissions problems if you try to execute it both from command-line and from webrunner. This feature is not officially supported.


How to run only some tests

Running a single test quickly (PHPUnit 9)

Moodle 3.11

The fastest way to run a single test in PHPUnit 9.5 and higher (Moodle 3.11 and higher) is to use the filter argument:

vendor/bin/phpunit --filter tool_dataprivacy_metadata_registry_testcase

To run all tests provided by the single component, use suite and the name it has in the phpunit.xml file. Example:

vendor/bin/phpunit --testsuite workshopform_accumulative_testsuite

Alternatively if you have config files built for each component:

vendor/bin/phpunit -c mod/workshop/form/accumulative/

Running a single test quickly (PHPUnit 8)

Moodle 3.10

The fastest way to run a single test in PHPUnit 8.5 and lower (Moodle 3.10 and lower):

vendor/bin/phpunit my/tests/filename.php

so, run this command in the CLI to see a real test in action:

vendor/bin/phpunit cohort/tests/cohortlib_test.php

You can also run a single test method inside a class:

vendor/bin/phpunit --filter test_function_name path/to/file.php

Note: You should be careful because it may be possible to run tests this way which are not included in the normal run if, for example, the file is not placed in the correct location. If you use this method, do at least one full test run (or --group run, as below) to ensure the test can be found.

Filters can also be applied to capture a group of similar tests across all testsuites:

vendor/bin/phpunit --filter test_flag_user

It is also possible to run all tests in a component (subsystem or plugin) by using the testsuite option:

vendor/bin/phpunit --testsuite mod_forum_testsuite
vendor/bin/phpunit --testsuite core_privacy_testsuite
vendor/bin/phpunit --testsuite core_privacy_testsuite --filter test_component_is_compliant

Using the @group annotation

If you add annotations like

namespace qtype_stack;
/**
 * Unit tests for {@link stack_cas_keyval} @ qtype/stack/tests/cas_keyval_test.php.
 * @group qtype_stack
 */
class cas_keyval_test extends \basic_testcase {

to all the classes in your plugin, then you can run just the tests for your plugin by doing

phpunit --group qtype_stack

Therefore, it is suggested that you annotate all your tests with the Frankenstyle name of your plugin.

Using multiple phpunit.xml files

It's easy to create alternative phpunit.xml files defining which tests must be run together. For reference, take a look to the default /phpunit.xml available in your base directory once the testing environment has been initialised. After creating the custom file you will be able to run those tests with

vendor/bin/phpunit -c path/to/your/alternative/phpunit/file.xml

Also, for commodity, you can use this command:

php admin/tool/phpunit/cli/util.php --buildcomponentconfigs

It will, automatically, create one valid phpunit.xml file within each component (plugin or subsystem) and other important directories, so later you will be able to execute tests like

vendor/bin/phpunit -c mod/forum[/phpunit.xml]  // Note that it's not needed to specify the name of the file (if it is 'phpunit.xml').
vendor/bin/phpunit -c question
vendor/bin/phpunit -c question/type/calculated
vendor/bin/phpunit -c backup
vendor/bin/phpunit -c lib/dml
...

or, also

cd directory/with/phpunit.xml
phpunit

External test resources

Moodle 2.6

By default Moodle phpunit tests contact http://download.moodle.org server when testing curl related functionality. Optionally you may checkout a local copy of the test scripts and access it instead:

  1. clone https://github.com/moodlehq/moodle-exttests to web directory
  2. add to your config.php or modify phpunit.xml file
    define('TEST_EXTERNAL_FILES_HTTP_URL', 'http://localhost/moodle-exttests');
    

Writing new tests

Conversion of existing SimpleTests

PHPUnit support in IDEs

Common Unit Test Problems

Common unit test problems

Performance

A typical run of full PHPUnit tests for Moodle 2.7 takes 10-20 minutes depending on the machine. If tests run slowly for you:

  • Ensure you are using a database and filesystem running on the same machine that is running the tests (not on a remote server).
  • Apply developer-only performance settings to your database: Postgres Tuning For Developers

Command line tips

  • Run all tests for a plugin (mod_mymodule in this example): vendor/bin/phpunit --testsuite=mod_mymodule_testsuite
  • Run only named test: vendor/bin/phpunit --filter=test_my_test_function_name
  • Display each test name before running it (useful e.g. if it crashes before the end and you want to know which test it was running at that point) vendor/bin/phpunit --debug (you will probably want to redirect this to a file as it gets very long).