Source for file test_case.php

Documentation is available at test_case.php

  1. <?php
  2. /**
  3.  *  Base include file for SimpleTest
  4.  *  @package    SimpleTest
  5.  *  @subpackage UnitTester
  6.  *  @version    $Id: test_case.php 1726 2008-04-08 01:20:10Z lastcraft $
  7.  */
  8.  
  9. /**#@+
  10.  * Includes SimpleTest files and defined the root constant
  11.  * for dependent libraries.
  12.  */
  13. require_once(dirname(__FILE__) . '/invoker.php');
  14. require_once(dirname(__FILE__) . '/errors.php');
  15. require_once(dirname(__FILE__) . '/compatibility.php');
  16. require_once(dirname(__FILE__) . '/scorer.php');
  17. require_once(dirname(__FILE__) . '/expectation.php');
  18. require_once(dirname(__FILE__) . '/dumper.php');
  19. require_once(dirname(__FILE__) . '/simpletest.php');
  20. if (version_compare(phpversion(), '5') >= 0) {
  21.     require_once(dirname(__FILE__) . '/exceptions.php');
  22.     require_once(dirname(__FILE__) . '/reflection_php5.php');
  23. } else {
  24.     require_once(dirname(__FILE__) . '/reflection_php4.php');
  25. }
  26. if (! defined('SIMPLE_TEST')) {
  27.     /**
  28.      * @ignore
  29.      */
  30.     define('SIMPLE_TEST', dirname(__FILE__) . DIRECTORY_SEPARATOR);
  31. }
  32. /**#@-*/
  33.  
  34.  *    Basic test case. This is the smallest unit of a test
  35.  *    suite. It searches for
  36.  *    all methods that start with the the string "test" and
  37.  *    runs them. Working test cases extend this class.
  38.  *    @package      SimpleTest
  39.  *    @subpackage   UnitTester
  40.  */
  41. class SimpleTestCase {
  42.     var $_label = false;
  43.     var $_reporter;
  44.     var $_observers;
  45.     var $_should_skip = false;
  46.  
  47.     /**
  48.      *    Sets up the test with no display.
  49.      *    @param string $label    If no test name is given then
  50.      *                             the class name is used.
  51.      *    @access public
  52.      */
  53.     function SimpleTestCase($label = false) {
  54.         if ($label) {
  55.             $this->_label = $label;
  56.         }
  57.     }
  58.  
  59.     /**
  60.      *    Accessor for the test name for subclasses.
  61.      *    @return string           Name of the test.
  62.      *    @access public
  63.      */
  64.     function getLabel() {
  65.         return $this->_label ? $this->_label : get_class($this);
  66.     }
  67.  
  68.     /**
  69.      *    This is a placeholder for skipping tests. In this
  70.      *    method you place skipIf() and skipUnless() calls to
  71.      *    set the skipping state.
  72.      *    @access public
  73.      */
  74.     function skip() {
  75.     }
  76.  
  77.     /**
  78.      *    Will issue a message to the reporter and tell the test
  79.      *    case to skip if the incoming flag is true.
  80.      *    @param string $should_skip    Condition causing the tests to be skipped.
  81.      *    @param string $message        Text of skip condition.
  82.      *    @access public
  83.      */
  84.     function skipIf($should_skip, $message = '%s') {
  85.         if ($should_skip && ! $this->_should_skip) {
  86.             $this->_should_skip = true;
  87.             $message = sprintf($message, 'Skipping [' . get_class($this) . ']');
  88.             $this->_reporter->paintSkip($message . $this->getAssertionLine());
  89.         }
  90.     }
  91.  
  92.     /**
  93.      *    Will issue a message to the reporter and tell the test
  94.      *    case to skip if the incoming flag is false.
  95.      *    @param string $shouldnt_skip  Condition causing the tests to be run.
  96.      *    @param string $message        Text of skip condition.
  97.      *    @access public
  98.      */
  99.     function skipUnless($shouldnt_skip, $message = false) {
  100.         $this->skipIf(! $shouldnt_skip, $message);
  101.     }
  102.  
  103.     /**
  104.      *    Used to invoke the single tests.
  105.      *    @return SimpleInvoker        Individual test runner.
  106.      *    @access public
  107.      */
  108.     function &createInvoker() {
  109.         $invoker = &new SimpleErrorTrappingInvoker(new SimpleInvoker($this));
  110.         if (version_compare(phpversion(), '5') >= 0) {
  111.             $invoker = &new SimpleExceptionTrappingInvoker($invoker);
  112.         }
  113.         return $invoker;
  114.     }
  115.  
  116.     /**
  117.      *    Uses reflection to run every method within itself
  118.      *    starting with the string "test" unless a method
  119.      *    is specified.
  120.      *    @param SimpleReporter $reporter    Current test reporter.
  121.      *    @return boolean                    True if all tests passed.
  122.      *    @access public
  123.      */
  124.     function run(&$reporter) {
  125.         $context = &SimpleTest::getContext();
  126.         $context->setTest($this);
  127.         $context->setReporter($reporter);
  128.         $this->_reporter = &$reporter;
  129.         $started = false;
  130.         foreach ($this->getTests() as $method) {
  131.             if ($reporter->shouldInvoke($this->getLabel(), $method)) {
  132.                 $this->skip();
  133.                 if ($this->_should_skip) {
  134.                     break;
  135.                 }
  136.                 if (! $started) {
  137.                     $reporter->paintCaseStart($this->getLabel());
  138.                     $started = true;
  139.                 }
  140.                 $invoker = &$this->_reporter->createInvoker($this->createInvoker());
  141.                 $invoker->before($method);
  142.                 $invoker->invoke($method);
  143.                 $invoker->after($method);
  144.             }
  145.         }
  146.         if ($started) {
  147.             $reporter->paintCaseEnd($this->getLabel());
  148.         }
  149.         unset($this->_reporter);
  150.         return $reporter->getStatus();
  151.     }
  152.  
  153.     /**
  154.      *    Gets a list of test names. Normally that will
  155.      *    be all internal methods that start with the
  156.      *    name "test". This method should be overridden
  157.      *    if you want a different rule.
  158.      *    @return array        List of test names.
  159.      *    @access public
  160.      */
  161.     function getTests() {
  162.         $methods = array();
  163.         foreach (get_class_methods(get_class($this)) as $method) {
  164.             if ($this->_isTest($method)) {
  165.                 $methods[] = $method;
  166.             }
  167.         }
  168.         return $methods;
  169.     }
  170.  
  171.     /**
  172.      *    Tests to see if the method is a test that should
  173.      *    be run. Currently any method that starts with 'test'
  174.      *    is a candidate unless it is the constructor.
  175.      *    @param string $method        Method name to try.
  176.      *    @return boolean              True if test method.
  177.      *    @access protected
  178.      */
  179.     function _isTest($method) {
  180.         if (strtolower(substr($method, 0, 4)) == 'test') {
  181.             return ! SimpleTestCompatibility::isA($this, strtolower($method));
  182.         }
  183.         return false;
  184.     }
  185.  
  186.     /**
  187.      *    Announces the start of the test.
  188.      *    @param string $method    Test method just started.
  189.      *    @access public
  190.      */
  191.     function before($method) {
  192.         $this->_reporter->paintMethodStart($method);
  193.         $this->_observers = array();
  194.     }
  195.  
  196.     /**
  197.      *    Sets up unit test wide variables at the start
  198.      *    of each test method. To be overridden in
  199.      *    actual user test cases.
  200.      *    @access public
  201.      */
  202.     function setUp() {
  203.     }
  204.  
  205.     /**
  206.      *    Clears the data set in the setUp() method call.
  207.      *    To be overridden by the user in actual user test cases.
  208.      *    @access public
  209.      */
  210.     function tearDown() {
  211.     }
  212.  
  213.     /**
  214.      *    Announces the end of the test. Includes private clean up.
  215.      *    @param string $method    Test method just finished.
  216.      *    @access public
  217.      */
  218.     function after($method) {
  219.         for ($i = 0; $i < count($this->_observers); $i++) {
  220.             $this->_observers[$i]->atTestEnd($method, $this);
  221.         }
  222.         $this->_reporter->paintMethodEnd($method);
  223.     }
  224.  
  225.     /**
  226.      *    Sets up an observer for the test end.
  227.      *    @param object $observer    Must have atTestEnd()
  228.      *                                method.
  229.      *    @access public
  230.      */
  231.     function tell(&$observer) {
  232.         $this->_observers[] = &$observer;
  233.     }
  234.  
  235.     /**
  236.      *    @deprecated
  237.      */
  238.     function pass($message = "Pass") {
  239.         if (! isset($this->_reporter)) {
  240.             trigger_error('Can only make assertions within test methods');
  241.         }
  242.         $this->_reporter->paintPass(
  243.                 $message . $this->getAssertionLine());
  244.         return true;
  245.     }
  246.  
  247.     /**
  248.      *    Sends a fail event with a message.
  249.      *    @param string $message        Message to send.
  250.      *    @access public
  251.      */
  252.     function fail($message = "Fail") {
  253.         if (! isset($this->_reporter)) {
  254.             trigger_error('Can only make assertions within test methods');
  255.         }
  256.         $this->_reporter->paintFail(
  257.                 $message . $this->getAssertionLine());
  258.         return false;
  259.     }
  260.  
  261.     /**
  262.      *    Formats a PHP error and dispatches it to the
  263.      *    reporter.
  264.      *    @param integer $severity  PHP error code.
  265.      *    @param string $message    Text of error.
  266.      *    @param string $file       File error occoured in.
  267.      *    @param integer $line      Line number of error.
  268.      *    @access public
  269.      */
  270.     function error($severity, $message, $file, $line) {
  271.         if (! isset($this->_reporter)) {
  272.             trigger_error('Can only make assertions within test methods');
  273.         }
  274.         $this->_reporter->paintError(
  275.                 "Unexpected PHP error [$message] severity [$severity] in [$file line $line]");
  276.     }
  277.  
  278.     /**
  279.      *    Formats an exception and dispatches it to the
  280.      *    reporter.
  281.      *    @param Exception $exception    Object thrown.
  282.      *    @access public
  283.      */
  284.     function exception($exception) {
  285.         $this->_reporter->paintException($exception);
  286.     }
  287.  
  288.     /**
  289.      *    @deprecated
  290.      */
  291.     function signal($type, &$payload) {
  292.         if (! isset($this->_reporter)) {
  293.             trigger_error('Can only make assertions within test methods');
  294.         }
  295.         $this->_reporter->paintSignal($type, $payload);
  296.     }
  297.  
  298.     /**
  299.      *    Runs an expectation directly, for extending the
  300.      *    tests with new expectation classes.
  301.      *    @param SimpleExpectation $expectation  Expectation subclass.
  302.      *    @param mixed $compare               Value to compare.
  303.      *    @param string $message                 Message to display.
  304.      *    @return boolean                        True on pass
  305.      *    @access public
  306.      */
  307.     function assert(&$expectation, $compare, $message = '%s') {
  308.         if ($expectation->test($compare)) {
  309.             return $this->pass(sprintf(
  310.                     $message,
  311.                     $expectation->overlayMessage($compare, $this->_reporter->getDumper())));
  312.         } else {
  313.             return $this->fail(sprintf(
  314.                     $message,
  315.                     $expectation->overlayMessage($compare, $this->_reporter->getDumper())));
  316.         }
  317.     }
  318.  
  319.     /**
  320.      *    @deprecated
  321.      */
  322.     function assertExpectation(&$expectation, $compare, $message = '%s') {
  323.         return $this->assert($expectation, $compare, $message);
  324.     }
  325.  
  326.     /**
  327.      *    Uses a stack trace to find the line of an assertion.
  328.      *    @return string           Line number of first assert*
  329.      *                              method embedded in format string.
  330.      *    @access public
  331.      */
  332.     function getAssertionLine() {
  333.         $trace = new SimpleStackTrace(array('assert', 'expect', 'pass', 'fail', 'skip'));
  334.         return $trace->traceMethod();
  335.     }
  336.  
  337.     /**
  338.      *    Sends a formatted dump of a variable to the
  339.      *    test suite for those emergency debugging
  340.      *    situations.
  341.      *    @param mixed $variable    Variable to display.
  342.      *    @param string $message    Message to display.
  343.      *    @return mixed             The original variable.
  344.      *    @access public
  345.      */
  346.     function dump($variable, $message = false) {
  347.         $dumper = $this->_reporter->getDumper();
  348.         $formatted = $dumper->dump($variable);
  349.         if ($message) {
  350.             $formatted = $message . "\n" . $formatted;
  351.         }
  352.         $this->_reporter->paintFormattedMessage($formatted);
  353.         return $variable;
  354.     }
  355.  
  356.     /**
  357.      *    @deprecated
  358.      */
  359.     function sendMessage($message) {
  360.         $this->_reporter->PaintMessage($message);
  361.     }
  362.  
  363.     /**
  364.      *    Accessor for the number of subtests including myelf.
  365.      *    @return integer           Number of test cases.
  366.      *    @access public
  367.      *    @static
  368.      */
  369.     function getSize() {
  370.         return 1;
  371.     }
  372. }
  373.  
  374. /**
  375.  *  Helps to extract test cases automatically from a file.
  376.  */
  377. class SimpleFileLoader {
  378.  
  379.     /**
  380.      *    Builds a test suite from a library of test cases.
  381.      *    The new suite is composed into this one.
  382.      *    @param string $test_file        File name of library with
  383.      *                                     test case classes.
  384.      *    @return TestSuite               The new test suite.
  385.      *    @access public
  386.      */
  387.     function &load($test_file) {
  388.         $existing_classes = get_declared_classes();
  389.         $existing_globals = get_defined_vars();
  390.         include_once($test_file);
  391.         $new_globals = get_defined_vars();
  392.         $this->_makeFileVariablesGlobal($existing_globals, $new_globals);
  393.         $new_classes = array_diff(get_declared_classes(), $existing_classes);
  394.         if (empty($new_classes)) {
  395.             $new_classes = $this->_scrapeClassesFromFile($test_file);
  396.         }
  397.         $classes = $this->selectRunnableTests($new_classes);
  398.         $suite = &$this->createSuiteFromClasses($test_file, $classes);
  399.         return $suite;
  400.     }
  401.     
  402.     /**
  403.      *    Imports new variables into the global namespace.
  404.      *    @param hash $existing   Variables before the file was loaded.
  405.      *    @param hash $new        Variables after the file was loaded.
  406.      *    @access private
  407.      */
  408.     function _makeFileVariablesGlobal($existing, $new) {
  409.         $globals = array_diff(array_keys($new), array_keys($existing));
  410.         foreach ($globals as $global) {
  411.             $_GLOBALS[$global] = $new[$global];
  412.         }
  413.     }
  414.     
  415.     /**
  416.      *    Lookup classnames from file contents, in case the
  417.      *    file may have been included before.
  418.      *    Note: This is probably too clever by half. Figuring this
  419.      *    out after a failed test case is going to be tricky for us,
  420.      *    never mind the user. A test case should not be included
  421.      *    twice anyway.
  422.      *    @param string $test_file        File name with classes.
  423.      *    @access private
  424.      */
  425.     function _scrapeClassesFromFile($test_file) {
  426.         preg_match_all('~^\s*class\s+(\w+)(\s+(extends|implements)\s+\w+)*\s*\{~mi',
  427.                         file_get_contents($test_file),
  428.                         $matches );
  429.         return $matches[1];
  430.     }
  431.  
  432.     /**
  433.      *    Calculates the incoming test cases. Skips abstract
  434.      *    and ignored classes.
  435.      *    @param array $candidates   Candidate classes.
  436.      *    @return array              New classes which are test
  437.      *                                cases that shouldn't be ignored.
  438.      *    @access public
  439.      */
  440.     function selectRunnableTests($candidates) {
  441.         $classes = array();
  442.         foreach ($candidates as $class) {
  443.             if (TestSuite::getBaseTestCase($class)) {
  444.                 $reflection = new SimpleReflection($class);
  445.                 if ($reflection->isAbstract()) {
  446.                     SimpleTest::ignore($class);
  447.                 } else {
  448.                     $classes[] = $class;
  449.                 }
  450.             }
  451.         }
  452.         return $classes;
  453.     }
  454.  
  455.     /**
  456.      *    Builds a test suite from a class list.
  457.      *    @param string $title       Title of new group.
  458.      *    @param array $classes      Test classes.
  459.      *    @return TestSuite          Group loaded with the new
  460.      *                                test cases.
  461.      *    @access public
  462.      */
  463.     function &createSuiteFromClasses($title, $classes) {
  464.         if (count($classes) == 0) {
  465.             $suite = &new BadTestSuite($title, "No runnable test cases in [$title]");
  466.             return $suite;
  467.         }
  468.         SimpleTest::ignoreParentsIfIgnored($classes);
  469.         $suite = &new TestSuite($title);
  470.         foreach ($classes as $class) {
  471.             if (! SimpleTest::isIgnored($class)) {
  472.                 $suite->addTestClass($class);
  473.             }
  474.         }
  475.         return $suite;
  476.     }
  477. }
  478.  
  479. /**
  480.  *    This is a composite test class for combining
  481.  *    test cases and other RunnableTest classes into
  482.  *    a group test.
  483.  *    @package      SimpleTest
  484.  *    @subpackage   UnitTester
  485.  */
  486. class TestSuite {
  487.     var $_label;
  488.     var $_test_cases;
  489.  
  490.     /**
  491.      *    Sets the name of the test suite.
  492.      *    @param string $label    Name sent at the start and end
  493.      *                             of the test.
  494.      *    @access public
  495.      */
  496.     function TestSuite($label = false) {
  497.         $this->_label = $label;
  498.         $this->_test_cases = array();
  499.     }
  500.  
  501.     /**
  502.      *    Accessor for the test name for subclasses. If the suite
  503.      *    wraps a single test case the label defaults to the name of that test.
  504.      *    @return string           Name of the test.
  505.      *    @access public
  506.      */
  507.     function getLabel() {
  508.         if (! $this->_label) {
  509.             return ($this->getSize() == 1) ?
  510.                     get_class($this->_test_cases[0]) : get_class($this);
  511.         } else {
  512.             return $this->_label;
  513.         }
  514.     }
  515.  
  516.     /**
  517.      *    @deprecated
  518.      */
  519.     function addTestCase(&$test_case) {
  520.         $this->_test_cases[] = &$test_case;
  521.     }
  522.  
  523.     /**
  524.      *    @deprecated
  525.      */
  526.     function addTestClass($class) {
  527.         if (TestSuite::getBaseTestCase($class) == 'testsuite') {
  528.             $this->_test_cases[] = &new $class();
  529.         } else {
  530.             $this->_test_cases[] = $class;
  531.         }
  532.     }
  533.  
  534.     /**
  535.      *    Adds a test into the suite by instance or class. The class will
  536.      *    be instantiated if it's a test suite.
  537.      *    @param SimpleTestCase $test_case  Suite or individual test
  538.      *                                       case implementing the
  539.      *                                       runnable test interface.
  540.      *    @access public
  541.      */
  542.     function add(&$test_case) {
  543.         if (! is_string($test_case)) {
  544.             $this->_test_cases[] = &$test_case;
  545.         } elseif (TestSuite::getBaseTestCase($class) == 'testsuite') {
  546.             $this->_test_cases[] = &new $class();
  547.         } else {
  548.             $this->_test_cases[] = $class;
  549.         }
  550.     }
  551.  
  552.     /**
  553.      *    @deprecated
  554.      */
  555.     function addTestFile($test_file) {
  556.         $this->addFile($test_file);
  557.     }
  558.  
  559.     /**
  560.      *    Builds a test suite from a library of test cases.
  561.      *    The new suite is composed into this one.
  562.      *    @param string $test_file        File name of library with
  563.      *                                     test case classes.
  564.      *    @access public
  565.      */
  566.     function addFile($test_file) {
  567.         $extractor = new SimpleFileLoader();
  568.         $this->add($extractor->load($test_file));
  569.     }
  570.  
  571.     /**
  572.      *    Delegates to a visiting collector to add test
  573.      *    files.
  574.      *    @param string $path                  Path to scan from.
  575.      *    @param SimpleCollector $collector    Directory scanner.
  576.      *    @access public
  577.      */
  578.     function collect($path, &$collector) {
  579.         $collector->collect($this, $path);
  580.     }
  581.  
  582.     /**
  583.      *    Invokes run() on all of the held test cases, instantiating
  584.      *    them if necessary.
  585.      *    @param SimpleReporter $reporter    Current test reporter.
  586.      *    @access public
  587.      */
  588.     function run(&$reporter) {
  589.         $reporter->paintGroupStart($this->getLabel(), $this->getSize());
  590.         for ($i = 0, $count = count($this->_test_cases); $i < $count; $i++) {
  591.             if (is_string($this->_test_cases[$i])) {
  592.                 $class = $this->_test_cases[$i];
  593.                 $test = &new $class();
  594.                 $test->run($reporter);
  595.                 unset($test);
  596.             } else {
  597.                 $this->_test_cases[$i]->run($reporter);
  598.             }
  599.         }
  600.         $reporter->paintGroupEnd($this->getLabel());
  601.         return $reporter->getStatus();
  602.     }
  603.  
  604.     /**
  605.      *    Number of contained test cases.
  606.      *    @return integer     Total count of cases in the group.
  607.      *    @access public
  608.      */
  609.     function getSize() {
  610.         $count = 0;
  611.         foreach ($this->_test_cases as $case) {
  612.             if (is_string($case)) {
  613.                 if (! SimpleTest::isIgnored($case)) {
  614.                     $count++;
  615.                 }
  616.             } else {
  617.                 $count += $case->getSize();
  618.             }
  619.         }
  620.         return $count;
  621.     }
  622.  
  623.     /**
  624.      *    Test to see if a class is derived from the
  625.      *    SimpleTestCase class.
  626.      *    @param string $class     Class name.
  627.      *    @access public
  628.      *    @static
  629.      */
  630.     function getBaseTestCase($class) {
  631.         while ($class = get_parent_class($class)) {
  632.             $class = strtolower($class);
  633.             if ($class == 'simpletestcase' || $class == 'testsuite') {
  634.                 return $class;
  635.             }
  636.         }
  637.         return false;
  638.     }
  639. }
  640.  
  641. /**
  642.  *    @package      SimpleTest
  643.  *    @subpackage   UnitTester
  644.  *    @deprecated
  645.  */
  646. class GroupTest extends TestSuite { }
  647.  
  648. /**
  649.  *    This is a failing group test for when a test suite hasn't
  650.  *    loaded properly.
  651.  *    @package      SimpleTest
  652.  *    @subpackage   UnitTester
  653.  */
  654. class BadTestSuite {
  655.     var $_label;
  656.     var $_error;
  657.  
  658.     /**
  659.      *    Sets the name of the test suite and error message.
  660.      *    @param string $label    Name sent at the start and end
  661.      *                             of the test.
  662.      *    @access public
  663.      */
  664.     function BadTestSuite($label, $error) {
  665.         $this->_label = $label;
  666.         $this->_error = $error;
  667.     }
  668.  
  669.     /**
  670.      *    Accessor for the test name for subclasses.
  671.      *    @return string           Name of the test.
  672.      *    @access public
  673.      */
  674.     function getLabel() {
  675.         return $this->_label;
  676.     }
  677.  
  678.     /**
  679.      *    Sends a single error to the reporter.
  680.      *    @param SimpleReporter $reporter    Current test reporter.
  681.      *    @access public
  682.      */
  683.     function run(&$reporter) {
  684.         $reporter->paintGroupStart($this->getLabel(), $this->getSize());
  685.         $reporter->paintFail('Bad TestSuite [' . $this->getLabel() .
  686.                 '] with error [' . $this->_error . ']');
  687.         $reporter->paintGroupEnd($this->getLabel());
  688.         return $reporter->getStatus();
  689.     }
  690.  
  691.     /**
  692.      *    Number of contained test cases. Always zero.
  693.      *    @return integer     Total count of cases in the group.
  694.      *    @access public
  695.      */
  696.     function getSize() {
  697.         return 0;
  698.     }
  699. }
  700.  
  701. /**
  702.  *    @package      SimpleTest
  703.  *    @subpackage   UnitTester
  704.  *    @deprecated
  705.  */
  706. class BadGroupTest extends BadTestSuite { }
  707. ?>

Documentation generated on Sun, 04 May 2008 09:22:18 -0500 by phpDocumentor 1.3.0