MDL-31857 phpunit: PHPDoc and typo fixes during integration
[moodle.git] / lib / phpunit / readme.md
CommitLineData
5bd40408
PS
1PHPUnit testing support in Moodle
2==================================
3
4
5Installation
6------------
71. install PHPUnit PEAR extension - see [PHPUnit docs](http://www.phpunit.de/manual/current/en/installation.html) for more details
82. edit main config.php - add $CFG->phpunit_prefix and $CFG->phpunit_dataroot - see config-dist.php for more details
93. execute `php admin/tool/phpunit/cli/util.php --install` to initialise test database
104. it is necessary to reinitialise the test database manually after every upgrade or installation of new plugins
11
12
13Test execution
14--------------
15* optionally generate phpunit.xml by executing `php admin/tool/phpunit/cli/util.php --buildconfig` - it collects test cases from all plugins
16* execute `phpunit` shell command from dirroot directory
17* you can also execute a single test `phpunit core_phpunit_basic_testcase lib/tests/phpunit_test.php`
18* or all tests in one directory `phpunit --configuration phpunit.xml lib/tests/*_test.php`
19* it is possible to create custom configuration files in xml format and use `phpunit -c myconfig.xml`
20
21
22How to add more tests
23---------------------
241. create `tests` directory in any plugin
252. add `*_test.php` files with custom class that extends `basic_testcase`
263. manually add all core unit test locations to `phpunit.xml.dist`
27
28
29How to convert existing tests
30-----------------------------
311. create new test file in `xxx/tests/yyy_test.php`
322. copy contents of the old test file
333. replace `extends UnitTestCase` with `extends basic_testcase`
344. fix setUp, tearDown, asserts, etc.
355. some old SimpleTest tests can be executed directly - mocking, database operations, assert(), etc. does not work, you may need to add `global $CFG;` before includes
36
37
38FAQs
39----
7aea08e1
SH
40* Why is it necessary to execute the tests from the command line? PHPUnit is designed to be executed from shell, existing Moodle globals and constants would interfere with it.
41* Why `tests` subdirectory? It is very unlikely that it will collide with any plugin name because plugin names use singular form.
5bd40408
PS
42* Why is it necessary to include core and plugin suites in configuration files? PHPUnit does not seem to allow dynamic loading of tests from our dir structure.
43
44
45TODO
46----
7aea08e1 47* stage 2 - implement advanced_testcase - support for database modifications, object generators, automatic rollback of db, globals and dataroot
5bd40408
PS
48* stage 3 - mocking and other advanced features, add support for execution of functional DB tests for different engines together (new options in phpunit.xml)
49* other - support for execution of tests and cli/util.php from web UI (to be implemented via shell execution), shell script that prepares everything for the first execution