Source for file DocTest.php

<?php
 
/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
 
/**
 * This file is part of the PEAR Testing_DocTest package.
 *
 * PHP version 5
 *
 * LICENSE: This source file is subject to the MIT license that is available
 * through the world-wide-web at the following URI:
 * http://opensource.org/licenses/mit-license.php
 *
 * @category  Testing
 * @package   Testing_DocTest
 * @author    David JEAN LOUIS <izimobil@gmail.com>
 * @copyright 2008 David JEAN LOUIS
 * @license   http://opensource.org/licenses/mit-license.php MIT License
 * @version   CVS: $Id$
 * @link      http://pear.php.net/package/Testing_DocTest
 * @since     File available since release 0.1.0
 * @filesource
 */
 
/**
 * Required unconditionally.
 */
require_once 'Testing/DocTest/Registry.php';
require_once 'Testing/DocTest/Exception.php';
require_once 'Testing/DocTest/Finder/Default.php';
require_once 'Testing/DocTest/Outputter/Default.php';
require_once 'Testing/DocTest/Parser/Default.php';
require_once 'Testing/DocTest/Runner/Default.php';
 
/**
 * DocTest.
 *
 * @category  Testing
 * @package   Testing_DocTest
 * @author    David JEAN LOUIS <izimobil@gmail.com>
 * @copyright 2008 David JEAN LOUIS
 * @license   http://opensource.org/licenses/mit-license.php MIT License
 * @version   Release: @package_version@
 * @link      http://pear.php.net/package/Testing_DocTest
 * @since     Class available since release 0.1.0
 */
class Testing_DocTest
{
    // Flags constants {{{
 
    /**
     * Tell the runner to ignore *all* whitespace differences when comparing
     * expected and actual results.
     */
    const FLAG_NORMALIZE_WHITESPACE = 0x01;
 
    /**
     * Tell the runner to compare expected and actual results in case
     * insensitive mode.
     */
    const FLAG_CASE_INSENSITIVE = 0x02;
 
    /**
     * Tell the parser to skip the test.
     */
    const FLAG_SKIP = 0x04;
 
    /**
     * Allow to pass a wildcard pattern: [...] that will match any string in
     * the actual result.
     */
    const FLAG_ELLIPSIS = 0x08;
 
    // }}}
    // __construct() {{{
 
    /**
     * Constructor.
     *
     * The $options array can have the following elements
     * - quiet: tells the outputter to turn on quiet mode, only errors will
     *   be printed out (the default value is false);
     * - no_colors: tells the outputter to not use colors when outputting
     *   results (the default value is false);
     * - logfile: tells the outputter to write the results in a logfile
     *   instead of STDOUT;
     *
     * @param array $options an optional array of options
     *
     * @access public
     * @return void 
     */
    public function __construct(array $options=array()) 
    {
        $reg = Testing_DocTest_Registry::singleton();
        // set user options
        foreach ($options as $name => $value) {
            $reg->$name = $value;
        }
        // set default workers
        $reg->finder    = new Testing_DocTest_Finder_Default();
        $reg->parser    = new Testing_DocTest_Parser_Default();
        $reg->runner    = new Testing_DocTest_Runner_Default();
        $reg->outputter = new Testing_DocTest_Outputter_Default();
    }
 
    // }}}
    // accept() {{{
 
