This is old documentation. Current Horde 5+ applications and libraries use PHPUnit wrapped in Horde_Test.

===================
 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:

1. TEST - the name of the test file (informational)

2. SKIPIF - PHP code that determines whether this test should be run, and echoes "skip reason", more at (a)

3. ARGS - pass in command-line arguments to php pear run-tests does not yet implement GET, POST, or INI

4. FILE - the actual test file, this is standard PHP

5. EXPECT/EXPECTF/EXPECTREGEX - plain test, the expected output of the file.  EXPECTF and EXPECTREGEX are used to allow looser validation.

a simple test is:

::

 --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

If you run this command on windows

::

 C:\> pear run-tests simpletest.phpt
 SKIP (reason: cannot run on windows)

if you run it on any other OS

::

 ~ pear run-tests simpletest.phpt
 PASS simple test [simpletest.phpt] (warn: you might have left the iron plugged in)

This test fails:

::

 --TEST--
 fail test
 --SKIPIF--
 --FILE--
 <?php
 echo "wrong";
 ?>
 --EXPECT--
 tests done

::

 C:\> pear run-tests failtest.phpt
 FAIL fail test [failtest.phpt]

and creates 3 files:

::

 failtest.php:
 <?php
 echo "wrong";
 ?>
 
 failtest.exp:
 tests done
 
 failtest.out:
 wrong
 
 failtest.diff:
 001- tests done
 001+ wrong

Most tests rely upon var_dump(), echo, and other display methods to validate the test like so:

::

 --TEST--
 old way
 --SKIPIF--
 --FILE--
 <?php
 var_dump(array(2, 'hi'));
 ?>
 --EXPECT--
 array(2) {
   [0]=>
   int(3)
   [1]=>
   string(2) "hi"
 }

The method I have been using for testing PEAR is more familiar to users of phpunit.

::

 --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

When a test succeeds, there is no output, but in this test:

::

 --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

if you have Text_Diff installed, the .out file would contain:

::

 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',
  )

otherwise, it would contain:

::

 Test Failure: "first array"
  in C:\devel\newtest.php line 4
 Expecting:
 array (
   0 => 2,
   1 => 'hi',
 )
 Received:
 array (
   0 => 3,
   1 => 'hi',
 )

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:

::

 $phpunit->assertEquals(array (
   0 =>
   array (
     0 => 3,
     1 => '+ tmp dir created at ' . $dp->_downloader->getDownloadDir(),
   ),
 ), $fakelog->getLog(), 'log messages');

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.