From 322bb9cd2be9e51422cb2b82684692e825c2bfb7 Mon Sep 17 00:00:00 2001 From: brettp Date: Fri, 2 Oct 2009 18:40:04 +0000 Subject: Added simpletest and start of unit tests. git-svn-id: http://code.elgg.org/elgg/trunk@3503 36083f99-b078-4883-b0ff-0f9b5a30f544 --- .../docs/en/unit_test_documentation.html | 431 +++++++++++++++++++++ 1 file changed, 431 insertions(+) create mode 100755 vendors/simpletest/docs/en/unit_test_documentation.html (limited to 'vendors/simpletest/docs/en/unit_test_documentation.html') diff --git a/vendors/simpletest/docs/en/unit_test_documentation.html b/vendors/simpletest/docs/en/unit_test_documentation.html new file mode 100755 index 000000000..bc43c82cc --- /dev/null +++ b/vendors/simpletest/docs/en/unit_test_documentation.html @@ -0,0 +1,431 @@ + + + +SimpleTest for PHP regression test documentation + + + +
+SimpleTest + | + Overview + | + Unit tester + | + Group tests + | + Mock objects + | + Partial mocks + | + Reporting + | + Expectations + | + Web tester + | + Testing forms + | + Authentication + | + Scriptable browser +
+

PHP Unit Test documentation

+ This page... + +
+

Unit test cases

+

+ The core system is a regression testing framework built around + test cases. + A sample test case looks like this... +

+class FileTestCase extends UnitTestCase {
+}
+
+ Actual tests are added as methods in the test case whose names + by default start with the string "test" and + when the test case is invoked all such methods are run in + the order that PHP introspection finds them. + As many test methods can be added as needed. +

+

+ For example... +

+require_once('simpletest/autorun.php');
+require_once('../classes/writer.php');
+
+class FileTestCase extends UnitTestCase {
+    function FileTestCase() {
+        $this->UnitTestCase('File test');
+    }
+    
+    function setUp() {
+        @unlink('../temp/test.txt');
+    }
+    
+    function tearDown() {
+        @unlink('../temp/test.txt');
+    }
+    
+    function testCreation() {
+        $writer = &new FileWriter('../temp/test.txt');
+        $writer->write('Hello');
+        $this->assertTrue(file_exists('../temp/test.txt'), 'File created');
+    }
+}
+
+ The constructor is optional and usually omitted. + Without a name, the class name is taken as the name of the test case. +

+

+ Our only test method at the moment is testCreation() + where we check that a file has been created by our + Writer object. + We could have put the unlink() + code into this method as well, but by placing it in + setUp() and + tearDown() we can use it with + other test methods that we add. +

+

+ The setUp() method is run + just before each and every test method. + tearDown() is run just after + each and every test method. +

+

+ You can place some test case set up into the constructor to + be run once for all the methods in the test case, but + you risk test inteference that way. + This way is slightly slower, but it is safer. + Note that if you come from a JUnit background this will not + be the behaviour you are used to. + JUnit surprisingly reinstantiates the test case for each test + method to prevent such interference. + SimpleTest requires the end user to use setUp(), but + supplies additional hooks for library writers. +

+

+ The means of reporting test results (see below) are by a + visiting display class + that is notified by various assert...() + methods. + Here is the full list for the UnitTestCase + class, the default for SimpleTest... + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
assertTrue($x)Fail if $x is false
assertFalse($x)Fail if $x is true
assertNull($x)Fail if $x is set
assertNotNull($x)Fail if $x not set
assertIsA($x, $t)Fail if $x is not the class or type $t
assertNotA($x, $t)Fail if $x is of the class or type $t
assertEqual($x, $y)Fail if $x == $y is false
assertNotEqual($x, $y)Fail if $x == $y is true
assertWithinMargin($x, $y, $m)Fail if abs($x - $y) < $m is false
assertOutsideMargin($x, $y, $m)Fail if abs($x - $y) < $m is true
assertIdentical($x, $y)Fail if $x == $y is false or a type mismatch
assertNotIdentical($x, $y)Fail if $x == $y is true and types match
assertReference($x, $y)Fail unless $x and $y are the same variable
assertClone($x, $y)Fail unless $x and $y are identical copies
assertPattern($p, $x)Fail unless the regex $p matches $x
assertNoPattern($p, $x)Fail if the regex $p matches $x
expectError($x)Swallows any upcoming matching error
assert($e)Fail on failed expectation object $e
+ All assertion methods can take an optional description as a + last parameter. + This is to label the displayed result with. + If omitted a default message is sent instead, which is usually + sufficient. + This default message can still be embedded in your own message + if you include "%s" within the string. + All the assertions return true on a pass or false on failure. +

