Unit test API - Revision history

Stronk7: Making it clear that this is absolutely outdated, also changed some redirects to point to PHPUnit.

2022-01-31T08:58:10Z

Making it clear that this is absolutely outdated, also changed some redirects to point to PHPUnit.

← Older revision		Revision as of 08:58, 31 January 2022
Line 1:		Line 1:
	~~Location: ''Administration > Reports > Unit tests'' in 1.9 or ''Site administration > Development > Unit tests'' in Moodle 2.0-~~2.2		{{Deprecated\|version=2.3}}
			{{obsolete}}

	See [[PHPUnit]] page for new unit testing support in Moodle 2.3		See [[PHPUnit]] page for new unit testing support in Moodle 2.3 and up.

			Location: ''Administration > Reports > Unit tests'' in 1.9 or ''Site administration > Development > Unit tests'' in Moodle 2.0-2.2

	The purpose of Unit tests is to evaluate the individual parts of a program (functions, and methods of classes) to make sure that each element individually does the right thing. Unit Tests can be one of the first steps in a quality control process for developing or tweaking Moodle code. The next steps will involve other forms of testing to ensure that these different parts work together properly.		The purpose of Unit tests is to evaluate the individual parts of a program (functions, and methods of classes) to make sure that each element individually does the right thing. Unit Tests can be one of the first steps in a quality control process for developing or tweaking Moodle code. The next steps will involve other forms of testing to ensure that these different parts work together properly.

Mudrd8mz: Text replacement - "" to ""

2021-07-14T20:23:03Z

Text replacement - "</code>" to "</syntaxhighlight>"

Show changes

