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 1933 2009-07-31 17:01:57Z 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. /**
  19.  *    Test for an HTML widget value match.
  20.  *    @package SimpleTest
  21.  *    @subpackage WebTester
  22.  */
  23. class FieldExpectation extends SimpleExpectation {
  24.     private $value;
  25.  
  26.     /**
  27.      *    Sets the field value to compare against.
  28.      *    @param mixed $value     Test value to match. Can be an
  29.      *                             expectation for say pattern matching.
  30.      *    @param string $message  Optiona message override. Can use %s as
  31.      *                             a placeholder for the original message.
  32.      *    @access public
  33.      */
  34.     function __construct($value, $message = '%s') {
  35.         parent::__construct($message);
  36.         if (is_array($value)) {
  37.             sort($value);
  38.         }
  39.         $this->value = $value;
  40.     }
  41.  
  42.     /**
  43.      *    Tests the expectation. True if it matches
  44.      *    a string value or an array value in any order.
  45.      *    @param mixed $compare        Comparison value. False for
  46.      *                                  an unset field.
  47.      *    @return boolean              True if correct.
  48.      *    @access public
  49.      */
  50.     function test($compare) {
  51.         if ($this->value === false) {
  52.             return ($compare === false);
  53.         }
  54.         if ($this->isSingle($this->value)) {
  55.             return $this->testSingle($compare);
  56.         }
  57.         if (is_array($this->value)) {
  58.             return $this->testMultiple($compare);
  59.         }
  60.         return false;
  61.     }
  62.  
  63.     /**
  64.      *    Tests for valid field comparisons with a single option.
  65.      *    @param mixed $value       Value to type check.
  66.      *    @return boolean           True if integer, string or float.
  67.      *    @access private
  68.      */
  69.     protected function isSingle($value) {
  70.         return is_string($value) || is_integer($value) || is_float($value);
  71.     }
  72.  
  73.     /**
  74.      *    String comparison for simple field with a single option.
  75.      *    @param mixed $compare    String to test against.
  76.      *    @returns boolean         True if matching.
  77.      *    @access private
  78.      */
  79.     protected function testSingle($compare) {
  80.         if (is_array($compare) && count($compare) == 1) {
  81.             $compare = $compare[0];
  82.         }
  83.         if (! $this->isSingle($compare)) {
  84.             return false;
  85.         }
  86.         return ($this->value == $compare);
  87.     }
  88.  
  89.     /**
  90.      *    List comparison for multivalue field.
  91.      *    @param mixed $compare    List in any order to test against.
  92.      *    @returns boolean         True if matching.
  93.      *    @access private
  94.      */
  95.     protected function testMultiple($compare) {
  96.         if (is_string($compare)) {
  97.             $compare = array($compare);
  98.         }
  99.         if (! is_array($compare)) {
  100.             return false;
  101.         }
  102.         sort($compare);
  103.         return ($this->value === $compare);
  104.     }
  105.  
  106.     /**
  107.      *    Returns a human readable test message.
  108.      *    @param mixed $compare      Comparison value.
  109.      *    @return string             Description of success
  110.      *                                or failure.
  111.      *    @access public
  112.      */
  113.     function testMessage($compare) {
  114.         $dumper = $this->getDumper();
  115.         if (is_array($compare)) {
  116.             sort($compare);
  117.         }
  118.         if ($this->test($compare)) {
  119.             return "Field expectation [" . $dumper->describeValue($this->value) . "]";
  120.         } else {
  121.             return "Field expectation [" . $dumper->describeValue($this->value) .
  122.                     "] fails with [" .
  123.                     $dumper->describeValue($compare) . "] " .
  124.                     $dumper->describeDifference($this->value, $compare);
  125.         }
  126.     }
  127. }
  128.  
  129. /**
  130.  *    Test for a specific HTTP header within a header block.
  131.  *    @package SimpleTest
  132.  *    @subpackage WebTester
  133.  */
  134. class HttpHeaderExpectation extends SimpleExpectation {
  135.     private $expected_header;
  136.     private $expected_value;
  137.  
  138.     /**
  139.      *    Sets the field and value to compare against.
  140.      *    @param string $header   Case insenstive trimmed header name.
  141.      *    @param mixed $value     Optional value to compare. If not
  142.      *                             given then any value will match. If
  143.      *                             an expectation object then that will
  144.      *                             be used instead.
  145.      *    @param string $message  Optiona message override. Can use %s as
  146.      *                             a placeholder for the original message.
  147.      */
  148.     function __construct($header, $value = false, $message = '%s') {
  149.         parent::__construct($message);
  150.         $this->expected_header = $this->normaliseHeader($header);
  151.         $this->expected_value = $value;
  152.     }
  153.  
  154.     /**
  155.      *    Accessor for aggregated object.
  156.      *    @return mixed        Expectation set in constructor.
  157.      *    @access protected
  158.      */
  159.     protected function getExpectation() {
  160.         return $this->expected_value;
  161.     }
  162.  
  163.     /**
  164.      *    Removes whitespace at ends and case variations.
  165.      *    @param string $header    Name of header.
  166.      *    @param string            Trimmed and lowecased header
  167.      *                              name.
  168.      *    @access private
  169.      */
  170.     protected function normaliseHeader($header) {
  171.         return strtolower(trim($header));
  172.     }
  173.  
  174.     /**
  175.      *    Tests the expectation. True if it matches
  176.      *    a string value or an array value in any order.
  177.      *    @param mixed $compare   Raw header block to search.
  178.      *    @return boolean         True if header present.
  179.      *    @access public
  180.      */
  181.     function test($compare) {
  182.         return is_string($this->findHeader($compare));
  183.     }
  184.  
  185.     /**
  186.      *    Searches the incoming result. Will extract the matching
  187.      *    line as text.
  188.      *    @param mixed $compare   Raw header block to search.
  189.      *    @return string          Matching header line.
  190.      *    @access protected
  191.      */
  192.     protected function findHeader($compare) {
  193.         $lines = explode("\r\n", $compare);
  194.         foreach ($lines as $line) {
  195.             if ($this->testHeaderLine($line)) {
  196.                 return $line;
  197.             }
  198.         }
  199.         return false;
  200.     }
  201.  
  202.     /**
  203.      *    Compares a single header line against the expectation.
  204.      *    @param string $line      A single line to compare.
  205.      *    @return boolean          True if matched.
  206.      *    @access private
  207.      */
  208.     protected function testHeaderLine($line) {
  209.         if (count($parsed = explode(':', $line, 2)) < 2) {
  210.             return false;
  211.         }
  212.         list($header, $value) = $parsed;
  213.         if ($this->normaliseHeader($header) != $this->expected_header) {
  214.             return false;
  215.         }
  216.         return $this->testHeaderValue($value, $this->expected_value);
  217.     }
  218.  
  219.     /**
  220.      *    Tests the value part of the header.
  221.      *    @param string $value        Value to test.
  222.      *    @param mixed $expected      Value to test against.
  223.      *    @return boolean             True if matched.
  224.      *    @access protected
  225.      */
  226.     protected function testHeaderValue($value, $expected) {
  227.         if ($expected === false) {
  228.             return true;
  229.         }
  230.         if (SimpleExpectation::isExpectation($expected)) {
  231.             return $expected->test(trim($value));
  232.         }
  233.         return (trim($value) == trim($expected));
  234.     }
  235.  
  236.     /**
  237.      *    Returns a human readable test message.
  238.      *    @param mixed $compare      Raw header block to search.
  239.      *    @return string             Description of success
  240.      *                                or failure.
  241.      *    @access public
  242.      */
  243.     function testMessage($compare) {
  244.         if (SimpleExpectation::isExpectation($this->expected_value)) {
  245.             $message = $this->expected_value->overlayMessage($compare, $this->getDumper());
  246.         } else {
  247.             $message = $this->expected_header .
  248.                     ($this->expected_value ? ': ' . $this->expected_value : '');
  249.         }
  250.         if (is_string($line = $this->findHeader($compare))) {
  251.             return "Searching for header [$message] found [$line]";
  252.         } else {
  253.             return "Failed to find header [$message]";
  254.         }
  255.     }
  256. }
  257.  
  258. /**
  259.  *    Test for a specific HTTP header within a header block that
  260.  *    should not be found.
  261.  *    @package SimpleTest
  262.  *    @subpackage WebTester
  263.  */
  264. class NoHttpHeaderExpectation extends HttpHeaderExpectation {
  265.     private $expected_header;
  266.     private $expected_value;
  267.  
  268.     /**
  269.      *    Sets the field and value to compare against.
  270.      *    @param string $unwanted   Case insenstive trimmed header name.
  271.      *    @param string $message    Optiona message override. Can use %s as
  272.      *                               a placeholder for the original message.
  273.      */
  274.     function __construct($unwanted, $message = '%s') {
  275.         parent::__construct($unwanted, false, $message);
  276.     }
  277.  
  278.     /**
  279.      *    Tests that the unwanted header is not found.
  280.      *    @param mixed $compare   Raw header block to search.
  281.      *    @return boolean         True if header present.
  282.      *    @access public
  283.      */
  284.     function test($compare) {
  285.         return ($this->findHeader($compare) === false);
  286.     }
  287.  
  288.     /**
  289.      *    Returns a human readable test message.
  290.      *    @param mixed $compare      Raw header block to search.
  291.      *    @return string             Description of success
  292.      *                                or failure.
  293.      *    @access public
  294.      */
  295.     function testMessage($compare) {
  296.         $expectation = $this->getExpectation();
  297.         if (is_string($line = $this->findHeader($compare))) {
  298.             return "Found unwanted header [$expectation] with [$line]";
  299.         } else {
  300.             return "Did not find unwanted header [$expectation]";
  301.         }
  302.     }
  303. }
  304.  
  305. /**
  306.  *    Test for a text substring.
  307.  *    @package SimpleTest
  308.  *    @subpackage UnitTester
  309.  */
  310. class TextExpectation extends SimpleExpectation {
  311.     private $substring;
  312.  
  313.     /**
  314.      *    Sets the value to compare against.
  315.      *    @param string $substring  Text to search for.
  316.      *    @param string $message    Customised message on failure.
  317.      *    @access public
  318.      */
  319.     function __construct($substring, $message = '%s') {
  320.         parent::__construct($message);
  321.         $this->substring = $substring;
  322.     }
  323.  
  324.     /**
  325.      *    Accessor for the substring.
  326.      *    @return string       Text to match.
  327.      *    @access protected
  328.      */
  329.     protected function getSubstring() {
  330.         return $this->substring;
  331.     }
  332.  
  333.     /**
  334.      *    Tests the expectation. True if the text contains the
  335.      *    substring.
  336.      *    @param string $compare        Comparison value.
  337.      *    @return boolean               True if correct.
  338.      *    @access public
  339.      */
  340.     function test($compare) {
  341.         return (strpos($compare, $this->substring) !== false);
  342.     }
  343.  
  344.     /**
  345.      *    Returns a human readable test message.
  346.      *    @param mixed $compare      Comparison value.
  347.      *    @return string             Description of success
  348.      *                                or failure.
  349.      *    @access public
  350.      */
  351.     function testMessage($compare) {
  352.         if ($this->test($compare)) {
  353.             return $this->describeTextMatch($this->getSubstring(), $compare);
  354.         } else {
  355.             $dumper = $this->getDumper();
  356.             return "Text [" . $this->getSubstring() .
  357.                     "] not detected in [" .
  358.                     $dumper->describeValue($compare) . "]";
  359.         }
  360.     }
  361.  
  362.     /**
  363.      *    Describes a pattern match including the string
  364.      *    found and it's position.
  365.      *    @param string $substring      Text to search for.
  366.      *    @param string $subject        Subject to search.
  367.      *    @access protected
  368.      */
  369.     protected function describeTextMatch($substring, $subject) {
  370.         $position = strpos($subject, $substring);
  371.         $dumper = $this->getDumper();
  372.         return "Text [$substring] detected at character [$position] in [" .
  373.                 $dumper->describeValue($subject) . "] in region [" .
  374.                 $dumper->clipString($subject, 100, $position) . "]";
  375.     }
  376. }
  377.  
  378. /**
  379.  *    Fail if a substring is detected within the
  380.  *    comparison text.
  381.  *    @package SimpleTest
  382.  *    @subpackage UnitTester
  383.  */
  384. class NoTextExpectation extends TextExpectation {
  385.  
  386.     /**
  387.      *    Sets the reject pattern
  388.      *    @param string $substring  Text to search for.
  389.      *    @param string $message    Customised message on failure.
  390.      *    @access public
  391.      */
  392.     function __construct($substring, $message = '%s') {
  393.         parent::__construct($substring, $message);
  394.     }
  395.  
  396.     /**
  397.      *    Tests the expectation. False if the substring appears
  398.      *    in the text.
  399.      *    @param string $compare        Comparison value.
  400.      *    @return boolean               True if correct.
  401.      *    @access public
  402.      */
  403.     function test($compare) {
  404.         return ! parent::test($compare);
  405.     }
  406.  
  407.     /**
  408.      *    Returns a human readable test message.
  409.      *    @param string $compare      Comparison value.
  410.      *    @return string              Description of success
  411.      *                                 or failure.
  412.      *    @access public
  413.      */
  414.     function testMessage($compare) {
  415.         if ($this->test($compare)) {
  416.             $dumper = $this->getDumper();
  417.             return "Text [" . $this->getSubstring() .
  418.                     "] not detected in [" .
  419.                     $dumper->describeValue($compare) . "]";
  420.         } else {
  421.             return $this->describeTextMatch($this->getSubstring(), $compare);
  422.         }
  423.     }
  424. }
  425.  
  426. /**
  427.  *    Test case for testing of web pages. Allows
  428.  *    fetching of pages, parsing of HTML and
  429.  *    submitting forms.
  430.  *    @package SimpleTest
  431.  *    @subpackage WebTester
  432.  */
  433. class WebTestCase extends SimpleTestCase {
  434.     private $browser;
  435.     private $ignore_errors = false;
  436.  
  437.     /**
  438.      *    Creates an empty test case. Should be subclassed
  439.      *    with test methods for a functional test case.
  440.      *    @param string $label     Name of test case. Will use
  441.      *                              the class name if none specified.
  442.      *    @access public
  443.      */
  444.     function __construct($label = false) {
  445.         parent::__construct($label);
  446.     }
  447.  
  448.     /**
  449.      *    Announces the start of the test.
  450.      *    @param string $method    Test method just started.
  451.      *    @access public
  452.      */
  453.     function before($method) {
  454.         parent::before($method);
  455.         $this->setBrowser($this->createBrowser());
  456.     }
  457.  
  458.     /**
  459.      *    Announces the end of the test. Includes private clean up.
  460.      *    @param string $method    Test method just finished.
  461.      *    @access public
  462.      */
  463.     function after($method) {
  464.         $this->unsetBrowser();
  465.         parent::after($method);
  466.     }
  467.  
  468.     /**
  469.      *    Gets a current browser reference for setting
  470.      *    special expectations or for detailed
  471.      *    examination of page fetches.
  472.      *    @return SimpleBrowser     Current test browser object.
  473.      *    @access public
  474.      */
  475.     function getBrowser() {
  476.         return $this->browser;
  477.     }
  478.  
  479.     /**
  480.      *    Gets a current browser reference for setting
  481.      *    special expectations or for detailed
  482.      *    examination of page fetches.
  483.      *    @param SimpleBrowser $browser    New test browser object.
  484.      *    @access public
  485.      */
  486.     function setBrowser($browser) {
  487.         return $this->browser = $browser;
  488.     }
  489.  
  490.     /**
  491.      *    Sets the HTML parser to use within this browser.
  492.      *    @param object         The parser, one of SimplePHPPageBuilder or
  493.      *                           SimpleTidyPageBuilder.
  494.      */
  495.     function setParser($parser) {
  496.         $this->browser->setParser($parser);
  497.     }
  498.  
  499.     /**
  500.      *    Clears the current browser reference to help the
  501.      *    PHP garbage collector.
  502.      *    @access public
  503.      */
  504.     function unsetBrowser() {
  505.         unset($this->browser);
  506.     }
  507.  
  508.     /**
  509.      *    Creates a new default web browser object.
  510.      *    Will be cleared at the end of the test method.
  511.      *    @return TestBrowser           New browser.
  512.      *    @access public
  513.      */
  514.     function createBrowser() {
  515.         return new SimpleBrowser();
  516.     }
  517.  
  518.     /**
  519.      *    Gets the last response error.
  520.      *    @return string    Last low level HTTP error.
  521.      *    @access public
  522.      */
  523.     function getTransportError() {
  524.         return $this->browser->getTransportError();
  525.     }
  526.  
  527.     /**
  528.      *    Accessor for the currently selected URL.
  529.      *    @return string        Current location or false if
  530.      *                           no page yet fetched.
  531.      *    @access public
  532.      */
  533.     function getUrl() {
  534.         return $this->browser->getUrl();
  535.     }
  536.  
  537.     /**
  538.      *    Dumps the current request for debugging.
  539.      *    @access public
  540.      */
  541.     function showRequest() {
  542.         $this->dump($this->browser->getRequest());
  543.     }
  544.  
  545.     /**
  546.      *    Dumps the current HTTP headers for debugging.
  547.      *    @access public
  548.      */
  549.     function showHeaders() {
  550.         $this->dump($this->browser->getHeaders());
  551.     }
  552.  
  553.     /**
  554.      *    Dumps the current HTML source for debugging.
  555.      *    @access public
  556.      */
  557.     function showSource() {
  558.         $this->dump($this->browser->getContent());
  559.     }
  560.  
  561.     /**
  562.      *    Dumps the visible text only for debugging.
  563.      *    @access public
  564.      */
  565.     function showText() {
  566.         $this->dump(wordwrap($this->browser->getContentAsText(), 80));
  567.     }
  568.  
  569.     /**
  570.      *    Simulates the closing and reopening of the browser.
  571.      *    Temporary cookies will be discarded and timed
  572.      *    cookies will be expired if later than the
  573.      *    specified time.
  574.      *    @param string/integer $date Time when session restarted.
  575.      *                                 If ommitted then all persistent
  576.      *                                 cookies are kept. Time is either
  577.      *                                 Cookie format string or timestamp.
  578.      *    @access public
  579.      */
  580.     function restart($date = false) {
  581.         if ($date === false) {
  582.             $date = time();
  583.         }
  584.         $this->browser->restart($date);
  585.     }
  586.  
  587.     /**
  588.      *    Moves cookie expiry times back into the past.
  589.      *    Useful for testing timeouts and expiries.
  590.      *    @param integer $interval    Amount to age in seconds.
  591.      *    @access public
  592.      */
  593.     function ageCookies($interval) {
  594.         $this->browser->ageCookies($interval);
  595.     }
  596.  
  597.     /**
  598.      *    Disables frames support. Frames will not be fetched
  599.      *    and the frameset page will be used instead.
  600.      *    @access public
  601.      */
  602.     function ignoreFrames() {
  603.         $this->browser->ignoreFrames();
  604.     }
  605.  
  606.     /**
  607.      *    Switches off cookie sending and recieving.
  608.      *    @access public
  609.      */
  610.     function ignoreCookies() {
  611.         $this->browser->ignoreCookies();
  612.     }
  613.  
  614.     /**
  615.      *    Skips errors for the next request only. You might
  616.      *    want to confirm that a page is unreachable for
  617.      *    example.
  618.      *    @access public
  619.      */
  620.     function ignoreErrors() {
  621.         $this->ignore_errors = true;
  622.     }
  623.  
  624.     /**
  625.      *    Issues a fail if there is a transport error anywhere
  626.      *    in the current frameset. Only one such error is
  627.      *    reported.
  628.      *    @param string/boolean $result   HTML or failure.
  629.      *    @return string/boolean $result  Passes through result.
  630.      *    @access private
  631.      */
  632.     protected function failOnError($result) {
  633.         if (! $this->ignore_errors) {
  634.             if ($error = $this->browser->getTransportError()) {
  635.                 $this->fail($error);
  636.             }
  637.         }
  638.         $this->ignore_errors = false;
  639.         return $result;
  640.     }
  641.  
  642.     /**
  643.      *    Adds a header to every fetch.
  644.      *    @param string $header       Header line to add to every
  645.      *                                 request until cleared.
  646.      *    @access public
  647.      */
  648.     function addHeader($header) {
  649.         $this->browser->addHeader($header);
  650.     }
  651.  
  652.     /**
  653.      *    Sets the maximum number of redirects before
  654.      *    the web page is loaded regardless.
  655.      *    @param integer $max        Maximum hops.
  656.      *    @access public
  657.      */
  658.     function setMaximumRedirects($max) {
  659.         if (! $this->browser) {
  660.             trigger_error(
  661.                     'Can only set maximum redirects in a test method, setUp() or tearDown()');
  662.         }
  663.         $this->browser->setMaximumRedirects($max);
  664.     }
  665.  
  666.     /**
  667.      *    Sets the socket timeout for opening a connection and
  668.      *    receiving at least one byte of information.
  669.      *    @param integer $timeout      Maximum time in seconds.
  670.      *    @access public
  671.      */
  672.     function setConnectionTimeout($timeout) {
  673.         $this->browser->setConnectionTimeout($timeout);
  674.     }
  675.  
  676.     /**
  677.      *    Sets proxy to use on all requests for when
  678.      *    testing from behind a firewall. Set URL
  679.      *    to false to disable.
  680.      *    @param string $proxy        Proxy URL.
  681.      *    @param string $username     Proxy username for authentication.
  682.      *    @param string $password     Proxy password for authentication.
  683.      *    @access public
  684.      */
  685.     function useProxy($proxy, $username = false, $password = false) {
  686.         $this->browser->useProxy($proxy, $username, $password);
  687.     }
  688.  
  689.     /**
  690.      *    Fetches a page into the page buffer. If
  691.      *    there is no base for the URL then the
  692.      *    current base URL is used. After the fetch
  693.      *    the base URL reflects the new location.
  694.      *    @param string $url          URL to fetch.
  695.      *    @param hash $parameters     Optional additional GET data.
  696.      *    @return boolean/string      Raw page on success.
  697.      *    @access public
  698.      */
  699.     function get($url, $parameters = false) {
  700.         return $this->failOnError($this->browser->get($url, $parameters));
  701.     }
  702.  
  703.     /**
  704.      *    Fetches a page by POST into the page buffer.
  705.      *    If there is no base for the URL then the
  706.      *    current base URL is used. After the fetch
  707.      *    the base URL reflects the new location.
  708.      *    @param string $url          URL to fetch.
  709.      *    @param hash $parameters     Optional additional GET data.
  710.      *    @return boolean/string      Raw page on success.
  711.      *    @access public
  712.      */
  713.     function post($url, $parameters = false) {
  714.         return $this->failOnError($this->browser->post($url, $parameters));
  715.     }
  716.  
  717.     /**
  718.      *    Does a HTTP HEAD fetch, fetching only the page
  719.      *    headers. The current base URL is unchanged by this.
  720.      *    @param string $url          URL to fetch.
  721.      *    @param hash $parameters     Optional additional GET data.
  722.      *    @return boolean             True on success.
  723.      *    @access public
  724.      */
  725.     function head($url, $parameters = false) {
  726.         return $this->failOnError($this->browser->head($url, $parameters));
  727.     }
  728.  
  729.     /**
  730.      *    Equivalent to hitting the retry button on the
  731.      *    browser. Will attempt to repeat the page fetch.
  732.      *    @return boolean     True if fetch succeeded.
  733.      *    @access public
  734.      */
  735.     function retry() {
  736.         return $this->failOnError($this->browser->retry());
  737.     }
  738.  
  739.     /**
  740.      *    Equivalent to hitting the back button on the
  741.      *    browser.
  742.      *    @return boolean     True if history entry and
  743.      *                         fetch succeeded.
  744.      *    @access public
  745.      */
  746.     function back() {
  747.         return $this->failOnError($this->browser->back());
  748.     }
  749.  
  750.     /**
  751.      *    Equivalent to hitting the forward button on the
  752.      *    browser.
  753.      *    @return boolean     True if history entry and
  754.      *                         fetch succeeded.
  755.      *    @access public
  756.      */
  757.     function forward() {
  758.         return $this->failOnError($this->browser->forward());
  759.     }
  760.  
  761.     /**
  762.      *    Retries a request after setting the authentication
  763.      *    for the current realm.
  764.      *    @param string $username    Username for realm.
  765.      *    @param string $password    Password for realm.
  766.      *    @return boolean/string     HTML on successful fetch. Note
  767.      *                                that authentication may still have
  768.      *                                failed.
  769.      *    @access public
  770.      */
  771.     function authenticate($username, $password) {
  772.         return $this->failOnError(
  773.                 $this->browser->authenticate($username, $password));
  774.     }
  775.  
  776.     /**
  777.      *    Gets the cookie value for the current browser context.
  778.      *    @param string $name          Name of cookie.
  779.      *    @return string               Value of cookie or false if unset.
  780.      *    @access public
  781.      */
  782.     function getCookie($name) {
  783.         return $this->browser->getCurrentCookieValue($name);
  784.     }
  785.  
  786.     /**
  787.      *    Sets a cookie in the current browser.
  788.      *    @param string $name          Name of cookie.
  789.      *    @param string $value         Cookie value.
  790.      *    @param string $host          Host upon which the cookie is valid.
  791.      *    @param string $path          Cookie path if not host wide.
  792.      *    @param string $expiry        Expiry date.
  793.      *    @access public
  794.      */
  795.     function setCookie($name, $value, $host = false, $path = '/', $expiry = false) {
  796.         $this->browser->setCookie($name, $value, $host, $path, $expiry);
  797.     }
  798.  
  799.     /**
  800.      *    Accessor for current frame focus. Will be
  801.      *    false if no frame has focus.
  802.      *    @return integer/string/boolean    Label if any, otherwise
  803.      *                                       the position in the frameset
  804.      *                                       or false if none.
  805.      *    @access public
  806.      */
  807.     function getFrameFocus() {
  808.         return $this->browser->getFrameFocus();
  809.     }
  810.  
  811.     /**
  812.      *    Sets the focus by index. The integer index starts from 1.
  813.      *    @param integer $choice    Chosen frame.
  814.      *    @return boolean           True if frame exists.
  815.      *    @access public
  816.      */
  817.     function setFrameFocusByIndex($choice) {
  818.         return $this->browser->setFrameFocusByIndex($choice);
  819.     }
  820.  
  821.     /**
  822.      *    Sets the focus by name.
  823.      *    @param string $name    Chosen frame.
  824.      *    @return boolean        True if frame exists.
  825.      *    @access public
  826.      */
  827.     function setFrameFocus($name) {
  828.         return $this->browser->setFrameFocus($name);
  829.     }
  830.  
  831.     /**
  832.      *    Clears the frame focus. All frames will be searched
  833.      *    for content.
  834.      *    @access public
  835.      */
  836.     function clearFrameFocus() {
  837.         return $this->browser->clearFrameFocus();
  838.     }
  839.  
  840.     /**
  841.      *    Clicks a visible text item. Will first try buttons,
  842.      *    then links and then images.
  843.      *    @param string $label        Visible text or alt text.
  844.      *    @return string/boolean      Raw page or false.
  845.      *    @access public
  846.      */
  847.     function click($label) {
  848.         return $this->failOnError($this->browser->click($label));
  849.     }
  850.  
  851.     /**
  852.      *    Checks for a click target.
  853.      *    @param string $label        Visible text or alt text.
  854.      *    @return boolean             True if click target.
  855.      *    @access public
  856.      */
  857.     function assertClickable($label, $message = '%s') {
  858.         return $this->assertTrue(
  859.                 $this->browser->isClickable($label),
  860.                 sprintf($message, "Click target [$label] should exist"));
  861.     }
  862.  
  863.     /**
  864.      *    Clicks the submit button by label. The owning
  865.      *    form will be submitted by this.
  866.      *    @param string $label    Button label. An unlabeled
  867.      *                             button can be triggered by 'Submit'.
  868.      *    @param hash $additional Additional form values.
  869.      *    @return boolean/string  Page on success, else false.
  870.      *    @access public
  871.      */
  872.     function clickSubmit($label = 'Submit', $additional = false) {
  873.         return $this->failOnError(
  874.                 $this->browser->clickSubmit($label, $additional));
  875.     }
  876.  
  877.     /**
  878.      *    Clicks the submit button by name attribute. The owning
  879.      *    form will be submitted by this.
  880.      *    @param string $name     Name attribute of button.
  881.      *    @param hash $additional Additional form values.
  882.      *    @return boolean/string  Page on success.
  883.      *    @access public
  884.      */
  885.     function clickSubmitByName($name, $additional = false) {
  886.         return $this->failOnError(
  887.                 $this->browser->clickSubmitByName($name, $additional));
  888.     }
  889.  
  890.     /**
  891.      *    Clicks the submit button by ID attribute. The owning
  892.      *    form will be submitted by this.
  893.      *    @param string $id       ID attribute of button.
  894.      *    @param hash $additional Additional form values.
  895.      *    @return boolean/string  Page on success.
  896.      *    @access public
  897.      */
  898.     function clickSubmitById($id, $additional = false) {
  899.         return $this->failOnError(
  900.                 $this->browser->clickSubmitById($id, $additional));
  901.     }
  902.  
  903.     /**
  904.      *    Checks for a valid button label.
  905.      *    @param string $label        Visible text.
  906.      *    @return boolean             True if click target.
  907.      *    @access public
  908.      */
  909.     function assertSubmit($label, $message = '%s') {
  910.         return $this->assertTrue(
  911.                 $this->browser->isSubmit($label),
  912.                 sprintf($message, "Submit button [$label] should exist"));
  913.     }
  914.  
  915.     /**
  916.      *    Clicks the submit image by some kind of label. Usually
  917.      *    the alt tag or the nearest equivalent. The owning
  918.      *    form will be submitted by this. Clicking outside of
  919.      *    the boundary of the coordinates will result in
  920.      *    a failure.
  921.      *    @param string $label    Alt attribute of button.
  922.      *    @param integer $x       X-coordinate of imaginary click.
  923.      *    @param integer $y       Y-coordinate of imaginary click.
  924.      *    @param hash $additional Additional form values.
  925.      *    @return boolean/string  Page on success.
  926.      *    @access public
  927.      */
  928.     function clickImage($label, $x = 1, $y = 1, $additional = false) {
  929.         return $this->failOnError(
  930.                 $this->browser->clickImage($label, $x, $y, $additional));
  931.     }
  932.  
  933.     /**
  934.      *    Clicks the submit image by the name. Usually
  935.      *    the alt tag or the nearest equivalent. The owning
  936.      *    form will be submitted by this. Clicking outside of
  937.      *    the boundary of the coordinates will result in
  938.      *    a failure.
  939.      *    @param string $name     Name attribute of button.
  940.      *    @param integer $x       X-coordinate of imaginary click.
  941.      *    @param integer $y       Y-coordinate of imaginary click.
  942.      *    @param hash $additional Additional form values.
  943.      *    @return boolean/string  Page on success.
  944.      *    @access public
  945.      */
  946.     function clickImageByName($name, $x = 1, $y = 1, $additional = false) {
  947.         return $this->failOnError(
  948.                 $this->browser->clickImageByName($name, $x, $y, $additional));
  949.     }
  950.  
  951.     /**
  952.      *    Clicks the submit image by ID attribute. The owning
  953.      *    form will be submitted by this. Clicking outside of
  954.      *    the boundary of the coordinates will result in
  955.      *    a failure.
  956.      *    @param integer/string $id   ID attribute of button.
  957.      *    @param integer $x           X-coordinate of imaginary click.
  958.      *    @param integer $y           Y-coordinate of imaginary click.
  959.      *    @param hash $additional     Additional form values.
  960.      *    @return boolean/string      Page on success.
  961.      *    @access public
  962.      */
  963.     function clickImageById($id, $x = 1, $y = 1, $additional = false) {
  964.         return $this->failOnError(
  965.                 $this->browser->clickImageById($id, $x, $y, $additional));
  966.     }
  967.  
  968.     /**
  969.      *    Checks for a valid image with atht alt text or title.
  970.      *    @param string $label        Visible text.
  971.      *    @return boolean             True if click target.
  972.      *    @access public
  973.      */
  974.     function assertImage($label, $message = '%s') {
  975.         return $this->assertTrue(
  976.                 $this->browser->isImage($label),
  977.                 sprintf($message, "Image with text [$label] should exist"));
  978.     }
  979.  
  980.     /**
  981.      *    Submits a form by the ID.
  982.      *    @param string $id       Form ID. No button information
  983.      *                             is submitted this way.
  984.      *    @return boolean/string  Page on success.
  985.      *    @access public
  986.      */
  987.     function submitFormById($id) {
  988.         return $this->failOnError($this->browser->submitFormById($id));
  989.     }
  990.  
  991.     /**
  992.      *    Follows a link by name. Will click the first link
  993.      *    found with this link text by default, or a later
  994.      *    one if an index is given. Match is case insensitive
  995.      *    with normalised space.
  996.      *    @param string $label     Text between the anchor tags.
  997.      *    @param integer $index    Link position counting from zero.
  998.      *    @return boolean/string   Page on success.
  999.      *    @access public
  1000.      */
  1001.     function clickLink($label, $index = 0) {
  1002.         return $this->failOnError($this->browser->clickLink($label, $index));
  1003.     }
  1004.  
  1005.     /**
  1006.      *    Follows a link by id attribute.
  1007.      *    @param string $id        ID attribute value.
  1008.      *    @return boolean/string   Page on success.
  1009.      *    @access public
  1010.      */
  1011.     function clickLinkById($id) {
  1012.         return $this->failOnError($this->browser->clickLinkById($id));
  1013.     }
  1014.  
  1015.     /**
  1016.      *    Tests for the presence of a link label. Match is
  1017.      *    case insensitive with normalised space.
  1018.      *    @param string $label     Text between the anchor tags.
  1019.      *    @param mixed $expected   Expected URL or expectation object.
  1020.      *    @param string $message   Message to display. Default
  1021.      *                              can be embedded with %s.
  1022.      *    @return boolean          True if link present.
  1023.      *    @access public
  1024.      */
  1025.     function assertLink($label, $expected = true, $message = '%s') {
  1026.         $url = $this->browser->getLink($label);
  1027.         if ($expected === true || ($expected !== true && $url === false)) {
  1028.             return $this->assertTrue($url !== false, sprintf($message, "Link [$label] should exist"));
  1029.         }
  1030.         if (! SimpleExpectation::isExpectation($expected)) {
  1031.             $expected = new IdenticalExpectation($expected);
  1032.         }
  1033.         return $this->assert($expected, $url->asString(), sprintf($message, "Link [$label] should match"));
  1034.     }
  1035.  
  1036.     /**
  1037.      *    Tests for the non-presence of a link label. Match is
  1038.      *    case insensitive with normalised space.
  1039.      *    @param string/integer $label    Text between the anchor tags
  1040.      *                                     or ID attribute.
  1041.      *    @param string $message          Message to display. Default
  1042.      *                                     can be embedded with %s.
  1043.      *    @return boolean                 True if link missing.
  1044.      *    @access public
  1045.      */
  1046.     function assertNoLink($label, $message = '%s') {
  1047.         return $this->assertTrue(
  1048.                 $this->browser->getLink($label) === false,
  1049.                 sprintf($message, "Link [$label] should not exist"));
  1050.     }
  1051.  
  1052.     /**
  1053.      *    Tests for the presence of a link id attribute.
  1054.      *    @param string $id        Id attribute value.
  1055.      *    @param mixed $expected   Expected URL or expectation object.
  1056.      *    @param string $message   Message to display. Default
  1057.      *                              can be embedded with %s.
  1058.      *    @return boolean          True if link present.
  1059.      *    @access public
  1060.      */
  1061.     function assertLinkById($id, $expected = true, $message = '%s') {
  1062.         $url = $this->browser->getLinkById($id);
  1063.         if ($expected === true) {
  1064.             return $this->assertTrue($url !== false, sprintf($message, "Link ID [$id] should exist"));
  1065.         }
  1066.         if (! SimpleExpectation::isExpectation($expected)) {
  1067.             $expected = new IdenticalExpectation($expected);
  1068.         }
  1069.         return $this->assert($expected, $url->asString(), sprintf($message, "Link ID [$id] should match"));
  1070.     }
  1071.  
  1072.     /**
  1073.      *    Tests for the non-presence of a link label. Match is
  1074.      *    case insensitive with normalised space.
  1075.      *    @param string $id        Id attribute value.
  1076.      *    @param string $message   Message to display. Default
  1077.      *                              can be embedded with %s.
  1078.      *    @return boolean          True if link missing.
  1079.      *    @access public
  1080.      */
  1081.     function assertNoLinkById($id, $message = '%s') {
  1082.         return $this->assertTrue(
  1083.                 $this->browser->getLinkById($id) === false,
  1084.                 sprintf($message, "Link ID [$id] should not exist"));
  1085.     }
  1086.  
  1087.     /**
  1088.      *    Sets all form fields with that label, or name if there
  1089.      *    is no label attached.
  1090.      *    @param string $name    Name of field in forms.
  1091.      *    @param string $value   New value of field.
  1092.      *    @return boolean        True if field exists, otherwise false.
  1093.      *    @access public
  1094.      */
  1095.     function setField($label, $value, $position=false) {
  1096.         return $this->browser->setField($label, $value, $position);
  1097.     }
  1098.  
  1099.     /**
  1100.      *    Sets all form fields with that name.
  1101.      *    @param string $name    Name of field in forms.
  1102.      *    @param string $value   New value of field.
  1103.      *    @return boolean        True if field exists, otherwise false.
  1104.      *    @access public
  1105.      */
  1106.     function setFieldByName($name, $value, $position=false) {
  1107.         return $this->browser->setFieldByName($name, $value, $position);
  1108.     }
  1109.  
  1110.     /**
  1111.      *    Sets all form fields with that id.
  1112.      *    @param string/integer $id   Id of field in forms.
  1113.      *    @param string $value        New value of field.
  1114.      *    @return boolean             True if field exists, otherwise false.
  1115.      *    @access public
  1116.      */
  1117.     function setFieldById($id, $value) {
  1118.         return $this->browser->setFieldById($id, $value);
  1119.     }
  1120.  
  1121.     /**
  1122.      *    Confirms that the form element is currently set
  1123.      *    to the expected value. A missing form will always
  1124.      *    fail. If no value is given then only the existence
  1125.      *    of the field is checked.
  1126.      *    @param string $name       Name of field in forms.
  1127.      *    @param mixed $expected    Expected string/array value or
  1128.      *                               false for unset fields.
  1129.      *    @param string $message    Message to display. Default
  1130.      *                               can be embedded with %s.
  1131.      *    @return boolean           True if pass.
  1132.      *    @access public
  1133.      */
  1134.     function assertField($label, $expected = true, $message = '%s') {
  1135.         $value = $this->browser->getField($label);
  1136.         return $this->assertFieldValue($label, $value, $expected, $message);
  1137.     }
  1138.  
  1139.     /**
  1140.      *    Confirms that the form element is currently set
  1141.      *    to the expected value. A missing form element will always
  1142.      *    fail. If no value is given then only the existence
  1143.      *    of the field is checked.
  1144.      *    @param string $name       Name of field in forms.
  1145.      *    @param mixed $expected    Expected string/array value or
  1146.      *                               false for unset fields.
  1147.      *    @param string $message    Message to display. Default
  1148.      *                               can be embedded with %s.
  1149.      *    @return boolean           True if pass.
  1150.      *    @access public
  1151.      */
  1152.     function assertFieldByName($name, $expected = true, $message = '%s') {
  1153.         $value = $this->browser->getFieldByName($name);
  1154.         return $this->assertFieldValue($name, $value, $expected, $message);
  1155.     }
  1156.  
  1157.     /**
  1158.      *    Confirms that the form element is currently set
  1159.      *    to the expected value. A missing form will always
  1160.      *    fail. If no ID is given then only the existence
  1161.      *    of the field is checked.
  1162.      *    @param string/integer $id  Name of field in forms.
  1163.      *    @param mixed $expected     Expected string/array value or
  1164.      *                                false for unset fields.
  1165.      *    @param string $message     Message to display. Default
  1166.      *                                can be embedded with %s.
  1167.      *    @return boolean            True if pass.
  1168.      *    @access public
  1169.      */
  1170.     function assertFieldById($id, $expected = true, $message = '%s') {
  1171.         $value = $this->browser->getFieldById($id);
  1172.         return $this->assertFieldValue($id, $value, $expected, $message);
  1173.     }
  1174.  
  1175.     /**
  1176.      *    Tests the field value against the expectation.
  1177.      *    @param string $identifier      Name, ID or label.
  1178.      *    @param mixed $value            Current field value.
  1179.      *    @param mixed $expected         Expected value to match.
  1180.      *    @param string $message         Failure message.
  1181.      *    @return boolean                True if pass
  1182.      *    @access protected
  1183.      */
  1184.     protected function assertFieldValue($identifier, $value, $expected, $message) {
  1185.         if ($expected === true) {
  1186.             return $this->assertTrue(
  1187.                     isset($value),
  1188.                     sprintf($message, "Field [$identifier] should exist"));
  1189.         }
  1190.         if (! SimpleExpectation::isExpectation($expected)) {
  1191.             $identifier = str_replace('%', '%%', $identifier);
  1192.             $expected = new FieldExpectation(
  1193.                     $expected,
  1194.                     "Field [$identifier] should match with [%s]");
  1195.         }
  1196.         return $this->assert($expected, $value, $message);
  1197.     }
  1198.  
  1199.     /**
  1200.      *    Checks the response code against a list
  1201.      *    of possible values.
  1202.      *    @param array $responses    Possible responses for a pass.
  1203.      *    @param string $message     Message to display. Default
  1204.      *                                can be embedded with %s.
  1205.      *    @return boolean            True if pass.
  1206.      *    @access public
  1207.      */
  1208.     function assertResponse($responses, $message = '%s') {
  1209.         $responses = (is_array($responses) ? $responses : array($responses));
  1210.         $code = $this->browser->getResponseCode();
  1211.         $message = sprintf($message, "Expecting response in [" .
  1212.                 implode(", ", $responses) . "] got [$code]");
  1213.         return $this->assertTrue(in_array($code, $responses), $message);
  1214.     }
  1215.  
  1216.     /**
  1217.      *    Checks the mime type against a list
  1218.      *    of possible values.
  1219.      *    @param array $types      Possible mime types for a pass.
  1220.      *    @param string $message   Message to display.
  1221.      *    @return boolean          True if pass.
  1222.      *    @access public
  1223.      */
  1224.     function assertMime($types, $message = '%s') {
  1225.         $types = (is_array($types) ? $types : array($types));
  1226.         $type = $this->browser->getMimeType();
  1227.         $message = sprintf($message, "Expecting mime type in [" .
  1228.                 implode(", ", $types) . "] got [$type]");
  1229.         return $this->assertTrue(in_array($type, $types), $message);
  1230.     }
  1231.  
  1232.     /**
  1233.      *    Attempt to match the authentication type within
  1234.      *    the security realm we are currently matching.
  1235.      *    @param string $authentication   Usually basic.
  1236.      *    @param string $message          Message to display.
  1237.      *    @return boolean                 True if pass.
  1238.      *    @access public
  1239.      */
  1240.     function assertAuthentication($authentication = false, $message = '%s') {
  1241.         if (! $authentication) {
  1242.             $message = sprintf($message, "Expected any authentication type, got [" .
  1243.                     $this->browser->getAuthentication() . "]");
  1244.             return $this->assertTrue(
  1245.                     $this->browser->getAuthentication(),
  1246.                     $message);
  1247.         } else {
  1248.             $message = sprintf($message, "Expected authentication [$authentication] got [" .
  1249.                     $this->browser->getAuthentication() . "]");
  1250.             return $this->assertTrue(
  1251.                     strtolower($this->browser->getAuthentication()) == strtolower($authentication),
  1252.                     $message);
  1253.         }
  1254.     }
  1255.  
  1256.     /**
  1257.      *    Checks that no authentication is necessary to view
  1258.      *    the desired page.
  1259.      *    @param string $message     Message to display.
  1260.      *    @return boolean            True if pass.
  1261.      *    @access public
  1262.      */
  1263.     function assertNoAuthentication($message = '%s') {
  1264.         $message = sprintf($message, "Expected no authentication type, got [" .
  1265.                 $this->browser->getAuthentication() . "]");
  1266.         return $this->assertFalse($this->browser->getAuthentication(), $message);
  1267.     }
  1268.  
  1269.     /**
  1270.      *    Attempts to match the current security realm.
  1271.      *    @param string $realm     Name of security realm.
  1272.      *    @param string $message   Message to display.
  1273.      *    @return boolean          True if pass.
  1274.      *    @access public
  1275.      */
  1276.     function assertRealm($realm, $message = '%s') {
  1277.         if (! SimpleExpectation::isExpectation($realm)) {
  1278.             $realm = new EqualExpectation($realm);
  1279.         }
  1280.         return $this->assert(
  1281.                 $realm,
  1282.                 $this->browser->getRealm(),
  1283.                 "Expected realm -> $message");
  1284.     }
  1285.  
  1286.     /**
  1287.      *    Checks each header line for the required value. If no
  1288.      *    value is given then only an existence check is made.
  1289.      *    @param string $header    Case insensitive header name.
  1290.      *    @param mixed $value      Case sensitive trimmed string to
  1291.      *                              match against. An expectation object
  1292.      *                              can be used for pattern matching.
  1293.      *    @return boolean          True if pass.
  1294.      *    @access public
  1295.      */
  1296.     function assertHeader($header, $value = false, $message = '%s') {
  1297.         return $this->assert(
  1298.                 new HttpHeaderExpectation($header, $value),
  1299.                 $this->browser->getHeaders(),
  1300.                 $message);
  1301.     }
  1302.  
  1303.     /**
  1304.      *    Confirms that the header type has not been received.
  1305.      *    Only the landing page is checked. If you want to check
  1306.      *    redirect pages, then you should limit redirects so
  1307.      *    as to capture the page you want.
  1308.      *    @param string $header    Case insensitive header name.
  1309.      *    @return boolean          True if pass.
  1310.      *    @access public
  1311.      */
  1312.     function assertNoHeader($header, $message = '%s') {
  1313.         return $this->assert(
  1314.                 new NoHttpHeaderExpectation($header),
  1315.                 $this->browser->getHeaders(),
  1316.                 $message);
  1317.     }
  1318.  
  1319.     /**
  1320.      *    Tests the text between the title tags.
  1321.      *    @param string/SimpleExpectation $title    Expected title.
  1322.      *    @param string $message                    Message to display.
  1323.      *    @return boolean                           True if pass.
  1324.      *    @access public
  1325.      */
  1326.     function assertTitle($title = false, $message = '%s') {
  1327.         if (! SimpleExpectation::isExpectation($title)) {
  1328.             $title = new EqualExpectation($title);
  1329.         }
  1330.         return $this->assert($title, $this->browser->getTitle(), $message);
  1331.     }
  1332.  
  1333.     /**
  1334.      *    Will trigger a pass if the text is found in the plain
  1335.      *    text form of the page.
  1336.      *    @param string $text       Text to look for.
  1337.      *    @param string $message    Message to display.
  1338.      *    @return boolean           True if pass.
  1339.      *    @access public
  1340.      */
  1341.     function assertText($text, $message = '%s') {
  1342.         return $this->assert(
  1343.                 new TextExpectation($text),
  1344.                 $this->browser->getContentAsText(),
  1345.                 $message);
  1346.     }
  1347.  
  1348.     /**
  1349.      *    Will trigger a pass if the text is not found in the plain
  1350.      *    text form of the page.
  1351.      *    @param string $text       Text to look for.
  1352.      *    @param string $message    Message to display.
  1353.      *    @return boolean           True if pass.
  1354.      *    @access public
  1355.      */
  1356.     function assertNoText($text, $message = '%s') {
  1357.         return $this->assert(
  1358.                 new NoTextExpectation($text),
  1359.                 $this->browser->getContentAsText(),
  1360.                 $message);
  1361.     }
  1362.  
  1363.     /**
  1364.      *    Will trigger a pass if the Perl regex pattern
  1365.      *    is found in the raw content.
  1366.      *    @param string $pattern    Perl regex to look for including
  1367.      *                               the regex delimiters.
  1368.      *    @param string $message    Message to display.
  1369.      *    @return boolean           True if pass.
  1370.      *    @access public
  1371.      */
  1372.     function assertPattern($pattern, $message = '%s') {
  1373.         return $this->assert(
  1374.                 new PatternExpectation($pattern),
  1375.                 $this->browser->getContent(),
  1376.                 $message);
  1377.     }
  1378.  
  1379.     /**
  1380.      *    Will trigger a pass if the perl regex pattern
  1381.      *    is not present in raw content.
  1382.      *    @param string $pattern    Perl regex to look for including
  1383.      *                               the regex delimiters.
  1384.      *    @param string $message    Message to display.
  1385.      *    @return boolean           True if pass.
  1386.      *    @access public
  1387.      */
  1388.     function assertNoPattern($pattern, $message = '%s') {
  1389.         return $this->assert(
  1390.                 new NoPatternExpectation($pattern),
  1391.                 $this->browser->getContent(),
  1392.                 $message);
  1393.     }
  1394.  
  1395.     /**
  1396.      *    Checks that a cookie is set for the current page
  1397.      *    and optionally checks the value.
  1398.      *    @param string $name        Name of cookie to test.
  1399.      *    @param string $expected    Expected value as a string or
  1400.      *                                false if any value will do.
  1401.      *    @param string $message     Message to display.
  1402.      *    @return boolean            True if pass.
  1403.      *    @access public
  1404.      */
  1405.     function assertCookie($name, $expected = false, $message = '%s') {
  1406.         $value = $this->getCookie($name);
  1407.         if (! $expected) {
  1408.             return $this->assertTrue(
  1409.                     $value,
  1410.                     sprintf($message, "Expecting cookie [$name]"));
  1411.         }
  1412.         if (! SimpleExpectation::isExpectation($expected)) {
  1413.             $expected = new EqualExpectation($expected);
  1414.         }
  1415.         return $this->assert($expected, $value, "Expecting cookie [$name] -> $message");
  1416.     }
  1417.  
  1418.     /**
  1419.      *    Checks that no cookie is present or that it has
  1420.      *    been successfully cleared.
  1421.      *    @param string $name        Name of cookie to test.
  1422.      *    @param string $message     Message to display.
  1423.      *    @return boolean            True if pass.
  1424.      *    @access public
  1425.      */
  1426.     function assertNoCookie($name, $message = '%s') {
  1427.         return $this->assertTrue(
  1428.                 $this->getCookie($name) === null or $this->getCookie($name) === false,
  1429.                 sprintf($message, "Not expecting cookie [$name]"));
  1430.     }
  1431.  
  1432.     /**
  1433.      *    Called from within the test methods to register
  1434.      *    passes and failures.
  1435.      *    @param boolean $result    Pass on true.
  1436.      *    @param string $message    Message to display describing
  1437.      *                               the test state.
  1438.      *    @return boolean           True on pass
  1439.      *    @access public
  1440.      */
  1441.     function assertTrue($result, $message = false) {
  1442.         return $this->assert(new TrueExpectation(), $result, $message);
  1443.     }
  1444.  
  1445.     /**
  1446.      *    Will be true on false and vice versa. False
  1447.      *    is the PHP definition of false, so that null,
  1448.      *    empty strings, zero and an empty array all count
  1449.      *    as false.
  1450.      *    @param boolean $result    Pass on false.
  1451.      *    @param string $message    Message to display.
  1452.      *    @return boolean           True on pass
  1453.      *    @access public
  1454.      */
  1455.     function assertFalse($result, $message = '%s') {
  1456.         return $this->assert(new FalseExpectation(), $result, $message);
  1457.     }
  1458.  
  1459.     /**
  1460.      *    Will trigger a pass if the two parameters have
  1461.      *    the same value only. Otherwise a fail. This
  1462.      *    is for testing hand extracted text, etc.
  1463.      *    @param mixed $first          Value to compare.
  1464.      *    @param mixed $second         Value to compare.
  1465.      *    @param string $message       Message to display.
  1466.      *    @return boolean              True on pass
  1467.      *    @access public
  1468.      */
  1469.     function assertEqual($first, $second, $message = '%s') {
  1470.         return $this->assert(
  1471.                 new EqualExpectation($first),
  1472.                 $second,
  1473.                 $message);
  1474.     }
  1475.  
  1476.     /**
  1477.      *    Will trigger a pass if the two parameters have
  1478.      *    a different value. Otherwise a fail. This
  1479.      *    is for testing hand extracted text, etc.
  1480.      *    @param mixed $first           Value to compare.
  1481.      *    @param mixed $second          Value to compare.
  1482.      *    @param string $message        Message to display.
  1483.      *    @return boolean               True on pass
  1484.      *    @access public
  1485.      */
  1486.     function assertNotEqual($first, $second, $message = '%s') {
  1487.         return $this->assert(
  1488.                 new NotEqualExpectation($first),
  1489.                 $second,
  1490.                 $message);
  1491.     }
  1492.  
  1493.     /**
  1494.      *    Uses a stack trace to find the line of an assertion.
  1495.      *    @return string           Line number of first assert*
  1496.      *                              method embedded in format string.
  1497.      *    @access public
  1498.      */
  1499.     function getAssertionLine() {
  1500.         $trace = new SimpleStackTrace(array('assert', 'click', 'pass', 'fail'));
  1501.         return $trace->traceMethod();
  1502.     }
  1503. }
  1504. ?>

Documentation generated on Thu, 01 Oct 2009 20:56:22 -0500 by phpDocumentor 1.4.2