Source for file web_tester.php

Documentation is available at web_tester.php

  1. <?php
  2. /**
  3.  *  Base include file for SimpleTest.
  4.  *  @package    SimpleTest
  5.  *  @subpackage WebTester
  6.  *  @version    $Id: web_tester.php 1723 2008-04-08 00:34:10Z lastcraft $
  7.  */
  8.  
  9. /**#@+
  10.  *  include other SimpleTest class files
  11.  */
  12. require_once(dirname(__FILE__) . '/test_case.php');
  13. require_once(dirname(__FILE__) . '/browser.php');
  14. require_once(dirname(__FILE__) . '/page.php');
  15. require_once(dirname(__FILE__) . '/expectation.php');
  16. /**#@-*/
  17.  
  18.  *    Test for an HTML widget value match.
  19.  *    @package SimpleTest
  20.  *    @subpackage WebTester
  21.  */
  22. class FieldExpectation extends SimpleExpectation {
  23.     var $_value;
  24.     
  25.     /**
  26.      *    Sets the field value to compare against.
  27.      *    @param mixed $value     Test value to match. Can be an
  28.      *                             expectation for say pattern matching.
  29.      *    @param string $message  Optiona message override. Can use %s as
  30.      *                             a placeholder for the original message.
  31.      *    @access public
  32.      */
  33.     function FieldExpectation($value, $message = '%s') {
  34.         $this->SimpleExpectation($message);
  35.         if (is_array($value)) {
  36.             sort($value);
  37.         }
  38.         $this->_value = $value;
  39.     }
  40.     
  41.     /**
  42.      *    Tests the expectation. True if it matches
  43.      *    a string value or an array value in any order.
  44.      *    @param mixed $compare        Comparison value. False for
  45.      *                                  an unset field.
  46.      *    @return boolean              True if correct.
  47.      *    @access public
  48.      */
  49.     function test($compare) {
  50.         if ($this->_value === false) {
  51.             return ($compare === false);
  52.         }
  53.         if ($this->_isSingle($this->_value)) {
  54.             return $this->_testSingle($compare);
  55.         }
  56.         if (is_array($this->_value)) {
  57.             return $this->_testMultiple($compare);
  58.         }
  59.         return false;
  60.     }
  61.     
  62.     /**
  63.      *    Tests for valid field comparisons with a single option.
  64.      *    @param mixed $value       Value to type check.
  65.      *    @return boolean           True if integer, string or float.
  66.      *    @access private
  67.      */
  68.     function _isSingle($value) {
  69.         return is_string($value) || is_integer($value) || is_float($value);
  70.     }
  71.     
  72.     /**
  73.      *    String comparison for simple field with a single option.
  74.      *    @param mixed $compare    String to test against.
  75.      *    @returns boolean         True if matching.
  76.      *    @access private
  77.      */
  78.     function _testSingle($compare) {
  79.         if (is_array($compare) && count($compare) == 1) {
  80.             $compare = $compare[0];
  81.         }
  82.         if (! $this->_isSingle($compare)) {
  83.             return false;
  84.         }
  85.         return ($this->_value == $compare);
  86.     }
  87.     
  88.     /**
  89.      *    List comparison for multivalue field.
  90.      *    @param mixed $compare    List in any order to test against.
  91.      *    @returns boolean         True if matching.
  92.      *    @access private
  93.      */
  94.     function _testMultiple($compare) {
  95.         if (is_string($compare)) {
  96.             $compare = array($compare);
  97.         }
  98.         if (! is_array($compare)) {
  99.             return false;
  100.         }
  101.         sort($compare);
  102.         return ($this->_value === $compare);
  103.     }
  104.     
  105.     /**
  106.      *    Returns a human readable test message.
  107.      *    @param mixed $compare      Comparison value.
  108.      *    @return string             Description of success
  109.      *                                or failure.
  110.      *    @access public
  111.      */
  112.     function testMessage($compare) {
  113.         $dumper = &$this->_getDumper();
  114.         if (is_array($compare)) {
  115.             sort($compare);
  116.         }
  117.         if ($this->test($compare)) {
  118.             return "Field expectation [" . $dumper->describeValue($this->_value) . "]";
  119.         } else {
  120.             return "Field expectation [" . $dumper->describeValue($this->_value) .
  121.                     "] fails with [" .
  122.                     $dumper->describeValue($compare) . "] " .
  123.                     $dumper->describeDifference($this->_value, $compare);
  124.         }
  125.     }
  126. }
  127.  
  128. /**
  129.  *    Test for a specific HTTP header within a header block.
  130.  *    @package SimpleTest
  131.  *    @subpackage WebTester
  132.  */
  133. class HttpHeaderExpectation extends SimpleExpectation {
  134.     var $_expected_header;
  135.     var $_expected_value;
  136.     
  137.     /**
  138.      *    Sets the field and value to compare against.
  139.      *    @param string $header   Case insenstive trimmed header name.
  140.      *    @param mixed $value     Optional value to compare. If not
  141.      *                             given then any value will match. If
  142.      *                             an expectation object then that will
  143.      *                             be used instead.
  144.      *    @param string $message  Optiona message override. Can use %s as
  145.      *                             a placeholder for the original message.
  146.      */
  147.     function HttpHeaderExpectation($header, $value = false, $message = '%s') {
  148.         $this->SimpleExpectation($message);
  149.         $this->_expected_header = $this->_normaliseHeader($header);
  150.         $this->_expected_value = $value;
  151.     }
  152.     
  153.     /**
  154.      *    Accessor for aggregated object.
  155.      *    @return mixed        Expectation set in constructor.
  156.      *    @access protected
  157.      */
  158.     function _getExpectation() {
  159.         return $this->_expected_value;
  160.     }
  161.     
  162.     /**
  163.      *    Removes whitespace at ends and case variations.
  164.      *    @param string $header    Name of header.
  165.      *    @param string            Trimmed and lowecased header
  166.      *                              name.
  167.      *    @access private
  168.      */
  169.     function _normaliseHeader($header) {
  170.         return strtolower(trim($header));
  171.     }
  172.     
  173.     /**
  174.      *    Tests the expectation. True if it matches
  175.      *    a string value or an array value in any order.
  176.      *    @param mixed $compare   Raw header block to search.
  177.      *    @return boolean         True if header present.
  178.      *    @access public
  179.      */
  180.     function test($compare) {
  181.         return is_string($this->_findHeader($compare));
  182.     }
  183.     
  184.     /**
  185.      *    Searches the incoming result. Will extract the matching
  186.      *    line as text.
  187.      *    @param mixed $compare   Raw header block to search.
  188.      *    @return string          Matching header line.
  189.      *    @access protected
  190.      */
  191.     function _findHeader($compare) {
  192.         $lines = split("\r\n", $compare);
  193.         foreach ($lines as $line) {
  194.             if ($this->_testHeaderLine($line)) {
  195.                 return $line;
  196.             }
  197.         }
  198.         return false;
  199.     }
  200.     
  201.     /**
  202.      *    Compares a single header line against the expectation.
  203.      *    @param string $line      A single line to compare.
  204.      *    @return boolean          True if matched.
  205.      *    @access private
  206.      */
  207.     function _testHeaderLine($line) {
  208.         if (count($parsed = split(':', $line, 2)) < 2) {
  209.             return false;
  210.         }
  211.         list($header, $value) = $parsed;
  212.         if ($this->_normaliseHeader($header) != $this->_expected_header) {
  213.             return false;
  214.         }
  215.         return $this->_testHeaderValue($value, $this->_expected_value);
  216.     }
  217.     
  218.     /**
  219.      *    Tests the value part of the header.
  220.      *    @param string $value        Value to test.
  221.      *    @param mixed $expected      Value to test against.
  222.      *    @return boolean             True if matched.
  223.      *    @access protected
  224.      */
  225.     function _testHeaderValue($value, $expected) {
  226.         if ($expected === false) {
  227.             return true;
  228.         }
  229.         if (SimpleExpectation::isExpectation($expected)) {
  230.             return $expected->test(trim($value));
  231.         }
  232.         return (trim($value) == trim($expected));
  233.     }
  234.     
  235.     /**
  236.      *    Returns a human readable test message.
  237.      *    @param mixed $compare      Raw header block to search.
  238.      *    @return string             Description of success
  239.      *                                or failure.
  240.      *    @access public
  241.      */
  242.     function testMessage($compare) {
  243.         if (SimpleExpectation::isExpectation($this->_expected_value)) {
  244.             $message = $this->_expected_value->overlayMessage($compare, $this->_getDumper());
  245.         } else {
  246.             $message = $this->_expected_header .
  247.                     ($this->_expected_value ? ': ' . $this->_expected_value : '');
  248.         }
  249.         if (is_string($line = $this->_findHeader($compare))) {
  250.             return "Searching for header [$message] found [$line]";
  251.         } else {
  252.             return "Failed to find header [$message]";
  253.         }
  254.     }
  255. }
  256.     
  257. /**
  258.  *    Test for a specific HTTP header within a header block that
  259.  *    should not be found.
  260.  *    @package SimpleTest
  261.  *    @subpackage WebTester
  262.  */
  263. class NoHttpHeaderExpectation extends HttpHeaderExpectation {
  264.     var $_expected_header;
  265.     var $_expected_value;
  266.     
  267.     /**
  268.      *    Sets the field and value to compare against.
  269.      *    @param string $unwanted   Case insenstive trimmed header name.
  270.      *    @param string $message    Optiona message override. Can use %s as
  271.      *                               a placeholder for the original message.
  272.      */
  273.     function NoHttpHeaderExpectation($unwanted, $message = '%s') {
  274.         $this->HttpHeaderExpectation($unwanted, false, $message);
  275.     }
  276.     
  277.     /**
  278.      *    Tests that the unwanted header is not found.
  279.      *    @param mixed $compare   Raw header block to search.
  280.      *    @return boolean         True if header present.
  281.      *    @access public
  282.      */
  283.     function test($compare) {
  284.         return ($this->_findHeader($compare) === false);
  285.     }
  286.     
  287.     /**
  288.      *    Returns a human readable test message.
  289.      *    @param mixed $compare      Raw header block to search.
  290.      *    @return string             Description of success
  291.      *                                or failure.
  292.      *    @access public
  293.      */
  294.     function testMessage($compare) {
  295.         $expectation = $this->_getExpectation();
  296.         if (is_string($line = $this->_findHeader($compare))) {
  297.             return "Found unwanted header [$expectation] with [$line]";
  298.         } else {
  299.             return "Did not find unwanted header [$expectation]";
  300.         }
  301.     }
  302. }
  303.  
  304. /**
  305.  *    Test for a text substring.
  306.  *    @package SimpleTest
  307.  *    @subpackage UnitTester
  308.  */
  309. class TextExpectation extends SimpleExpectation {
  310.     var $_substring;
  311.     
  312.     /**
  313.      *    Sets the value to compare against.
  314.      *    @param string $substring  Text to search for.
  315.      *    @param string $message    Customised message on failure.
  316.      *    @access public
  317.      */
  318.     function TextExpectation($substring, $message = '%s') {
  319.         $this->SimpleExpectation($message);
  320.         $this->_substring = $substring;
  321.     }
  322.     
  323.     /**
  324.      *    Accessor for the substring.
  325.      *    @return string       Text to match.
  326.      *    @access protected
  327.      */
  328.     function _getSubstring() {
  329.         return $this->_substring;
  330.     }
  331.     
  332.     /**
  333.      *    Tests the expectation. True if the text contains the
  334.      *    substring.
  335.      *    @param string $compare        Comparison value.
  336.      *    @return boolean               True if correct.
  337.      *    @access public
  338.      */
  339.     function test($compare) {
  340.         return (strpos($compare, $this->_substring) !== false);
  341.     }
  342.     
  343.     /**
  344.      *    Returns a human readable test message.
  345.      *    @param mixed $compare      Comparison value.
  346.      *    @return string             Description of success
  347.      *                                or failure.
  348.      *    @access public
  349.      */
  350.     function testMessage($compare) {
  351.         if ($this->test($compare)) {
  352.             return $this->_describeTextMatch($this->_getSubstring(), $compare);
  353.         } else {
  354.             $dumper = &$this->_getDumper();
  355.             return "Text [" . $this->_getSubstring() .
  356.                     "] not detected in [" .
  357.                     $dumper->describeValue($compare) . "]";
  358.         }
  359.     }
  360.     
  361.     /**
  362.      *    Describes a pattern match including the string
  363.      *    found and it's position.
  364.      *    @param string $substring      Text to search for.
  365.      *    @param string $subject        Subject to search.
  366.      *    @access protected
  367.      */
  368.     function _describeTextMatch($substring, $subject) {
  369.         $position = strpos($subject, $substring);
  370.         $dumper = &$this->_getDumper();
  371.         return "Text [$substring] detected at character [$position] in [" .
  372.                 $dumper->describeValue($subject) . "] in region [" .
  373.                 $dumper->clipString($subject, 100, $position) . "]";
  374.     }
  375. }
  376.  
  377. /**
  378.  *    Fail if a substring is detected within the
  379.  *    comparison text.
  380.  *    @package SimpleTest
  381.  *    @subpackage UnitTester
  382.  */
  383. class NoTextExpectation extends TextExpectation {
  384.     
  385.     /**
  386.      *    Sets the reject pattern
  387.      *    @param string $substring  Text to search for.
  388.      *    @param string $message    Customised message on failure.
  389.      *    @access public
  390.      */
  391.     function NoTextExpectation($substring, $message = '%s') {
  392.         $this->TextExpectation($substring, $message);
  393.     }
  394.     
  395.     /**
  396.      *    Tests the expectation. False if the substring appears
  397.      *    in the text.
  398.      *    @param string $compare        Comparison value.
  399.      *    @return boolean               True if correct.
  400.      *    @access public
  401.      */
  402.     function test($compare) {
  403.         return ! parent::test($compare);
  404.     }
  405.     
  406.     /**
  407.      *    Returns a human readable test message.
  408.      *    @param string $compare      Comparison value.
  409.      *    @return string              Description of success
  410.      *                                 or failure.
  411.      *    @access public
  412.      */
  413.     function testMessage($compare) {
  414.         if ($this->test($compare)) {
  415.             $dumper = &$this->_getDumper();
  416.             return "Text [" . $this->_getSubstring() .
  417.                     "] not detected in [" .
  418.                     $dumper->describeValue($compare) . "]";
  419.         } else {
  420.             return $this->_describeTextMatch($this->_getSubstring(), $compare);
  421.         }
  422.     }
  423. }
  424.  
  425. /**
  426.  *    Test case for testing of web pages. Allows
  427.  *    fetching of pages, parsing of HTML and
  428.  *    submitting forms.
  429.  *    @package SimpleTest
  430.  *    @subpackage WebTester
  431.  */
  432. class WebTestCase extends SimpleTestCase {
  433.     var $_browser;
  434.     var $_ignore_errors = false;
  435.     
  436.     /**
  437.      *    Creates an empty test case. Should be subclassed
  438.      *    with test methods for a functional test case.
  439.      *    @param string $label     Name of test case. Will use
  440.      *                              the class name if none specified.
  441.      *    @access public
  442.      */
  443.     function WebTestCase($label = false) {
  444.         $this->SimpleTestCase($label);
  445.     }
  446.     
  447.     /**
  448.      *    Announces the start of the test.
  449.      *    @param string $method    Test method just started.
  450.      *    @access public
  451.      */
  452.     function before($method) {
  453.         parent::before($method);
  454.         $this->setBrowser($this->createBrowser());
  455.     }
  456.  
  457.     /**
  458.      *    Announces the end of the test. Includes private clean up.
  459.      *    @param string $method    Test method just finished.
  460.      *    @access public
  461.      */
  462.     function after($method) {
  463.         $this->unsetBrowser();
  464.         parent::after($method);
  465.     }
  466.     
  467.     /**
  468.      *    Gets a current browser reference for setting
  469.      *    special expectations or for detailed
  470.      *    examination of page fetches.
  471.      *    @return SimpleBrowser     Current test browser object.
  472.      *    @access public
  473.      */
  474.     function &getBrowser() {
  475.         return $this->_browser;
  476.     }
  477.     
  478.     /**
  479.      *    Gets a current browser reference for setting
  480.      *    special expectations or for detailed
  481.      *    examination of page fetches.
  482.      *    @param SimpleBrowser $browser    New test browser object.
  483.      *    @access public
  484.      */
  485.     function setBrowser(&$browser) {
  486.         return $this->_browser = &$browser;
  487.     }
  488.         
  489.     /**
  490.      *    Clears the current browser reference to help the
  491.      *    PHP garbage collector.
  492.      *    @access public
  493.      */
  494.     function unsetBrowser() {
  495.         unset($this->_browser);
  496.     }
  497.     
  498.     /**
  499.      *    Creates a new default web browser object.
  500.      *    Will be cleared at the end of the test method.
  501.      *    @return TestBrowser           New browser.
  502.      *    @access public
  503.      */
  504.     function &createBrowser() {
  505.         $browser = &new SimpleBrowser();
  506.         return $browser;
  507.     }
  508.     
  509.     /**
  510.      *    Gets the last response error.
  511.      *    @return string    Last low level HTTP error.
  512.      *    @access public
  513.      */
  514.     function getTransportError() {
  515.         return $this->_browser->getTransportError();
  516.     }
  517.         
  518.     /**
  519.      *    Accessor for the currently selected URL.
  520.      * &n