Mudrd8mz: Text replacement - "`" to ""`


2021-07-14T13:28:09Z
Text replacement - "<code php>" to "<syntaxhighlight lang="php">"
Show changes



Mudrd8mz: Text replacement - "" to ""

2021-07-14T13:03:57Z
Text replacement - "<code>" to "<syntaxhighlight lang="php">"

				
				
				
				
				
				← Older revision
				Revision as of 13:03, 14 July 2021
				
Line 86:
Line 86:
If all your test cases relate to the same area of code, then they may all need to same bit of fixture set up. For example, all the tests in lib/simpletest/teststringmanager.php need an instance of the string_manager class to test. If all your test cases relate to the same area of code, then they may all need to same bit of fixture set up. For example, all the tests in lib/simpletest/teststringmanager.php need an instance of the string_manager class to test.



To avoid duplicating code, you can override a method called <code>setUp()</code> that sets up the test data. If present, this method will be called before each test method. You can write a matching <code>tearDown()</code> method if there is any clean-up that needs to be done after each test case has run. For example, in lib/simpletest/teststringmanager.php there are setUp and tearDown methods that do something like: To avoid duplicating code, you can override a method called <syntaxhighlight lang="php">setUp()</code> that sets up the test data. If present, this method will be called before each test method. You can write a matching <syntaxhighlight lang="php">tearDown()</code> method if there is any clean-up that needs to be done after each test case has run. For example, in lib/simpletest/teststringmanager.php there are setUp and tearDown methods that do something like:
<code php> <code php>
public function setUp() { public function setUp() {



Poltawski: /* Access to global variables */
2016-06-14T16:49:36Z
Access to global variables

				
				
				
				
				
				← Older revision
				Revision as of 16:49, 14 June 2016
				
Line 128:
Line 128:



<code php> <code php>
require_once(dirname(__FILE__) . '/../../config.php'); require_once(__DIR__ . '/../../config.php');
require_once($CFG->libdir . '/moodlelib.php'); // Won't work. require_once($CFG->libdir . '/moodlelib.php'); // Won't work.
</code> </code>



<code php> <code php>
require_once(dirname(__FILE__) . '/../../config.php'); require_once(__DIR__. '/../../config.php');



global $CFG; // You need this. global $CFG; // You need this.



Poltawski: MDL-35628
2016-06-14T16:48:08Z
MDL-35628

				
				
				
				
				
				← Older revision
				Revision as of 16:48, 14 June 2016
				
Line 120:
Line 120:



<code php> <code php>
require_once(dirname(__FILE__) . '/../../config.php'); // Do this. require_once(__DIR__ . '/../../config.php'); // Do this.
</code> </code>






Ivor99: /* Code coverage analysis */
2013-09-21T23:18:20Z
Code coverage analysis

				
				
				
				
				
				← Older revision
				Revision as of 23:18, 21 September 2013
				
Line 277:
Line 277:



Further reading and investigation suggest that Moodle will implement its own extensions to SimpleTest in order to fulfill the main goal of having statement/line code coverage analysis working under Moodle 2.0 onwards. To achieve this  [http://developer.spikesource.com/projects/phpcoverage Spike PHPCoverage], a basic code-coverage tool, will be used and extended. You can find the details of the implementation of this tool at MDL-19579. Further reading and investigation suggest that Moodle will implement its own extensions to SimpleTest in order to fulfill the main goal of having statement/line code coverage analysis working under Moodle 2.0 onwards. To achieve this  [http://developer.spikesource.com/projects/phpcoverage Spike PHPCoverage], a basic code-coverage tool, will be used and extended. You can find the details of the implementation of this tool at MDL-19579.

Further update: according to [https://docs.moodle.org/dev/SimpleTest_conversion SimpleTest conversion] Moodle 2.3 switched to [http://www.phpunit.de/ PHPUnit] as the recommended unit testing framework and SimpleTest support will be completely removed from Moodle 2.4.  See [https://docs.moodle.org/dev/SimpleTest_conversion  cited link] for how to convert test scripts from [http://www.simpletest.org/ SimpleTest] to [http://www.phpunit.de/ PHPUnit]



=== Changes === === Changes ===



Ivor99: /* Code coverage analysis */
2013-09-21T20:00:49Z
Code coverage analysis

				
				
				
				
				
				← Older revision
				Revision as of 20:00, 21 September 2013
				
Line 272:
Line 272:
{{Moodle 2.0}} {{Moodle 2.0}}



'''[[Wikipedia:Code_coverage|Code coverage]]''' is a technique, strongly tied with software testing, that allows to '''check and improve the quality of the tests''' by measuring the degree of source code that is being covered by them. With Moodle supporting more and more tests each day (slowly towards a '''Test Driven Development''' model) we need to integrate some tool into our development process helping to analyse the quality of ours tests. '''[[Wikipedia:Code_coverage|Code coverage]]''' is a technique, strongly tied with software testing, that allows to '''check and improve the quality of the tests''' by measuring the degree of source code that is being covered by them. With Moodle supporting more and more tests each day (moving slowly towards a '''Test Driven Development''' model) we need to integrate some tool into our development process to help analyse the completeness of our test regime.



Right now (in Moodle 2.0) we are using [http://www.simpletest.org/ SimpleTest], one simple and great tool to perform all the tests. Unluckily, it doesn't support code coverage analysis at all. In the other hand, other PHP unit testing products like [http://www.phpunit.de/ PHPUnit], more complex and powerful, have built-in support for that technique, but switching to a new product is out from our current [[Roadmap]] plans. Right now (in Moodle 2.0) we are using [http://www.simpletest.org/ SimpleTest], a simple and useful tool that supports unit testing. Unfortunately it doesn't support code coverage analysis at all. On the other hand, other PHP unit testing products like [http://www.phpunit.de/ PHPUnit], more complex and powerful, have built-in support for code coverage analysis. However switching to a new product is out of scope of our current [[Roadmap]].



So, after some readings and comparisons, Moodle will implement its own extensions to SimpleTest, in order to fulfil the main goal of having statement/line code coverage analysis working under Moodle 2.0 onwards. To achieve this, also [http://developer.spikesource.com/projects/phpcoverage Spike PHPCoverage], a basic code-coverage tool, will be used and extended. You can find the details of the implementation of this tool at MDL-19579. Further reading and investigation suggest that Moodle will implement its own extensions to SimpleTest in order to fulfill the main goal of having statement/line code coverage analysis working under Moodle 2.0 onwards. To achieve this  [http://developer.spikesource.com/projects/phpcoverage Spike PHPCoverage], a basic code-coverage tool, will be used and extended. You can find the details of the implementation of this tool at MDL-19579.



=== Changes === === Changes ===



To enable code coverage in your tests, only a few modifications need to be performed to your current code: To enable code coverage in your tests, only a few modifications need to be made to your current code:



# Change your test classes by adding two (public static) attributes: '''$includecoverage''' and '''$excludecoverage''', both arrays, being used to inform to the code coverage tool (via reflection) about which source code files and dirs must be covered/skipped by the analysis. # Change your test classes by adding two (public static) attributes: '''$includecoverage''' and '''$excludecoverage''', both arrays. These are used to inform the code coverage tool (via reflection) about which source code files and directories must be covered/skipped by the analysis.
# Use '''[http://cvs.moodle.org/moodle/lib/simpletestcoveragelib.php?view=markup simpletestcoveragelib.php]''' instead of simpletestlib.php in your caller scripts. # Use '''[http://cvs.moodle.org/moodle/lib/simpletestcoveragelib.php?view=markup simpletestcoveragelib.php]''' instead of simpletestlib.php in your caller scripts.
# Use the '''autogroup_test_coverage''' class instead of the AutoGroupTest one (see below for details) in your caller scripts. # Use the '''autogroup_test_coverage''' class instead of the AutoGroupTest class (see below for details) in your caller scripts.



(note that only the 1st point above is needed for new unit tests being created because both 2 and 3 (changes in caller scripts) are already implemented in Moodle and awaiting your cool unit tests. Note that only item 1 above is needed for new unit tests being created because both 2 and 3 (changes in caller scripts) are already implemented in Moodle and awaiting your cool unit tests.



That's all! With those 3 basic changes, you will end with a complete code coverage report available for further analysis. That's all! With these 3 basic changes, you will end with a complete code coverage report available for further analysis.



=== API === === API ===



When using code coverage within Moodle there are two alternative APIs available, both providing the same code coverage reports at the end, but doing that in a different way. Here they are: When using code coverage within Moodle there are two alternative APIs available, both providing the same code coverage reports at the end, but each doing that in a different way. Here they are:



* '''Internal (hidden) coverage API''': This API is completely hidden beyond the Unit testing API and you won't need to know the details about it. Just perform the 1-2-3 changes described above and, after running the tests you'll get the final report available for being used immediately, without needing to perform anything in your code. His major drawback: it only can perform '''one''' "code coverage session" (a.k.a. instrumentation), so it's only suitable for testing scripts using only one unit test execution. One example of this type of unit testing is  [http://cvs.moodle.org/moodle/admin/report/unittest/index.php?view=markup admin/report/unittest/index.php] where only one (big) test-group is executed. * '''Internal (hidden) coverage API''': This API is completely hidden behind the Unit testing API and you won't need to know the details of it. Just make the three changes described above and, after running the tests, the coverage report will be available for use; without needing any other changes to your code. The major drawback: it only can perform '''one''' "code coverage session" (a.k.a. instrumentation), so it's only suitable for testing scripts using only one unit test execution. One example of this type of unit testing is  [http://cvs.moodle.org/moodle/admin/report/unittest/index.php?view=markup admin/report/unittest/index.php] where only one (big) test-group is executed.
* '''External (explicit) coverage API''': This API needs extra coding as long as coverage instantiating, configuration and report generation happens in the main script. It's a bit more complex but, in the other hand, it support '''multiple''' instrumentations to be performed, and gives you more control about the code coverage process.  One example of this type of unit testing is  [http://cvs.moodle.org/moodle/admin/report/unittest/dbtest.php?view=markup admin/report/unittest/dbtest.php] where multiple (one for each DB being tested) test-group are executed. * '''External (explicit) coverage API''': This API needs extra coding as long as coverage instantiating, configuration and report generation happens in the main script. It's a bit more complex but, on the other hand, it supports '''multiple''' instrumentations to be performed, and gives you more control about the code coverage process.  One example of this type of unit testing is  [http://cvs.moodle.org/moodle/admin/report/unittest/dbtest.php?view=markup admin/report/unittest/dbtest.php] where multiple (one for each DB being tested) test-groups are executed.



So, first of all (point 1 in prev section - usage), we need to define, for each unit test, which files / directories (relative to dirroot) we want to analyse with the tool. Here it's one example, for the '''dml_test''' unit test ([http://cvs.moodle.org/moodle/lib/dml/simpletest/testdml.php?view=markup /lib/dml/simpletest/testdml.php]), all we need to add to these lines to the class declaration : So, first of all (point 1 in prev section - usage), we need to define, for each unit test, which files / directories (relative to dirroot) we want to analyse with the tool. Here is one example, for the '''dml_test''' unit test ([http://cvs.moodle.org/moodle/lib/dml/simpletest/testdml.php?view=markup /lib/dml/simpletest/testdml.php]), all we need to do is add the following lines to the class declaration :



<code php> <code php>
Line 304:
Line 304:
</code> </code>



By doing so, the code coverage tool will know which are the target files to perform coverage analysis/reporting and will do that for all the files (recursively) in the ''lib/dml''' dir but excluding the ''lib/dml/somedir'' directory (recursively too). Note that both attributes are arrays so multiple paths can be specified in any of them. Also note that the dir where the UnitTest is stored is automatically excluded (usually ''simpletest'' dirs). By doing so, the code coverage tool will know which are the target files on which to perform coverage analysis/reporting and will do that for all the files (recursively) in the ''lib/dml''' directory but excluding the ''lib/dml/somedir'' directory (recursively too). Note that both attributes are arrays so multiple paths can be specified in any of them. Also note that the directory where the UnitTest is stored is automatically excluded (usually the ''simpletest'' directories).



And, as said, that's all you need to fulfil in order to get current/new unit tests being analysed by the code coverage tool by current Moodle scripts. The documentation below is only interesting for developers wanting to create new scripts able to perform unit testing with code coverage (points 2 and 3 in prev section - usage). And, as said, that's all you need to do in order to get current/new unit tests analysed by the code coverage tool in current Moodle scripts. The documentation below is only interesting for developers wanting to create new scripts able to support unit testing with code coverage (points 2 and 3 in prev section - usage).



==== Internal coverage API ==== ==== Internal coverage API ====
Line 313:
Line 313:
</code> </code>
Create one new autogroup test object with code coverage support, there you can specify if you want to perform coverage (true/false), the name of the report (title) and the directory where the final report will be created (under moodledata/codecoverage).   Create one new autogroup test object with code coverage support, there you can specify if you want to perform coverage (true/false), the name of the report (title) and the directory where the final report will be created (under moodledata/codecoverage).  
Optionally you can add more files and directories (relative to dirroot) to the list of files to be covered / ignored by using these functions (in case the defined in point 1 aren't enough). Optionally you can add more files and directories (relative to dirroot) to the list of files to be covered / ignored by using these functions (in case those defined in point 1 aren't enough).
<code php> <code php>
$test->add_coverage_include_path($path); $test->add_coverage_include_path($path);
$test->add_coverage_exclude_path($path); $test->add_coverage_exclude_path($path);
</code> </code>
And then, affter adding a bunch of unit tests to the group, you simply invoke the test execution with code coverage support to end with a nice code coverage report under ''dataroot/codecoverage/$coveragedir'': And then, after adding a bunch of unit tests to the group, you simply invoke the test execution with code coverage support to end with a nice code coverage report under ''dataroot/codecoverage/$coveragedir'':
<code php> <code php>
$test->run($unit_test_reporter); $test->run($unit_test_reporter);
Line 355:
Line 355:
==== Final notes ==== ==== Final notes ====
* Note that there are some more methods available in the moodle_coverage_recorder class. They will allow to control starting/stopping instrumentations by hand and other minor things but they shouldn't really be used. The run() and run_with_external_coverage() methods should be enough in 99% of cases. * Note that there are some more methods available in the moodle_coverage_recorder class. They will allow to control starting/stopping instrumentations by hand and other minor things but they shouldn't really be used. The run() and run_with_external_coverage() methods should be enough in 99% of cases.
* Not being part of the API, but used by it, there is one '''[http://cvs.moodle.org/moodle/admin/report/unittest/coveragefile.php?view=markup overagefile.php]''' script under ''admin/report/unittest'' responsible for serving the coverage report files from within Moodle. See current scripts in that dir to see how can be used. * Not being part of the API, but used by it, there is one '''[http://cvs.moodle.org/moodle/admin/report/unittest/coveragefile.php?view=markup coveragefile.php]''' script under ''admin/report/unittest'' responsible for serving the coverage report files from within Moodle. See current scripts in that directory to see how it can be used.
* All the test execution / reporting / coverage utilities must be protected with the 'moodle/site:config' permission. * All the test execution / reporting / coverage utilities must be protected with the 'moodle/site:config' permission.






Jcrodriguez: /* Bridge Pattern */
2012-12-21T12:35:57Z
Bridge Pattern

				
				
				
				
				
				← Older revision
				Revision as of 12:35, 21 December 2012
				
Line 160:
Line 160:
class languageBridge { class languageBridge {
     public function get_string($stuff,$module='moodle') {      public function get_string($stuff,$module='moodle') {
         echo get_string($stuff, $module);          return get_string($stuff, $module);
     }      }
} }



Skodak at 20:13, 23 April 2012
2012-04-23T20:13:25Z


				
				
				
				
				
				← Older revision
				Revision as of 20:13, 23 April 2012
				
Line 1:
Line 1:
Location: ''Administration > Reports > Unit tests'' in 1.9 or ''Site administration > Development > Unit tests'' in Moodle 2.0 onwards Location: ''Administration > Reports > Unit tests'' in 1.9 or ''Site administration > Development > Unit tests'' in Moodle 2.0-2.2
 
See [[PHPUnit]] page for new unit testing support in Moodle 2.3

← Older revision		Revision as of 13:03, 14 July 2021
Line 86:		Line 86:
	If all your test cases relate to the same area of code, then they may all need to same bit of fixture set up. For example, all the tests in lib/simpletest/teststringmanager.php need an instance of the string_manager class to test.		If all your test cases relate to the same area of code, then they may all need to same bit of fixture set up. For example, all the tests in lib/simpletest/teststringmanager.php need an instance of the string_manager class to test.

	To avoid duplicating code, you can override a method called <~~code~~>setUp()</code> that sets up the test data. If present, this method will be called before each test method. You can write a matching <~~code~~>tearDown()</code> method if there is any clean-up that needs to be done after each test case has run. For example, in lib/simpletest/teststringmanager.php there are setUp and tearDown methods that do something like:		To avoid duplicating code, you can override a method called <syntaxhighlight lang="php">setUp()</code> that sets up the test data. If present, this method will be called before each test method. You can write a matching <syntaxhighlight lang="php">tearDown()</code> method if there is any clean-up that needs to be done after each test case has run. For example, in lib/simpletest/teststringmanager.php there are setUp and tearDown methods that do something like:
	<code php>		<code php>
	public function setUp() {		public function setUp() {

← Older revision		Revision as of 16:49, 14 June 2016
Line 128:		Line 128:

	<code php>		<code php>
	require_once(~~dirname(__FILE__)~~ . '/../../config.php');		require_once(__DIR__ . '/../../config.php');
	require_once($CFG->libdir . '/moodlelib.php'); // Won't work.		require_once($CFG->libdir . '/moodlelib.php'); // Won't work.
	</code>		</code>

	<code php>		<code php>
	require_once(~~dirname(__FILE__)~~ . '/../../config.php');		require_once(__DIR__. '/../../config.php');

	global $CFG; // You need this.		global $CFG; // You need this.

← Older revision		Revision as of 16:48, 14 June 2016
Line 120:		Line 120:

	<code php>		<code php>
	require_once(~~dirname(__FILE__)~~ . '/../../config.php'); // Do this.		require_once(__DIR__ . '/../../config.php'); // Do this.
	</code>		</code>

← Older revision		Revision as of 23:18, 21 September 2013
Line 277:		Line 277:

	Further reading and investigation suggest that Moodle will implement its own extensions to SimpleTest in order to fulfill the main goal of having statement/line code coverage analysis working under Moodle 2.0 onwards. To achieve this [http://developer.spikesource.com/projects/phpcoverage Spike PHPCoverage], a basic code-coverage tool, will be used and extended. You can find the details of the implementation of this tool at MDL-19579.		Further reading and investigation suggest that Moodle will implement its own extensions to SimpleTest in order to fulfill the main goal of having statement/line code coverage analysis working under Moodle 2.0 onwards. To achieve this [http://developer.spikesource.com/projects/phpcoverage Spike PHPCoverage], a basic code-coverage tool, will be used and extended. You can find the details of the implementation of this tool at MDL-19579.

			Further update: according to [https://docs.moodle.org/dev/SimpleTest_conversion SimpleTest conversion] Moodle 2.3 switched to [http://www.phpunit.de/ PHPUnit] as the recommended unit testing framework and SimpleTest support will be completely removed from Moodle 2.4. See [https://docs.moodle.org/dev/SimpleTest_conversion cited link] for how to convert test scripts from [http://www.simpletest.org/ SimpleTest] to [http://www.phpunit.de/ PHPUnit]

	=== Changes ===		=== Changes ===

← Older revision		Revision as of 20:00, 21 September 2013
Line 272:		Line 272:
	{{Moodle 2.0}}		{{Moodle 2.0}}

	'''[[Wikipedia:Code_coverage\|Code coverage]]''' is a technique, strongly tied with software testing, that allows to '''check and improve the quality of the tests''' by measuring the degree of source code that is being covered by them. With Moodle supporting more and more tests each day (slowly towards a '''Test Driven Development''' model) we need to integrate some tool into our development process ~~helping~~ to analyse the ~~quality~~ of ~~ours tests~~.		'''[[Wikipedia:Code_coverage\|Code coverage]]''' is a technique, strongly tied with software testing, that allows to '''check and improve the quality of the tests''' by measuring the degree of source code that is being covered by them. With Moodle supporting more and more tests each day (moving slowly towards a '''Test Driven Development''' model) we need to integrate some tool into our development process to help analyse the completeness of our test regime.

	Right now (in Moodle 2.0) we are using [http://www.simpletest.org/ SimpleTest], ~~one~~ simple and ~~great~~ tool ~~to perform all the tests~~. ~~Unluckily,~~ it doesn't support code coverage analysis at all. In the other hand, other PHP unit testing products like [http://www.phpunit.de/ PHPUnit], more complex and powerful, have built-in support for ~~that technique, but~~ switching to a new product is out ~~from~~ our current [[Roadmap]] ~~plans~~.		Right now (in Moodle 2.0) we are using [http://www.simpletest.org/ SimpleTest], a simple and useful tool that supports unit testing. Unfortunately it doesn't support code coverage analysis at all. On the other hand, other PHP unit testing products like [http://www.phpunit.de/ PHPUnit], more complex and powerful, have built-in support for code coverage analysis. However switching to a new product is out of scope of our current [[Roadmap]].

	~~So, after some readings~~ and ~~comparisons,~~ Moodle will implement its own extensions to SimpleTest, in order to ~~fulfil~~ the main goal of having statement/line code coverage analysis working under Moodle 2.0 onwards. To achieve this~~, also~~ [http://developer.spikesource.com/projects/phpcoverage Spike PHPCoverage], a basic code-coverage tool, will be used and extended. You can find the details of the implementation of this tool at MDL-19579.		Further reading and investigation suggest that Moodle will implement its own extensions to SimpleTest in order to fulfill the main goal of having statement/line code coverage analysis working under Moodle 2.0 onwards. To achieve this [http://developer.spikesource.com/projects/phpcoverage Spike PHPCoverage], a basic code-coverage tool, will be used and extended. You can find the details of the implementation of this tool at MDL-19579.

	=== Changes ===		=== Changes ===

	To enable code coverage in your tests, only a few modifications need to be ~~performed~~ to your current code:		To enable code coverage in your tests, only a few modifications need to be made to your current code:

	# Change your test classes by adding two (public static) attributes: '''$includecoverage''' and '''$excludecoverage''', both arrays~~, being~~ used to inform to the code coverage tool (via reflection) about which source code files and ~~dirs~~ must be covered/skipped by the analysis.		# Change your test classes by adding two (public static) attributes: '''$includecoverage''' and '''$excludecoverage''', both arrays. These are used to inform the code coverage tool (via reflection) about which source code files and directories must be covered/skipped by the analysis.
	# Use '''[http://cvs.moodle.org/moodle/lib/simpletestcoveragelib.php?view=markup simpletestcoveragelib.php]''' instead of simpletestlib.php in your caller scripts.		# Use '''[http://cvs.moodle.org/moodle/lib/simpletestcoveragelib.php?view=markup simpletestcoveragelib.php]''' instead of simpletestlib.php in your caller scripts.
	# Use the '''autogroup_test_coverage''' class instead of the AutoGroupTest ~~one~~ (see below for details) in your caller scripts.		# Use the '''autogroup_test_coverage''' class instead of the AutoGroupTest class (see below for details) in your caller scripts.

	~~(note~~ that only ~~the 1st point~~ above is needed for new unit tests being created because both 2 and 3 (changes in caller scripts) are already implemented in Moodle and awaiting your cool unit tests.		Note that only item 1 above is needed for new unit tests being created because both 2 and 3 (changes in caller scripts) are already implemented in Moodle and awaiting your cool unit tests.

	That's all! With ~~those~~ 3 basic changes, you will end with a complete code coverage report available for further analysis.		That's all! With these 3 basic changes, you will end with a complete code coverage report available for further analysis.

	=== API ===		=== API ===

	When using code coverage within Moodle there are two alternative APIs available, both providing the same code coverage reports at the end, but doing that in a different way. Here they are:		When using code coverage within Moodle there are two alternative APIs available, both providing the same code coverage reports at the end, but each doing that in a different way. Here they are:

	* '''Internal (hidden) coverage API''': This API is completely hidden ~~beyond~~ the Unit testing API and you won't need to know the details ~~about~~ it. Just ~~perform~~ the ~~1-2-3~~ changes described above and, after running the tests ~~you'll get~~ the ~~final~~ report available for ~~being used immediately,~~ without needing to ~~perform anything in~~ your code. ~~His~~ major drawback: it only can perform '''one''' "code coverage session" (a.k.a. instrumentation), so it's only suitable for testing scripts using only one unit test execution. One example of this type of unit testing is [http://cvs.moodle.org/moodle/admin/report/unittest/index.php?view=markup admin/report/unittest/index.php] where only one (big) test-group is executed.		* '''Internal (hidden) coverage API''': This API is completely hidden behind the Unit testing API and you won't need to know the details of it. Just make the three changes described above and, after running the tests, the coverage report will be available for use; without needing any other changes to your code. The major drawback: it only can perform '''one''' "code coverage session" (a.k.a. instrumentation), so it's only suitable for testing scripts using only one unit test execution. One example of this type of unit testing is [http://cvs.moodle.org/moodle/admin/report/unittest/index.php?view=markup admin/report/unittest/index.php] where only one (big) test-group is executed.
	* '''External (explicit) coverage API''': This API needs extra coding as long as coverage instantiating, configuration and report generation happens in the main script. It's a bit more complex but, in the other hand, it ~~support~~ '''multiple''' instrumentations to be performed, and gives you more control about the code coverage process. One example of this type of unit testing is [http://cvs.moodle.org/moodle/admin/report/unittest/dbtest.php?view=markup admin/report/unittest/dbtest.php] where multiple (one for each DB being tested) test-~~group~~ are executed.		* '''External (explicit) coverage API''': This API needs extra coding as long as coverage instantiating, configuration and report generation happens in the main script. It's a bit more complex but, on the other hand, it supports '''multiple''' instrumentations to be performed, and gives you more control about the code coverage process. One example of this type of unit testing is [http://cvs.moodle.org/moodle/admin/report/unittest/dbtest.php?view=markup admin/report/unittest/dbtest.php] where multiple (one for each DB being tested) test-groups are executed.

	So, first of all (point 1 in prev section - usage), we need to define, for each unit test, which files / directories (relative to dirroot) we want to analyse with the tool. Here ~~it's~~ one example, for the '''dml_test''' unit test ([http://cvs.moodle.org/moodle/lib/dml/simpletest/testdml.php?view=markup /lib/dml/simpletest/testdml.php]), all we need to add ~~to these~~ lines to the class declaration :		So, first of all (point 1 in prev section - usage), we need to define, for each unit test, which files / directories (relative to dirroot) we want to analyse with the tool. Here is one example, for the '''dml_test''' unit test ([http://cvs.moodle.org/moodle/lib/dml/simpletest/testdml.php?view=markup /lib/dml/simpletest/testdml.php]), all we need to do is add the following lines to the class declaration :

	<code php>		<code php>
Line 304:		Line 304:
	</code>		</code>

	By doing so, the code coverage tool will know which are the target files to perform coverage analysis/reporting and will do that for all the files (recursively) in the ''lib/dml''' ~~dir~~ but excluding the ''lib/dml/somedir'' directory (recursively too). Note that both attributes are arrays so multiple paths can be specified in any of them. Also note that the ~~dir~~ where the UnitTest is stored is automatically excluded (usually ''simpletest'' ~~dirs~~).		By doing so, the code coverage tool will know which are the target files on which to perform coverage analysis/reporting and will do that for all the files (recursively) in the ''lib/dml''' directory but excluding the ''lib/dml/somedir'' directory (recursively too). Note that both attributes are arrays so multiple paths can be specified in any of them. Also note that the directory where the UnitTest is stored is automatically excluded (usually the ''simpletest'' directories).

	And, as said, that's all you need to ~~fulfil~~ in order to get current/new unit tests ~~being~~ analysed by the code coverage tool by current Moodle scripts. The documentation below is only interesting for developers wanting to create new scripts able to ~~perform~~ unit testing with code coverage (points 2 and 3 in prev section - usage).		And, as said, that's all you need to do in order to get current/new unit tests analysed by the code coverage tool in current Moodle scripts. The documentation below is only interesting for developers wanting to create new scripts able to support unit testing with code coverage (points 2 and 3 in prev section - usage).

	==== Internal coverage API ====		==== Internal coverage API ====
Line 313:		Line 313:
	</code>		</code>
	Create one new autogroup test object with code coverage support, there you can specify if you want to perform coverage (true/false), the name of the report (title) and the directory where the final report will be created (under moodledata/codecoverage).		Create one new autogroup test object with code coverage support, there you can specify if you want to perform coverage (true/false), the name of the report (title) and the directory where the final report will be created (under moodledata/codecoverage).
	Optionally you can add more files and directories (relative to dirroot) to the list of files to be covered / ignored by using these functions (in case ~~the~~ defined in point 1 aren't enough).		Optionally you can add more files and directories (relative to dirroot) to the list of files to be covered / ignored by using these functions (in case those defined in point 1 aren't enough).
	<code php>		<code php>
	$test->add_coverage_include_path($path);		$test->add_coverage_include_path($path);
	$test->add_coverage_exclude_path($path);		$test->add_coverage_exclude_path($path);
	</code>		</code>
	And then, ~~affter~~ adding a bunch of unit tests to the group, you simply invoke the test execution with code coverage support to end with a nice code coverage report under ''dataroot/codecoverage/$coveragedir'':		And then, after adding a bunch of unit tests to the group, you simply invoke the test execution with code coverage support to end with a nice code coverage report under ''dataroot/codecoverage/$coveragedir'':
	<code php>		<code php>
	$test->run($unit_test_reporter);		$test->run($unit_test_reporter);
Line 355:		Line 355:
	==== Final notes ====		==== Final notes ====
	* Note that there are some more methods available in the moodle_coverage_recorder class. They will allow to control starting/stopping instrumentations by hand and other minor things but they shouldn't really be used. The run() and run_with_external_coverage() methods should be enough in 99% of cases.		* Note that there are some more methods available in the moodle_coverage_recorder class. They will allow to control starting/stopping instrumentations by hand and other minor things but they shouldn't really be used. The run() and run_with_external_coverage() methods should be enough in 99% of cases.
	* Not being part of the API, but used by it, there is one '''[http://cvs.moodle.org/moodle/admin/report/unittest/coveragefile.php?view=markup ~~overagefile~~.php]''' script under ''admin/report/unittest'' responsible for serving the coverage report files from within Moodle. See current scripts in that ~~dir~~ to see how can be used.		* Not being part of the API, but used by it, there is one '''[http://cvs.moodle.org/moodle/admin/report/unittest/coveragefile.php?view=markup coveragefile.php]''' script under ''admin/report/unittest'' responsible for serving the coverage report files from within Moodle. See current scripts in that directory to see how it can be used.
	* All the test execution / reporting / coverage utilities must be protected with the 'moodle/site:config' permission.		* All the test execution / reporting / coverage utilities must be protected with the 'moodle/site:config' permission.

← Older revision		Revision as of 12:35, 21 December 2012
Line 160:		Line 160:
	class languageBridge {		class languageBridge {
	public function get_string($stuff,$module='moodle') {		public function get_string($stuff,$module='moodle') {
	~~echo~~ get_string($stuff, $module);		return get_string($stuff, $module);
	}		}
	}		}

← Older revision		Revision as of 20:13, 23 April 2012
Line 1:		Line 1:
	Location: ''Administration > Reports > Unit tests'' in 1.9 or ''Site administration > Development > Unit tests'' in Moodle 2.0 ~~onwards~~		Location: ''Administration > Reports > Unit tests'' in 1.9 or ''Site administration > Development > Unit tests'' in Moodle 2.0-2.2

			See [[PHPUnit]] page for new unit testing support in Moodle 2.3