[cvs] [Wiki] changed: Doc/Tests

[Chuck Hagenbuch]

chuck  Thu, 27 Oct 2005 17:28:48 -0700

Modified page: http://wiki.horde.org/Doc/Tests
New Revision:  1.1
Change log:  test docs

@@ -1 +1,183 @@
++ Writing PHP Tests
 
+.phpt stands for "php test" and is a specialized file format that consists of 4 standard sections, and two optional sections (marked by *).  They are as follows:
+
+# TEST - the name of the test file (informational)
+# SKIPIF - PHP code that determines whether this test should be run, and echoes "skip reason", more at (a)
+# ARGS - pass in command-line arguments to php pear run-tests does not yet implement GET, POST, or INI
+# FILE - the actual test file, this is standard PHP
+# EXPECT/EXPECTF/EXPECTREGEX - plain test, the expected output of the file.  EXPECTF and EXPECTREGEX are used to allow looser validation.
+
+a simple test is:
+
+<code>
+--TEST--
+simple test
+--SKIPIF--
+<?php
+if (substr(PHP_OS, 0, 3) == "WIN") {
+    echo "skip cannot run on windows";
+}
+echo "warn you might have left the iron plugged in";
+?>
+--FILE--
+<?php
+echo "tests done";
+?>
+--EXPECT--
+tests done
+</code>
+
+If you run this command on windows
+
+<code>
+C:\> pear run-tests simpletest.phpt
+SKIP (reason: cannot run on windows)
+</code>
+
+if you run it on any other OS
+
+<code>
+~ pear run-tests simpletest.phpt
+PASS simple test [simpletest.phpt] (warn: you might have left the iron plugged in)
+</code>
+
+This test fails:
+
+<code>
+--TEST--
+fail test
+--SKIPIF--
+--FILE--
+<?php
+echo "wrong";
+?>
+--EXPECT--
+tests done
+</code>
+
+<code>
+C:\> pear run-tests failtest.phpt
+FAIL fail test [failtest.phpt]
+</code>
+
+and creates 3 files:
+
+<code>
+failtest.php:
+<?php
+echo "wrong";
+?>
+
+failtest.exp:
+tests done
+
+failtest.out:
+wrong
+
+failtest.diff:
+001- tests done
+001+ wrong
+</code>
+
+Most tests rely upon var_dump(), echo, and other display methods to validate the test like so:
+
+<code>
+--TEST--
+old way
+--SKIPIF--
+--FILE--
+<?php
+var_dump(array(2, 'hi'));
+?>
+--EXPECT--
+array(2) {
+  [0]=>
+  int(3)
+  [1]=>
+  string(2) "hi"
+}
+</code>
+
+The method I have been using for testing PEAR is more familiar to users of phpunit.
+
+<code>
+--TEST--
+new way
+--SKIPIF--
+--FILE--
+<?php
+require_once dirname(__FILE__) . '/phpt_test.php.inc';
+$phpunit = new PEAR_PHPTest;
+$a = array(2, 'hi');
+$phpunit->assertEquals(array(2, 'hi'), $a, 'first array');
+echo 'tests done';
+?>
+--EXPECT--
+tests done
+</code>
+
+When a test succeeds, there is no output, but in this test:
+
+<code>
+--TEST--
+new way
+--SKIPIF--
+--FILE--
+<?php
+require_once dirname(__FILE__) . '/phpt_test.php.inc';
+$phpunit = new PEAR_PHPTest;
+$a = array(3, 'hi');
+$phpunit->assertEquals(array(2, 'hi'), $a, 'first array');
+echo 'tests done';
+?>
+--EXPECT--
+tests done
+</code>
+
+if you have Text_Diff installed, the .out file would contain:
+
+<code>
+Test Failure: "first array"
+ in C:\devel\newtest.php line 4
+Diff of expecting/received:
+@@ -1,4 +1,4 @@
+ array (
+-  0 => 2,
++  0 => 3,
+   1 => 'hi',
+ )
+</code>
+
+otherwise, it would contain:
+
+<code>
+Test Failure: "first array"
+ in C:\devel\newtest.php line 4
+Expecting:
+array (
+  0 => 2,
+  1 => 'hi',
+)
+Received:
+array (
+  0 => 3,
+  1 => 'hi',
+)
+</code>
+
+This makes it really easy to both debug and create new tests/modify old ones.  If array(3, 'hi') is correct, all you have to do is cut and paste the output into your test. An extreme example of where I have done this is in pear-core/tests/PEAR_DependencyDB/test_rebuildDB.phpt
+
+An example of how this flexibility is better than a simple EXPECTF is in pear-core/tests/PEAR_Downloader_Package/test_initialize_abstractpackage.phpt in this section:
+
+<code>
+$phpunit->assertEquals(array (
+  0 =>
+  array (
+    0 => 3,
+    1 => '+ tmp dir created at ' . $dp->_downloader->getDownloadDir(),
+  ),
+), $fakelog->getLog(), 'log messages');
+</code>
+
+here, I wanted to make sure that not only was this + tmp dir message logged, but that the directory created was in fact the one from our instance of PEAR_Downloader.