+

+ Some examples... +

+$variable = null;
+$this->assertNull($variable, 'Should be cleared');
+
+ ...will pass and normally show no message. + If you have + set up the tester to display passes + as well then the message will be displayed as is. +
+$this->assertIdentical(0, false, 'Zero is not false [%s]');
+
+ This will fail as it performs a type + check, as well as a comparison, between the two values. + The "%s" part is replaced by the default + error message that would have been shown if we had not + supplied our own. +
+$a = 1;
+$b = $a;
+$this->assertReference($a, $b);
+
+ Will fail as the variable $a is a copy of $b. +
+$this->assertPattern('/hello/i', 'Hello world');
+
+ This will pass as using a case insensitive match the string + hello is contained in Hello world. +
+$this->expectError();
+trigger_error('Catastrophe');
+
+ Here the check catches the "Catastrophe" + message without checking the text and passes. + This removes the error from the queue. +
+$this->expectError('Catastrophe');
+trigger_error('Catastrophe');
+
+ The next error check tests not only the existence of the error, + but also the text which, here matches so another pass. + If any unchecked errors are left at the end of a test method then + an exception will be reported in the test. +

+

+ Note that SimpleTest cannot catch compile time PHP errors. +

+

+ The test cases also have some convenience methods for debugging + code or extending the suite... + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
setUp()Runs this before each test method
tearDown()Runs this after each test method
pass()Sends a test pass
fail()Sends a test failure
error()Sends an exception event
signal($type, $payload)Sends a user defined message to the test reporter
dump($var)Does a formatted print_r() for quick and dirty debugging
+

+ +

Extending test cases

+

+ Of course additional test methods can be added to create + specific types of test case, so as to extend framework... +

+require_once('simpletest/autorun.php');
+
+class FileTester extends UnitTestCase {
+    function FileTester($name = false) {
+        $this->UnitTestCase($name);
+    }
+    
+    function assertFileExists($filename, $message = '%s') {
+        $this->assertTrue(
+                file_exists($filename),
+                sprintf($message, 'File [$filename] existence check'));
+    }
+}
+
+ Here the SimpleTest library is held in a folder called + simpletest that is local. + Substitute your own path for this. +

+

+ To prevent this test case being run accidently, it is + advisable to mark it as abstract. +

+

+ Alternatively you could add a + SimpleTestOptions::ignore('FileTester'); + directive in your code. +

+

+ This new case can be now be inherited just like + a normal test case... +

+class FileTestCase extends FileTester {
+    
+    function setUp() {
+        @unlink('../temp/test.txt');
+    }
+    
+    function tearDown() {
+        @unlink('../temp/test.txt');
+    }
+    
+    function testCreation() {
+        $writer = &new FileWriter('../temp/test.txt');
+        $writer->write('Hello');
+        $this->assertFileExists('../temp/test.txt');
+    }
+}
+
+

+

+ If you want a test case that does not have all of the + UnitTestCase assertions, + only your own and a few basics, + you need to extend the SimpleTestCase + class instead. + It is found in simple_test.php rather than + unit_tester.php. + See later if you + want to incorporate other unit tester's + test cases in your test suites. +

+ +

Running a single test case

+

+ You won't often run single test cases except when bashing + away at a module that is having difficulty, and you don't + want to upset the main test suite. + With autorun no particular scaffolding is needed, + just launch your particular test file and you're ready to go. +

+

+ You can even decide which reporter (for example, + TextReporter or HtmlReporter) + you prefer for a specific file when launched on its own... +

+<?php
+require_once('simpletest/autorun.php');
+SimpleTest :: prefer(new TextReporter());
+require_once('../classes/writer.php');
+
+class FileTestCase extends UnitTestCase {
+    ...
+}
+?>
+
+ This script will run as is, but of course will output zero passes + and zero failures until test methods are added. +

+ +
+ References and related information... + +
+SimpleTest + | + Overview + | + Unit tester + | + Group tests + | + Mock objects + | + Partial mocks + | + Reporting + | + Expectations + | + Web tester + | + Testing forms + | + Authentication + | + Scriptable browser +
+
+ Copyright
Marcus Baker 2006 +
+ + -- cgit v1.2.3