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.      *    @return string        Current location or false if
  521.      *                           no page yet fetched.
  522.      *    @access public
  523.      */
  524.     function getUrl() {
  525.         return $this->_browser->getUrl();
  526.     }
  527.     
  528.     /**
  529.      *    Dumps the current request for debugging.
  530.      *    @access public
  531.      */
  532.     function showRequest() {
  533.         $this->dump($this->_browser->getRequest());
  534.     }
  535.     
  536.     /**
  537.      *    Dumps the current HTTP headers for debugging.
  538.      *    @access public
  539.      */
  540.     function showHeaders() {
  541.         $this->dump($this->_browser->getHeaders());
  542.     }
  543.     
  544.     /**
  545.      *    Dumps the current HTML source for debugging.
  546.      *    @access public
  547.      */
  548.     function showSource() {
  549.         $this->dump($this->_browser->getContent());
  550.     }
  551.     
  552.     /**
  553.      *    Dumps the visible text only for debugging.
  554.      *    @access public
  555.      */
  556.     function showText() {
  557.         $this->dump(wordwrap($this->_browser->getContentAsText(), 80));
  558.     }
  559.     
  560.     /**
  561.      *    Simulates the closing and reopening of the browser.
  562.      *    Temporary cookies will be discarded and timed
  563.      *    cookies will be expired if later than the
  564.      *    specified time.
  565.      *    @param string/integer $date Time when session restarted.
  566.      *                                 If ommitted then all persistent
  567.      *                                 cookies are kept. Time is either
  568.      *                                 Cookie format string or timestamp.
  569.      *    @access public
  570.      */
  571.     function restart($date = false) {
  572.         if ($date === false) {
  573.             $date = time();
  574.         }
  575.         $this->_browser->restart($date);
  576.     }
  577.     
  578.     /**
  579.      *    Moves cookie expiry times back into the past.
  580.      *    Useful for testing timeouts and expiries.
  581.      *    @param integer $interval    Amount to age in seconds.
  582.      *    @access public
  583.      */
  584.     function ageCookies($interval) {
  585.         $this->_browser->ageCookies($interval);
  586.     }
  587.     
  588.     /**
  589.      *    Disables frames support. Frames will not be fetched
  590.      *    and the frameset page will be used instead.
  591.      *    @access public
  592.      */
  593.     function ignoreFrames() {
  594.         $this->_browser->ignoreFrames();
  595.     }
  596.     
  597.     /**
  598.      *    Switches off cookie sending and recieving.
  599.      *    @access public
  600.      */
  601.     function ignoreCookies() {
  602.         $this->_browser->ignoreCookies();
  603.     }
  604.     
  605.     /**
  606.      *    Skips errors for the next request only. You might
  607.      *    want to confirm that a page is unreachable for
  608.      *    example.
  609.      *    @access public
  610.      */
  611.     function ignoreErrors() {
  612.         $this->_ignore_errors = true;
  613.     }
  614.     
  615.     /**
  616.      *    Issues a fail if there is a transport error anywhere
  617.      *    in the current frameset. Only one such error is
  618.      *    reported.
  619.      *    @param string/boolean $result   HTML or failure.
  620.      *    @return string/boolean $result  Passes through result.
  621.      *    @access private
  622.      */
  623.     function _failOnError($result) {
  624.         if (! $this->_ignore_errors) {
  625.             if ($error = $this->_browser->getTransportError()) {
  626.                 $this->fail($error);
  627.             }
  628.         }
  629.         $this->_ignore_errors = false;
  630.         return $result;
  631.     }
  632.  
  633.     /**
  634.      *    Adds a header to every fetch.
  635.      *    @param string $header       Header line to add to every
  636.      *                                 request until cleared.
  637.      *    @access public
  638.      */
  639.     function addHeader($header) {
  640.         $this->_browser->addHeader($header);
  641.     }
  642.     
  643.     /**
  644.      *    Sets the maximum number of redirects before
  645.      *    the web page is loaded regardless.
  646.      *    @param integer $max        Maximum hops.
  647.      *    @access public
  648.      */
  649.     function setMaximumRedirects($max) {
  650.         if (! $this->_browser) {
  651.             trigger_error(
  652.                     'Can only set maximum redirects in a test method, setUp() or tearDown()');
  653.         }
  654.         $this->_browser->setMaximumRedirects($max);
  655.     }
  656.     
  657.     /**
  658.      *    Sets the socket timeout for opening a connection and
  659.      *    receiving at least one byte of information.
  660.      *    @param integer $timeout      Maximum time in seconds.
  661.      *    @access public
  662.      */
  663.     function setConnectionTimeout($timeout) {
  664.         $this->_browser->setConnectionTimeout($timeout);
  665.     }
  666.     
  667.     /**
  668.      *    Sets proxy to use on all requests for when
  669.      *    testing from behind a firewall. Set URL
  670.      *    to false to disable.
  671.      *    @param string $proxy        Proxy URL.
  672.      *    @param string $username     Proxy username for authentication.
  673.      *    @param string $password     Proxy password for authentication.
  674.      *    @access public
  675.      */
  676.     function useProxy($proxy, $username = false, $password = false) {
  677.         $this->_browser->useProxy($proxy, $username, $password);
  678.     }
  679.     
  680.     /**
  681.      *    Fetches a page into the page buffer. If
  682.      *    there is no base for the URL then the
  683.      *    current base URL is used. After the fetch
  684.      *    the base URL reflects the new location.
  685.      *    @param string $url          URL to fetch.
  686.      *    @param hash $parameters     Optional additional GET data.
  687.      *    @return boolean/string      Raw page on success.
  688.      *    @access public
  689.      */
  690.     function get($url, $parameters = false) {
  691.         return $this->_failOnError($this->_browser->get($url, $parameters));
  692.     }
  693.     
  694.     /**
  695.      *    Fetches a page by POST into the page buffer.
  696.      *    If there is no base for the URL then the
  697.      *    current base URL is used. After the fetch
  698.      *    the base URL reflects the new location.
  699.      *    @param string $url          URL to fetch.
  700.      *    @param hash $parameters     Optional additional GET data.
  701.      *    @return boolean/string      Raw page on success.
  702.      *    @access public
  703.      */
  704.     function post($url, $parameters = false) {
  705.         return $this->_failOnError($this->_browser->post($url, $parameters));
  706.     }
  707.     
  708.     /**
  709.      *    Does a HTTP HEAD fetch, fetching only the page
  710.      *    headers. The current base URL is unchanged by this.
  711.      *    @param string $url          URL to fetch.
  712.      *    @param hash $parameters     Optional additional GET data.
  713.      *    @return boolean             True on success.
  714.      *    @access public
  715.      */
  716.     function head($url, $parameters = false) {
  717.         return $this->_failOnError($this->_browser->head($url, $parameters));
  718.     }
  719.     
  720.     /**
  721.      *    Equivalent to hitting the retry button on the
  722.      *    browser. Will attempt to repeat the page fetch.
  723.      *    @return boolean     True if fetch succeeded.
  724.      *    @access public
  725.      */
  726.     function retry() {
  727.         return $this->_failOnError($this->_browser->retry());
  728.     }
  729.     
  730.     /**
  731.      *    Equivalent to hitting the back button on the
  732.      *    browser.
  733.      *    @return boolean     True if history entry and
  734.      *                         fetch succeeded.
  735.      *    @access public
  736.      */
  737.     function back() {
  738.         return $this->_failOnError($this->_browser->back());
  739.     }
  740.     
  741.     /**
  742.      *    Equivalent to hitting the forward button on the
  743.      *    browser.
  744.      *    @return boolean     True if history entry and
  745.      *                         fetch succeeded.
  746.      *    @access public
  747.      */
  748.     function forward() {
  749.         return $this->_failOnError($this->_browser->forward());
  750.     }
  751.     
  752.     /**
  753.      *    Retries a request after setting the authentication
  754.      *    for the current realm.
  755.      *    @param string $username    Username for realm.
  756.      *    @param string $password    Password for realm.
  757.      *    @return boolean/string     HTML on successful fetch. Note
  758.      *                                that authentication may still have
  759.      *                                failed.
  760.      *    @access public
  761.      */
  762.     function authenticate($username, $password) {
  763.         return $this->_failOnError(
  764.                 $this->_browser->authenticate($username, $password));
  765.     }
  766.     
  767.     /**
  768.      *    Gets the cookie value for the current browser context.
  769.      *    @param string $name          Name of cookie.
  770.      *    @return string               Value of cookie or false if unset.
  771.      *    @access public
  772.      */
  773.     function getCookie($name) {
  774.         return $this->_browser->getCurrentCookieValue($name);
  775.     }
  776.     
  777.     /**
  778.      *    Sets a cookie in the current browser.
  779.      *    @param string $name          Name of cookie.
  780.      *    @param string $value         Cookie value.
  781.      *    @param string $host          Host upon which the cookie is valid.
  782.      *    @param string $path          Cookie path if not host wide.
  783.      *    @param string $expiry        Expiry date.
  784.      *    @access public
  785.      */
  786.     function setCookie($name, $value, $host = false, $path = '/', $expiry = false) {
  787.         $this->_browser->setCookie($name, $value, $host, $path, $expiry);
  788.     }
  789.     
  790.     /**
  791.      *    Accessor for current frame focus. Will be
  792.      *    false if no frame has focus.
  793.      *    @return integer/string/boolean    Label if any, otherwise
  794.      *                                       the position in the frameset
  795.      *                                       or false if none.
  796.      *    @access public
  797.      */
  798.     function getFrameFocus() {
  799.         return $this->_browser->getFrameFocus();
  800.     }
  801.     
  802.     /**
  803.      *    Sets the focus by index. The integer index starts from 1.
  804.      *    @param integer $choice    Chosen frame.
  805.      *    @return boolean           True if frame exists.
  806.      *    @access public
  807.      */
  808.     function setFrameFocusByIndex($choice) {
  809.         return $this->_browser->setFrameFocusByIndex($choice);
  810.     }
  811.     
  812.     /**
  813.      *    Sets the focus by name.
  814.      *    @param string $name    Chosen frame.
  815.      *    @return boolean        True if frame exists.
  816.      *    @access public
  817.      */
  818.     function setFrameFocus($name) {
  819.         return $this->_browser->setFrameFocus($name);
  820.     }
  821.     
  822.     /**
  823.      *    Clears the frame focus. All frames will be searched
  824.      *    for content.
  825.      *    @access public
  826.      */
  827.     function clearFrameFocus() {
  828.         return $this->_browser->clearFrameFocus();
  829.     }
  830.     
  831.     /**
  832.      *    Clicks a visible text item. Will first try buttons,
  833.      *    then links and then images.
  834.      *    @param string $label        Visible text or alt text.
  835.      *    @return string/boolean      Raw page or false.
  836.      *    @access public
  837.      */
  838.     function click($label) {
  839.         return $this->_failOnError($this->_browser->click($label));
  840.     }
  841.     
  842.     /**
  843.      *    Checks for a click target.
  844.      *    @param string $label        Visible text or alt text.
  845.      *    @return boolean             True if click target.
  846.      *    @access public
  847.      */    
  848.     function assertClickable($label, $message = '%s') {
  849.         return $this->assertTrue(
  850.                 $this->_browser->isClickable($label),
  851.                 sprintf($message, "Click target [$label] should exist"));
  852.     }
  853.     
  854.     /**
  855.      *    Clicks the submit button by label. The owning
  856.      *    form will be submitted by this.
  857.      *    @param string $label    Button label. An unlabeled
  858.      *                             button can be triggered by 'Submit'.
  859.      *    @param hash $additional Additional form values.
  860.      *    @return boolean/string  Page on success, else false.
  861.      *    @access public
  862.      */
  863.     function clickSubmit($label = 'Submit', $additional = false) {
  864.         return $this->_failOnError(
  865.                 $this->_browser->clickSubmit($label, $additional));
  866.     }
  867.     
  868.     /**
  869.      *    Clicks the submit button by name attribute. The owning
  870.      *    form will be submitted by this.
  871.      *    @param string $name     Name attribute of button.
  872.      *    @param hash $additional Additional form values.
  873.      *    @return boolean/string  Page on success.
  874.      *    @access public
  875.      */
  876.     function clickSubmitByName($name, $additional = false) {
  877.         return $this->_failOnError(
  878.                 $this->_browser->clickSubmitByName($name, $additional));
  879.     }
  880.     
  881.     /**
  882.      *    Clicks the submit button by ID attribute. The owning
  883.      *    form will be submitted by this.
  884.      *    @param string $id       ID attribute of button.
  885.      *    @param hash $additional Additional form values.
  886.      *    @return boolean/string  Page on success.
  887.      *    @access public
  888.      */
  889.     function clickSubmitById($id, $additional = false) {
  890.         return $this->_failOnError(
  891.                 $this->_browser->clickSubmitById($id, $additional));
  892.     }
  893.     
  894.     /**
  895.      *    Checks for a valid button label.
  896.      *    @param string $label        Visible text.
  897.      *    @return boolean             True if click target.
  898.      *    @access public
  899.      */    
  900.     function assertSubmit($label, $message = '%s') {
  901.         return $this->assertTrue(
  902.                 $this->_browser->isSubmit($label),
  903.                 sprintf($message, "Submit button [$label] should exist"));
  904.     }
  905.     
  906.     /**
  907.      *    Clicks the submit image by some kind of label. Usually
  908.      *    the alt tag or the nearest equivalent. The owning
  909.      *    form will be submitted by this. Clicking outside of
  910.      *    the boundary of the coordinates will result in
  911.      *    a failure.
  912.      *    @param string $label    Alt attribute of button.
  913.      *    @param integer $x       X-coordinate of imaginary click.
  914.      *    @param integer $y       Y-coordinate of imaginary click.
  915.      *    @param hash $additional Additional form values.
  916.      *    @return boolean/string  Page on success.
  917.      *    @access public
  918.      */
  919.     function clickImage($label, $x = 1, $y = 1, $additional = false) {
  920.         return $this->_failOnError(
  921.                 $this->_browser->clickImage($label, $x, $y, $additional));
  922.     }
  923.     
  924.     /**
  925.      *    Clicks the submit image by the name. Usually
  926.      *    the alt tag or the nearest equivalent. The owning
  927.      *    form will be submitted by this. Clicking outside of
  928.      *    the boundary of the coordinates will result in
  929.      *    a failure.
  930.      *    @param string $name     Name attribute of button.
  931.      *    @param integer $x       X-coordinate of imaginary click.
  932.      *    @param integer $y       Y-coordinate of imaginary click.
  933.      *    @param hash $additional Additional form values.
  934.      *    @return boolean/string  Page on success.
  935.      *    @access public
  936.      */
  937.     function clickImageByName($name, $x = 1, $y = 1, $additional = false) {
  938.         return $this->_failOnError(
  939.                 $this->_browser->clickImageByName($name, $x, $y, $additional));
  940.     }
  941.     
  942.     /**
  943.      *    Clicks the submit image by ID attribute. The owning
  944.      *    form will be submitted by this. Clicking outside of
  945.      *    the boundary of the coordinates will result in
  946.      *    a failure.
  947.      *    @param integer/string $id   ID attribute of button.
  948.      *    @param integer $x           X-coordinate of imaginary click.
  949.      *    @param integer $y           Y-coordinate of imaginary click.
  950.      *    @param hash $additional     Additional form values.
  951.      *    @return boolean/string      Page on success.
  952.      *    @access public
  953.      */
  954.     function clickImageById($id, $x = 1, $y = 1, $additional = false) {
  955.         return $this->_failOnError(
  956.                 $this->_browser->clickImageById($id, $x, $y, $additional));
  957.     }
  958.     
  959.     /**
  960.      *    Checks for a valid image with atht alt text or title.
  961.      *    @param string $label        Visible text.
  962.      *    @return boolean             True if click target.
  963.      *    @access public
  964.      */    
  965.     function assertImage($label, $message = '%s') {
  966.         return $this->assertTrue(
  967.                 $this->_browser->isImage($label),
  968.                 sprintf($message, "Image with text [$label] should exist"));
  969.     }
  970.     
  971.     /**
  972.      *    Submits a form by the ID.
  973.      *    @param string $id       Form ID. No button information
  974.      *                             is submitted this way.
  975.      *    @return boolean/string  Page on success.
  976.      *    @access public
  977.      */
  978.     function submitFormById($id) {
  979.         return $this->_failOnError($this->_browser->submitFormById($id));
  980.     }
  981.     
  982.     /**
  983.      *    Follows a link by name. Will click the first link
  984.      *    found with this link text by default, or a later
  985.      *    one if an index is given. Match is case insensitive
  986.      *    with normalised space.
  987.      *    @param string $label     Text between the anchor tags.
  988.      *    @param integer $index    Link position counting from zero.
  989.      *    @return boolean/string   Page on success.
  990.      *    @access public
  991.      */
  992.     function clickLink($label, $index = 0) {
  993.         return $this->_failOnError($this->_browser->clickLink($label, $index));
  994.     }
  995.     
  996.     /**
  997.      *    Follows a link by id attribute.
  998.      *    @param string $id        ID attribute value.
  999.      *    @return boolean/string   Page on success.
  1000.      *    @access public
  1001.      */
  1002.     function clickLinkById($id) {
  1003.         return $this->_failOnError($this->_browser->clickLinkById($id));
  1004.     }
  1005.     
  1006.     /**
  1007.      *    Tests for the presence of a link label. Match is
  1008.      *    case insensitive with normalised space.
  1009.      *    @param string $label     Text between the anchor tags.
  1010.      *    @param mixed $expected   Expected URL or expectation object.
  1011.      *    @param string $message   Message to display. Default
  1012.      *                              can be embedded with %s.
  1013.      *    @return boolean          True if link present.
  1014.      *    @access public
  1015.      */
  1016.     function assertLink($label, $expected = true, $message = '%s') {
  1017.         $url = $this->_browser->getLink($label);
  1018.         if ($expected === true || ($expected !== true && $url === false)) {
  1019.             return $this->assertTrue($url !== false, sprintf($message, "Link [$label] should exist"));
  1020.         }
  1021.         if (! SimpleExpectation::isExpectation($expected)) {
  1022.             $expected = new IdenticalExpectation($expected);
  1023.         }
  1024.         return $this->assert($expected, $url->asString(), sprintf($message, "Link [$label] should match"));
  1025.     }
  1026.  
  1027.     /**
  1028.      *    Tests for the non-presence of a link label. Match is
  1029.      *    case insensitive with normalised space.
  1030.      *    @param string/integer $label    Text between the anchor tags
  1031.      *                                     or ID attribute.
  1032.      *    @param string $message          Message to display. Default
  1033.      *                                     can be embedded with %s.
  1034.      *    @return boolean                 True if link missing.
  1035.      *    @access public
  1036.      */
  1037.     function assertNoLink($label, $message = '%s') {
  1038.         return $this->assertTrue(
  1039.                 $this->_browser->getLink($label) === false,
  1040.                 sprintf($message, "Link [$label] should not exist"));
  1041.     }
  1042.     
  1043.     /**
  1044.      *    Tests for the presence of a link id attribute.
  1045.      *    @param string $id        Id attribute value.
  1046.      *    @param mixed $expected   Expected URL or expectation object.
  1047.      *    @param string $message   Message to display. Default
  1048.      *                              can be embedded with %s.
  1049.      *    @return boolean          True if link present.
  1050.      *    @access public
  1051.      */
  1052.     function assertLinkById($id, $expected = true, $message = '%s') {
  1053.         $url = $this->_browser->getLinkById($id);
  1054.         if ($expected === true) {
  1055.             return $this->assertTrue($url !== false, sprintf($message, "Link ID [$id] should exist"));
  1056.         }
  1057.         if (! SimpleExpectation::isExpectation($expected)) {
  1058.             $expected = new IdenticalExpectation($expected);
  1059.         }
  1060.         return $this->assert($expected, $url->asString(), sprintf($message, "Link ID [$id] should match"));
  1061.     }
  1062.  
  1063.     /**
  1064.      *    Tests for the non-presence of a link label. Match is
  1065.      *    case insensitive with normalised space.
  1066.      *    @param string $id        Id attribute value.
  1067.      *    @param string $message   Message to display. Default
  1068.      *                              can be embedded with %s.
  1069.      *    @return boolean          True if link missing.
  1070.      *    @access public
  1071.      */
  1072.     function assertNoLinkById($id, $message = '%s') {
  1073.         return $this->assertTrue(
  1074.                 $this->_browser->getLinkById($id) === false,
  1075.                 sprintf($message, "Link ID [$id] should not exist"));
  1076.     }
  1077.     
  1078.     /**
  1079.      *    Sets all form fields with that label, or name if there
  1080.      *    is no label attached.
  1081.      *    @param string $name    Name of field in forms.
  1082.      *    @param string $value   New value of field.
  1083.      *    @return boolean        True if field exists, otherwise false.
  1084.      *    @access public
  1085.      */
  1086.     function setField($label, $value, $position=false) {
  1087.         return $this->_browser->setField($label, $value, $position);
  1088.     }
  1089.     
  1090.     /**
  1091.      *    Sets all form fields with that name.
  1092.      *    @param string $name    Name of field in forms.
  1093.      *    @param string $value   New value of field.
  1094.      *    @return boolean        True if field exists, otherwise false.
  1095.      *    @access public
  1096.      */
  1097.     function setFieldByName($name, $value, $position=false) {
  1098.         return $this->_browser->setFieldByName($name, $value, $position);
  1099.     }
  1100.         
  1101.     /**
  1102.      *    Sets all form fields with that id.
  1103.      *    @param string/integer $id   Id of field in forms.
  1104.      *    @param string $value        New value of field.
  1105.      *    @return boolean             True if field exists, otherwise false.
  1106.      *    @access public
  1107.      */
  1108.     function setFieldById($id, $value) {
  1109.         return $this->_browser->setFieldById($id, $value);
  1110.     }
  1111.     
  1112.     /**
  1113.      *    Confirms that the form element is currently set
  1114.      *    to the expected value. A missing form will always
  1115.      *    fail. If no value is given then only the existence
  1116.      *    of the field is checked.
  1117.      *    @param string $name       Name of field in forms.
  1118.      *    @param mixed $expected    Expected string/array value or
  1119.      *                               false for unset fields.
  1120.      *    @param string $message    Message to display. Default
  1121.      *                               can be embedded with %s.
  1122.      *    @return boolean           True if pass.
  1123.      *    @access public
  1124.      */
  1125.     function assertField($label, $expected = true, $message = '%s') {
  1126.         $value = $this->_browser->getField($label);
  1127.         return $this->_assertFieldValue($label, $value, $expected, $message);
  1128.     }
  1129.     
  1130.     /**
  1131.      *    Confirms that the form element is currently set
  1132.      *    to the expected value. A missing form element will always
  1133.      *    fail. If no value is given then only the existence
  1134.      *    of the field is checked.
  1135.      *    @param string $name       Name of field in forms.
  1136.      *    @param mixed $expected    Expected string/array value or
  1137.      *                               false for unset fields.
  1138.      *    @param string $message    Message to display. Default
  1139.      *                               can be embedded with %s.
  1140.      *    @return boolean           True if pass.
  1141.      *    @access public
  1142.      */
  1143.     function assertFieldByName($name, $expected = true, $message = '%s') {
  1144.         $value = $this->_browser->getFieldByName($name);
  1145.         return $this->_assertFieldValue($name, $value, $expected, $message);
  1146.     }
  1147.         
  1148.     /**
  1149.      *    Confirms that the form element is currently set
  1150.      *    to the expected value. A missing form will always
  1151.      *    fail. If no ID is given then only the existence
  1152.      *    of the field is checked.
  1153.      *    @param string/integer $id  Name of field in forms.
  1154.      *    @param mixed $expected     Expected string/array value or
  1155.      *                                false for unset fields.
  1156.      *    @param string $message     Message to display. Default
  1157.      *                                can be embedded with %s.
  1158.      *    @return boolean            True if pass.
  1159.      *    @access public
  1160.      */
  1161.     function assertFieldById($id, $expected = true, $message = '%s') {
  1162.         $value = $this->_browser->getFieldById($id);
  1163.         return $this->_assertFieldValue($id, $value, $expected, $message);
  1164.     }
  1165.     
  1166.     /**
  1167.      *    Tests the field value against the expectation.
  1168.      *    @param string $identifier      Name, ID or label.
  1169.      *    @param mixed $value            Current field value.
  1170.      *    @param mixed $expected         Expected value to match.
  1171.      *    @param string $message         Failure message.
  1172.      *    @return boolean                True if pass
  1173.      *    @access protected
  1174.      */
  1175.     function _assertFieldValue($identifier, $value, $expected, $message) {
  1176.         if ($expected === true) {
  1177.             return $this->assertTrue(
  1178.                     isset($value),
  1179.                     sprintf($message, "Field [$identifier] should exist"));
  1180.         }
  1181.         if (! SimpleExpectation::isExpectation($expected)) {
  1182.             $identifier = str_replace('%', '%%', $identifier);
  1183.             $expected = new FieldExpectation(
  1184.                     $expected,
  1185.                     "Field [$identifier] should match with [%s]");
  1186.         }
  1187.         return $this->assert($expected, $value, $message);
  1188.     }
  1189.     
  1190.     /**
  1191.      *    Checks the response code against a list
  1192.      *    of possible values.
  1193.      *    @param array $responses    Possible responses for a pass.
  1194.      *    @param string $message     Message to display. Default
  1195.      *                                can be embedded with %s.
  1196.      *    @return boolean            True if pass.
  1197.      *    @access public
  1198.      */
  1199.     function assertResponse($responses, $message = '%s') {
  1200.         $responses = (is_array($responses) ? $responses : array($responses));
  1201.         $code = $this->_browser->getResponseCode();
  1202.         $message = sprintf($message, "Expecting response in [" .
  1203.                 implode(", ", $responses) . "] got [$code]");
  1204.         return $this->assertTrue(in_array($code, $responses), $message);
  1205.     }
  1206.     
  1207.     /**
  1208.      *    Checks the mime type against a list
  1209.      *    of possible values.
  1210.      *    @param array $types      Possible mime types for a pass.
  1211.      *    @param string $message   Message to display.
  1212.      *    @return boolean          True if pass.
  1213.      *    @access public
  1214.      */
  1215.     function assertMime($types, $message = '%s') {
  1216.         $types = (is_array($types) ? $types : array($types));
  1217.         $type = $this->_browser->getMimeType();
  1218.         $message = sprintf($message, "Expecting mime type in [" .
  1219.                 implode(", ", $types) . "] got [$type]");
  1220.         return $this->assertTrue(in_array($type, $types), $message);
  1221.     }
  1222.     
  1223.     /**
  1224.      *    Attempt to match the authentication type within
  1225.      *    the security realm we are currently matching.
  1226.      *    @param string $authentication   Usually basic.
  1227.      *    @param string $message          Message to display.
  1228.      *    @return boolean                 True if pass.
  1229.      *    @access public
  1230.      */
  1231.     function assertAuthentication($authentication = false, $message = '%s') {
  1232.         if (! $authentication) {
  1233.             $message = sprintf($message, "Expected any authentication type, got [" .
  1234.                     $this->_browser->getAuthentication() . "]");
  1235.             return $this->assertTrue(
  1236.                     $this->_browser->getAuthentication(),
  1237.                     $message);
  1238.         } else {
  1239.             $message = sprintf($message, "Expected authentication [$authentication] got [" .
  1240.                     $this->_browser->getAuthentication() . "]");
  1241.             return $this->assertTrue(
  1242.                     strtolower($this->_browser->getAuthentication()) == strtolower($authentication),
  1243.                     $message);
  1244.         }
  1245.     }
  1246.     
  1247.     /**
  1248.      *    Checks that no authentication is necessary to view
  1249.      *    the desired page.
  1250.      *    @param string $message     Message to display.
  1251.      *    @return boolean            True if pass.
  1252.      *    @access public
  1253.      */
  1254.     function assertNoAuthentication($message = '%s') {
  1255.         $message = sprintf($message, "Expected no authentication type, got [" .
  1256.                 $this->_browser->getAuthentication() . "]");
  1257.         return $this->assertFalse($this->_browser->getAuthentication(), $message);
  1258.     }
  1259.     
  1260.     /**
  1261.      *    Attempts to match the current security realm.
  1262.      *    @param string $realm     Name of security realm.
  1263.      *    @param string $message   Message to display.
  1264.      *    @return boolean          True if pass.
  1265.      *    @access public
  1266.      */
  1267.     function assertRealm($realm, $message = '%s') {
  1268.         if (! SimpleExpectation::isExpectation($realm)) {
  1269.             $realm = new EqualExpectation($realm);
  1270.         }
  1271.         return $this->assert(
  1272.                 $realm,
  1273.                 $this->_browser->getRealm(),
  1274.                 "Expected realm -> $message");
  1275.     }
  1276.     
  1277.     /**
  1278.      *    Checks each header line for the required value. If no
  1279.      *    value is given then only an existence check is made.
  1280.      *    @param string $header    Case insensitive header name.
  1281.      *    @param mixed $value      Case sensitive trimmed string to
  1282.      *                              match against. An expectation object
  1283.      *                              can be used for pattern matching.
  1284.      *    @return boolean          True if pass.
  1285.      *    @access public
  1286.      */
  1287.     function assertHeader($header, $value = false, $message = '%s') {
  1288.         return $this->assert(
  1289.                 new HttpHeaderExpectation($header, $value),
  1290.                 $this->_browser->getHeaders(),
  1291.                 $message);
  1292.     }
  1293.         
  1294.     /**
  1295.      *    @deprecated
  1296.      */
  1297.     function assertHeaderPattern($header, $pattern, $message = '%s') {
  1298.         return $this->assert(
  1299.                 new HttpHeaderExpectation($header, new PatternExpectation($pattern)),
  1300.                 $this->_browser->getHeaders(),
  1301.                 $message);
  1302.     }
  1303.  
  1304.     /**
  1305.      *    Confirms that the header type has not been received.
  1306.      *    Only the landing page is checked. If you want to check
  1307.      *    redirect pages, then you should limit redirects so
  1308.      *    as to capture the page you want.
  1309.      *    @param string $header    Case insensitive header name.
  1310.      *    @return boolean          True if pass.
  1311.      *    @access public
  1312.      */
  1313.     function assertNoHeader($header, $message = '%s') {
  1314.         return $this->assert(
  1315.                 new NoHttpHeaderExpectation($header),
  1316.                 $this->_browser->getHeaders(),
  1317.                 $message);
  1318.     }
  1319.         
  1320.     /**
  1321.      *    @deprecated
  1322.      */
  1323.     function assertNoUnwantedHeader($header, $message = '%s') {
  1324.         return $this->assertNoHeader($header, $message);
  1325.     }
  1326.     
  1327.     /**
  1328.      *    Tests the text between the title tags.
  1329.      *    @param string/SimpleExpectation $title    Expected title.
  1330.      *    @param string $message                    Message to display.
  1331.      *    @return boolean                           True if pass.
  1332.      *    @access public
  1333.      */
  1334.     function assertTitle($title = false, $message = '%s') {
  1335.         if (! SimpleExpectation::isExpectation($title)) {
  1336.             $title = new EqualExpectation($title);
  1337.         }
  1338.         return $this->assert($title, $this->_browser->getTitle(), $message);
  1339.     }
  1340.     
  1341.     /**
  1342.      *    Will trigger a pass if the text is found in the plain
  1343.      *    text form of the page.
  1344.      *    @param string $text       Text to look for.
  1345.      *    @param string $message    Message to display.
  1346.      *    @return boolean           True if pass.
  1347.      *    @access public
  1348.      */
  1349.     function assertText($text, $message = '%s') {
  1350.         return $this->assert(
  1351.                 new TextExpectation($text),
  1352.                 $this->_browser->getContentAsText(),
  1353.                 $message);
  1354.     }
  1355.     
  1356.     /**
  1357.      *    @deprecated
  1358.      */
  1359.     function assertWantedText($text, $message = '%s') {
  1360.         return $this->assertText($text, $message);
  1361.     }
  1362.     
  1363.     /**
  1364.      *    Will trigger a pass if the text is not found in the plain
  1365.      *    text form of the page.
  1366.      *    @param string $text       Text to look for.
  1367.      *    @param string $message    Message to display.
  1368.      *    @return boolean           True if pass.
  1369.      *    @access public
  1370.      */
  1371.     function assertNoText($text, $message = '%s') {
  1372.         return $this->assert(
  1373.                 new NoTextExpectation($text),
  1374.                 $this->_browser->getContentAsText(),
  1375.                 $message);
  1376.     }
  1377.     
  1378.     /**
  1379.      *    @deprecated
  1380.      */
  1381.     function assertNoUnwantedText($text, $message = '%s') {
  1382.         return $this->assertNoText($text, $message);
  1383.     }
  1384.     
  1385.     /**
  1386.      *    Will trigger a pass if the Perl regex pattern
  1387.      *    is found in the raw content.
  1388.      *    @param string $pattern    Perl regex to look for including
  1389.      *                               the regex delimiters.
  1390.      *    @param string $message    Message to display.
  1391.      *    @return boolean           True if pass.
  1392.      *    @access public
  1393.      */
  1394.     function assertPattern($pattern, $message = '%s') {
  1395.         return $this->assert(
  1396.                 new PatternExpectation($pattern),
  1397.                 $this->_browser->getContent(),
  1398.                 $message);
  1399.     }
  1400.     
  1401.     /**
  1402.      *    @deprecated
  1403.      */
  1404.     function assertWantedPattern($pattern, $message = '%s') {
  1405.         return $this->assertPattern($pattern, $message);
  1406.     }
  1407.     
  1408.     /**
  1409.      *    Will trigger a pass if the perl regex pattern
  1410.      *    is not present in raw content.
  1411.      *    @param string $pattern    Perl regex to look for including
  1412.      *                               the regex delimiters.
  1413.      *    @param string $message    Message to display.
  1414.      *    @return boolean           True if pass.
  1415.      *    @access public
  1416.      */
  1417.     function assertNoPattern($pattern, $message = '%s') {
  1418.         return $this->assert(
  1419.                 new NoPatternExpectation($pattern),
  1420.                 $this->_browser->getContent(),
  1421.                 $message);
  1422.     }
  1423.     
  1424.     /**
  1425.      *    @deprecated
  1426.      */
  1427.     function assertNoUnwantedPattern($pattern, $message = '%s') {
  1428.         return $this->assertNoPattern($pattern, $message);
  1429.     }
  1430.     
  1431.     /**
  1432.      *    Checks that a cookie is set for the current page
  1433.      *    and optionally checks the value.
  1434.      *    @param string $name        Name of cookie to test.
  1435.      *    @param string $expected    Expected value as a string or
  1436.      *                                false if any value will do.
  1437.      *    @param string $message     Message to display.
  1438.      *    @return boolean            True if pass.
  1439.      *    @access public
  1440.      */
  1441.     function assertCookie($name, $expected = false, $message = '%s') {
  1442.         $value = $this->getCookie($name);
  1443.         if (! $expected) {
  1444.             return $this->assertTrue(
  1445.                     $value,
  1446.                     sprintf($message, "Expecting cookie [$name]"));
  1447.         }
  1448.         if (! SimpleExpectation::isExpectation($expected)) {
  1449.             $expected = new EqualExpectation($expected);
  1450.         }
  1451.         return $this->assert($expected, $value, "Expecting cookie [$name] -> $message");
  1452.     }
  1453.     
  1454.     /**
  1455.      *    Checks that no cookie is present or that it has
  1456.      *    been successfully cleared.
  1457.      *    @param string $name        Name of cookie to test.
  1458.      *    @param string $message     Message to display.
  1459.      *    @return boolean            True if pass.
  1460.      *    @access public
  1461.      */
  1462.     function assertNoCookie($name, $message = '%s') {
  1463.         return $this->assertTrue(
  1464.                 $this->getCookie($name) === false,
  1465.                 sprintf($message, "Not expecting cookie [$name]"));
  1466.     }
  1467.  
  1468.     /**
  1469.      *    Called from within the test methods to register
  1470.      *    passes and failures.
  1471.      *    @param boolean $result    Pass on true.
  1472.      *    @param string $message    Message to display describing
  1473.      *                               the test state.
  1474.      *    @return boolean           True on pass
  1475.      *    @access public
  1476.      */
  1477.     function assertTrue($result, $message = false) {
  1478.         return $this->assert(new TrueExpectation(), $result, $message);
  1479.     }
  1480.  
  1481.     /**
  1482.      *    Will be true on false and vice versa. False
  1483.      *    is the PHP definition of false, so that null,
  1484.      *    empty strings, zero and an empty array all count
  1485.      *    as false.
  1486.      *    @param boolean $result    Pass on false.
  1487.      *    @param string $message    Message to display.
  1488.      *    @return boolean           True on pass
  1489.      *    @access public
  1490.      */
  1491.     function assertFalse($result, $message = '%s') {
  1492.         return $this->assert(new FalseExpectation(), $result, $message);
  1493.     }
  1494.     
  1495.     /**
  1496.      *    Will trigger a pass if the two parameters have
  1497.      *    the same value only. Otherwise a fail. This
  1498.      *    is for testing hand extracted text, etc.
  1499.      *    @param mixed $first          Value to compare.
  1500.      *    @param mixed $second         Value to compare.
  1501.      *    @param string $message       Message to display.
  1502.      *    @return boolean              True on pass
  1503.      *    @access public
  1504.      */
  1505.     function assertEqual($first, $second, $message = '%s') {
  1506.         return $this->assert(
  1507.                 new EqualExpectation($first),
  1508.                 $second,
  1509.                 $message);
  1510.     }
  1511.     
  1512.     /**
  1513.      *    Will trigger a pass if the two parameters have
  1514.      *    a different value. Otherwise a fail. This
  1515.      *    is for testing hand extracted text, etc.
  1516.      *    @param mixed $first           Value to compare.
  1517.      *    @param mixed $second          Value to compare.
  1518.      *    @param string $message        Message to display.
  1519.      *    @return boolean               True on pass
  1520.      *    @access public
  1521.      */
  1522.     function assertNotEqual($first, $second, $message = '%s') {
  1523.         return $this->assert(
  1524.                 new NotEqualExpectation($first),
  1525.                 $second,
  1526.                 $message);
  1527.     }
  1528.  
  1529.     /**
  1530.      *    Uses a stack trace to find the line of an assertion.
  1531.      *    @return string           Line number of first assert*
  1532.      *                              method embedded in format string.
  1533.      *    @access public
  1534.      */
  1535.     function getAssertionLine() {
  1536.         $trace = new SimpleStackTrace(array('assert', 'click', 'pass', 'fail'));
  1537.         return $trace->traceMethod();
  1538.     }
  1539. }
  1540. ?>

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