NAME
    Test.php - TAP test framework for PHP with a Test::More-like interface

SYNOPSIS
        #!/usr/bin/env php
        <?php  
        require 'Test.php';
  
        plan($num); # plan $num tests
        # or
        plan('no_plan'); # We don't know how many
        # or
        plan('skip_all'); # Skip all tests
        # or
        plan('skip_all', $reason); # Skip all tests with a reason
  
        diag('message in test output') # Trailing \n not required
  
        # $test_name is always optional and should be a short description of
        # the test, e.g. "some_function() returns an integer"
  
        # Various ways to say "ok"
        ok($got == $expected, $test_name);
  
        # Compare with == and !=
        is($got, $expected, $test_name);
        isnt($got, $expected, $test_name);
  
        # Run a preg regex match on some data
        like($got, $regex, $test_name);
        unlike($got, $regex, $test_name);
  
        # Compare something with a given comparison operator
        cmp_ok($got, '==', $expected, $test_name);
        # Compare something with a comparison function (should return bool)
        cmp_ok($got, $func, $expected, $test_name);
  
        # Recursively check datastructures for equalness
        is_deeply($got, $expected, $test_name);
  
        # Always pass or fail a test under an optional name
        pass($test_name);
        fail($test_name);

        # TODO tests, these are expected to fail but won't fail the test run,
        # unexpected success will be reported
        todo_start("integer arithmetic still working");
        ok(1 + 2 == 3);
        {
            # TODOs can be nested
            todo_start("string comparison still working")
            is("foo", "bar");
            todo_end();
        }
        todo_end();
        ?>
  
DESCRIPTION
    Test.php is an implementation of Perl's Test::More for PHP. Like
    Test::More it produces language agnostic TAP output (see TAP) which can
    then be gathered, formatted and summarized by a program that understands
    TAP such as prove(1).

HOWTO
    First place the Test.php in the project root or somewhere else in the
    include path where "require" and "include" will find it.

    Then make a place to put your tests in, it's customary to place TAP
    tests in a directory named t under the root but they can be anywhere you
    like. Make a test in this directory or one of its subdirs and try
    running it with php(1):

        $ php t/pass.t 
        1..1
        ok 1 This dummy test passed

    The TAP output consists of very simple output, of course reading larger
    output is going to be harder which is where prove(1) comes in. prove is
    a harness program that reads test output and produces reports based on
    it:

        $ prove t/pass.t 
        t/pass....ok
        All tests successful.
        Files=1, Tests=1,  0 wallclock secs ( 0.03 cusr +  0.02 csys =  0.05 CPU)

    To run all the tests in the t directory recursively use "prove -r t".
    This can be put in a Makefile under a *test* target, for example:

        test: Test.php
                    prove -r t
    
    For reference the example test file above looks like this, the shebang
    on the first line is needed so that prove(1) and other test harness
    programs know they're dealing with a PHP file.

        #!/usr/bin/env php
        <?php
    
        require 'Test.php';
    
        plan(1);
        pass('This dummy test passed');
        ?>
    
SEE ALSO
    TAP - The TAP protocol

AUTHOR
    Ævar Arnfjörð Bjarmason <avar@cpan.org> and Andy Armstrong
    <andy@hexten.net>

LICENSING
    The author or authors of this code dedicate any and all copyright
    interest in this code to the public domain. We make this dedication for
    the benefit of the public at large and to the detriment of our heirs and
    successors. We intend this dedication to be an overt act of
    relinquishment in perpetuity of all present and future rights this code
    under copyright law.