    /**
     * Method to allow DocTest to accept a custom finder, outputter, parser or
     * runner instance.
     *
     * <code>
     * class MyRunner implements Testing_DocTest_RunnerInterface {
     *     function run(Testing_DocTest_TestCase $tb) {
     *         // do something here...
     *     }
     * }
     *
     * try {
     *     $goodRunner = new MyRunner();
     *     $badRunner  = new stdclass();
     *     $doctest    = new Testing_DocTest();
     *     $doctest->accept($goodRunner);
     *     echo "Ok !\n";
     *     $doctest->accept($badRunner);
     * } catch (Testing_DocTest_Exception $exc) {
     *     echo "Error !\n";
     * }
     * // expects:
     * // Ok !
     * // Error !
     *
     * </code>
     *
     * @param mixed $instance an instance implementing the finder, outputter,
     *                         parser or runner interface.
     *
     * @access public
     * @return void 
     * @throws Testing_DocTest_Exception if wrong argument passed
     */
    public function accept($instance) 
    {
        $reg = Testing_DocTest_Registry::singleton();
        if ($instance instanceof Testing_DocTest_FinderInterface) {
            $reg->finder = $instance;
        } else if ($instance instanceof Testing_DocTest_OutputterInterface) {
            $reg->outputter = $instance;
        } else if ($instance instanceof Testing_DocTest_ParserInterface) {
            $reg->parser = $instance;
        } else if ($instance instanceof Testing_DocTest_RunnerInterface) {
            $reg->runner = $instance;
        } else {
            throw new Testing_DocTest_Exception('argument 1 of '
                . 'DocTest::accept must implement the finder, outputter, '
                . 'parser or runner interface.');
        }
    }
 
    // }}}
    // run() {{{
 
    /**
     * Run the tests contained in the given pathes.
     *
     * <code>
     * // flags: ELLIPSIS
     * $base    = is_dir('@php_dir@') ?
     *     '@php_dir@/tests/Testing_DocTest' : 'Testing';
     * $doctest = new Testing_DocTest(array('no_colors'=>true));
     * $doctest->run(array($base . '/tests'));
     * // expects:
     * // [PASS]  file level test in file "[...]test1.php"
     * // [PASS]  my test for class Foo in file "[...]test1.php"
     * // [PASS]  my test for method Foo::testString in file "[...]test1.php"
     * // [PASS]  method Foo::testBool in file "[...]test1.php"
     * // [PASS]  method Foo::testInt in file "[...]test1.php"
     * // [PASS]  method Foo::testFloat in file "[...]test1.php"
     * // [PASS]  method Foo::testArray in file "[...]test1.php"
     * // [PASS]  method Foo::testObject in file "[...]test1.php"
     * // [PASS]  method Foo::testResource in file "[...]test1.php"
     * // [PASS]  method Foo::testException in file "[...]test1.php"
     * // [PASS]  method Foo::testNull in file "[...]test1.php"
     * // [PASS]  method Foo::testError in file "[...]test1.php"
     * // [PASS]  method Foo::testError in file "[...]test1.php"
     * // [PASS]  method Foo::testError in file "[...]test1.php"
     * // [PASS]  method Foo::testError in file "[...]test1.php"
     * // [PASS]  function testFlags in file "[...]test1.php"
     * // [PASS]  function testFlags in file "[...]test1.php"
     * // [SKIP]  function testFlags in file "[...]test1.php"
     * // [PASS]  function testFlags in file "[...]test1.php"
     * // [PASS]  function multiply in file "[...]test1.php"
     * // [PASS]  function testArray in file "[...]test1.php"
     * // [PASS]  function testArray in file "[...]test1.php"
     * // [PASS]  function testString in file "[...]test1.php"
     * // [PASS]  function testString in file "[...]test1.php"
     * //
     * // Total time    : [...] sec.
     * // Passed tests  : 23
     * // Skipped tests : 1
     * // Failed tests  : 0
     * //
     * </code>
     *
     * @param array $pathes an array of files and/or directories
     *
     * @access public
     * @return void 
     */
    public function run(array $pathes)
    {
        $reg   = Testing_DocTest_Registry::singleton();
        $files = $reg->parser->parse($reg->finder->find($pathes));
        $reg->outputter->begin($files);
        foreach ($files as $file=>$testCaseArray) {
            $reg->outputter->beginFile($file, $testCaseArray);
            foreach ($testCaseArray as $testCase) {
                $reg->outputter->beginTestCase($testCase);
                $reg->runner->run($testCase);
                $reg->outputter->endTestCase($testCase);
                unset($testCase);
            }
            $reg->outputter->endFile($file, $testCaseArray);
        }
        $reg->outputter->end($files);
    }
 
    // }}}
}