3 * Base include file for SimpleTest
5 * @subpackage WebTester
6 * @version $Id: page.php,v 1.99 2004/08/18 23:10:19 lastcraft Exp $
10 * include other SimpleTest class files
12 require_once(dirname(__FILE__
) . '/http.php');
13 require_once(dirname(__FILE__
) . '/parser.php');
14 require_once(dirname(__FILE__
) . '/tag.php');
15 require_once(dirname(__FILE__
) . '/form.php');
19 * SAX event handler. Maintains a list of
20 * open tags and dispatches them as they close.
22 * @subpackage WebTester
24 class SimplePageBuilder
extends SimpleSaxListener
{
29 * Sets the builder up empty.
32 function SimplePageBuilder() {
33 $this->SimpleSaxListener();
37 * Reads the raw content and send events
38 * into the page to be built.
39 * @param $response SimpleHttpResponse Fetched response.
40 * @return SimplePage Newly parsed page.
43 function parse($response) {
44 $this->_tags
= array();
45 $this->_page
= &$this->_createPage($response);
46 $parser = &$this->_createParser();
47 $parser->parse($response->getContent());
52 * Creates an empty page.
53 * @return SimplePage New unparsed page.
56 function &_createPage($response) {
57 return new SimplePage($response);
61 * Creates the parser used with the builder.
62 * @return SimpleSaxParser Parser to generate events for
66 function &_createParser() {
67 return new SimpleSaxParser($this);
71 * Start of element event. Opens a new tag.
72 * @param string $name Element name.
73 * @param hash $attributes Attributes without content
75 * @return boolean False on parse error.
78 function startElement($name, $attributes) {
79 $tag = &$this->_createTag($name, $attributes);
80 if ($name == 'form') {
81 $this->_page
->acceptFormStart($tag);
84 if ($name == 'frameset') {
85 $this->_page
->acceptFramesetStart($tag);
88 if ($name == 'frame') {
89 $this->_page
->acceptFrame($tag);
92 if ($tag->expectEndTag()) {
93 $this->_openTag($tag);
96 $this->_page
->acceptTag($tag);
101 * End of element event.
102 * @param string $name Element name.
103 * @return boolean False on parse error.
106 function endElement($name) {
107 if ($name == 'form') {
108 $this->_page
->acceptFormEnd();
111 if ($name == 'frameset') {
112 $this->_page
->acceptFramesetEnd();
115 if (isset($this->_tags
[$name]) && (count($this->_tags
[$name]) > 0)) {
116 $tag = array_pop($this->_tags
[$name]);
117 $this->_addContentTagToOpenTags($tag);
118 $this->_page
->acceptTag($tag);
125 * Unparsed, but relevant data. The data is added
127 * @param string $text May include unparsed tags.
128 * @return boolean False on parse error.
131 function addContent($text) {
132 foreach (array_keys($this->_tags
) as $name) {
133 for ($i = 0; $i < count($this->_tags
[$name]); $i++
) {
134 $this->_tags
[$name][$i]->addContent($text);
141 * Parsed relevant data. The parsed tag is added
143 * @param SimpleTag $tag May include unparsed tags.
146 function _addContentTagToOpenTags(&$tag) {
147 if (! in_array($tag->getTagName(), array('option'))) {
150 foreach (array_keys($this->_tags
) as $name) {
151 for ($i = 0; $i < count($this->_tags
[$name]); $i++
) {
152 $this->_tags
[$name][$i]->addTag($tag);
158 * Opens a tag for receiving content. Multiple tags
159 * will be receiving input at the same time.
160 * @param SimpleTag $tag New content tag.
163 function _openTag(&$tag) {
164 $name = $tag->getTagName();
165 if (! in_array($name, array_keys($this->_tags
))) {
166 $this->_tags
[$name] = array();
168 array_push($this->_tags
[$name], $tag);
172 * Factory for the tag objects. Creates the
173 * appropriate tag object for the incoming tag name.
174 * @param string $name HTML tag name.
175 * @param hash $attributes Element attributes.
176 * @return SimpleTag Tag object.
179 function &_createTag($name, $attributes) {
181 return new SimpleAnchorTag($attributes);
182 } elseif ($name == 'title') {
183 return new SimpleTitleTag($attributes);
184 } elseif ($name == 'input') {
185 return $this->_createInputTag($attributes);
186 } elseif ($name == 'button') {
187 return new SimpleButtonTag($attributes);
188 } elseif ($name == 'textarea') {
189 return new SimpleTextAreaTag($attributes);
190 } elseif ($name == 'select') {
191 return $this->_createSelectionTag($attributes);
192 } elseif ($name == 'option') {
193 return new SimpleOptionTag($attributes);
194 } elseif ($name == 'form') {
195 return new SimpleFormTag($attributes);
196 } elseif ($name == 'frame') {
197 return new SimpleFrameTag($attributes);
199 return new SimpleTag($name, $attributes);
203 * Factory for selection fields.
204 * @param hash $attributes Element attributes.
205 * @return SimpleTag Tag object.
208 function &_createSelectionTag($attributes) {
209 if (isset($attributes['multiple'])) {
210 return new MultipleSelectionTag($attributes);
212 return new SimpleSelectionTag($attributes);
216 * Factory for input tags.
217 * @param hash $attributes Element attributes.
218 * @return SimpleTag Tag object.
221 function &_createInputTag($attributes) {
222 if (! isset($attributes['type'])) {
223 return new SimpleTextTag($attributes);
225 if ($attributes['type'] == 'submit') {
226 return new SimpleSubmitTag($attributes);
227 } elseif ($attributes['type'] == 'image') {
228 return new SimpleImageSubmitTag($attributes);
229 } elseif ($attributes['type'] == 'checkbox') {
230 return new SimpleCheckboxTag($attributes);
231 } elseif ($attributes['type'] == 'radio') {
232 return new SimpleRadioButtonTag($attributes);
234 return new SimpleTextTag($attributes);
240 * A wrapper for a web page.
241 * @package SimpleTest
242 * @subpackage WebTester
248 var $_complete_forms;
251 var $_frameset_nesting_level;
252 var $_transport_error;
261 * Parses a page ready to access it's contents.
262 * @param SimpleHttpResponse $response Result of HTTP fetch.
265 function SimplePage($response = false
) {
266 $this->_links
= array();
267 $this->_title
= false
;
268 $this->_open_forms
= array();
269 $this->_complete_forms
= array();
270 $this->_frameset
= false
;
271 $this->_frames
= array();
272 $this->_frameset_nesting_level
= 0;
274 $this->_extractResponse($response);
276 $this->_noResponse();
281 * Extracts all of the response information.
282 * @param SimpleHttpResponse $response Response being parsed.
285 function _extractResponse($response) {
286 $this->_transport_error
= $response->getError();
287 $this->_raw
= $response->getContent();
288 $this->_sent
= $response->getSent();
289 $this->_headers
= $response->getHeaders();
290 $this->_method
= $response->getMethod();
291 $this->_url
= $response->getUrl();
292 $this->_request_data
= $response->getRequestData();
296 * Sets up a missng response.
299 function _noResponse() {
300 $this->_transport_error
= 'No page fetched yet';
302 $this->_sent
= false
;
303 $this->_headers
= false
;
304 $this->_method
= 'GET';
306 $this->_request_data
= false
;
310 * Original request as bytes sent down the wire.
311 * @return mixed Sent content.
314 function getRequest() {
319 * Accessor for raw text of page.
320 * @return string Raw unparsed content.
328 * Accessor for raw headers of page.
329 * @return string Header block as text.
332 function getHeaders() {
333 if ($this->_headers
) {
334 return $this->_headers
->getRaw();
340 * Original request method.
341 * @return string GET, POST or HEAD.
344 function getMethod() {
345 return $this->_method
;
349 * Original resource name.
350 * @return SimpleUrl Current url.
358 * Original request data.
359 * @return mixed Sent content.
362 function getRequestData() {
363 return $this->_request_data
;
367 * Accessor for last error.
368 * @return string Error from last response.
371 function getTransportError() {
372 return $this->_transport_error
;
376 * Accessor for current MIME type.
377 * @return string MIME type as string; e.g. 'text/html'
380 function getMimeType() {
381 if ($this->_headers
) {
382 return $this->_headers
->getMimeType();
388 * Accessor for HTTP response code.
389 * @return integer HTTP response code received.
392 function getResponseCode() {
393 if ($this->_headers
) {
394 return $this->_headers
->getResponseCode();
400 * Accessor for last Authentication type. Only valid
401 * straight after a challenge (401).
402 * @return string Description of challenge type.
405 function getAuthentication() {
406 if ($this->_headers
) {
407 return $this->_headers
->getAuthentication();
413 * Accessor for last Authentication realm. Only valid
414 * straight after a challenge (401).
415 * @return string Name of security realm.
418 function getRealm() {
419 if ($this->_headers
) {
420 return $this->_headers
->getRealm();
426 * Accessor for current frame focus. Will be
427 * false as no frames.
428 * @return array Always empty.
431 function getFrameFocus() {
436 * Sets the focus by index. The integer index starts from 1.
437 * @param integer $choice Chosen frame.
438 * @return boolean Always false.
441 function setFrameFocusByIndex($choice) {
446 * Sets the focus by name. Always fails for a leaf page.
447 * @param string $name Chosen frame.
448 * @return boolean False as no frames.
451 function setFrameFocus($name) {
456 * Clears the frame focus. Does nothing for a leaf page.
459 function clearFrameFocus() {
463 * Adds a tag to the page.
464 * @param SimpleTag $tag Tag to accept.
467 function acceptTag(&$tag) {
468 if ($tag->getTagName() == "a") {
469 $this->_addLink($tag);
470 } elseif ($tag->getTagName() == "title") {
471 $this->_setTitle($tag);
472 } elseif ($this->_isFormElement($tag->getTagName())) {
473 for ($i = 0; $i < count($this->_open_forms
); $i++
) {
474 $this->_open_forms
[$i]->addWidget($tag);
480 * Tests to see if a tag is a possible form
482 * @param string $name HTML element name.
483 * @return boolean True if form element.
486 function _isFormElement($name) {
487 return in_array($name, array('input', 'button', 'textarea', 'select'));
491 * Opens a form. New widgets go here.
492 * @param SimpleFormTag $tag Tag to accept.
495 function acceptFormStart(&$tag) {
496 $this->_open_forms
[] = &new SimpleForm($tag, $this->getUrl());
500 * Closes the most recently opened form.
503 function acceptFormEnd() {
504 if (count($this->_open_forms
)) {
505 $this->_complete_forms
[] = array_pop($this->_open_forms
);
510 * Opens a frameset. A frameset may contain nested
512 * @param SimpleFramesetTag $tag Tag to accept.
515 function acceptFramesetStart(&$tag) {
516 if (! $this->_isLoadingFrames()) {
517 $this->_frameset
= &$tag;
519 $this->_frameset_nesting_level++
;
523 * Closes the most recently opened frameset.
526 function acceptFramesetEnd() {
527 if ($this->_isLoadingFrames()) {
528 $this->_frameset_nesting_level
--;
533 * Takes a single frame tag and stashes it in
534 * the current frame set.
535 * @param SimpleFrameTag $tag Tag to accept.
538 function acceptFrame(&$tag) {
539 if ($this->_isLoadingFrames()) {
540 if ($tag->getAttribute('src')) {
541 $this->_frames
[] = &$tag;
547 * Test to see if in the middle of reading
549 * @return boolean True if inframeset.
552 function _isLoadingFrames() {
553 if (! $this->_frameset
) {
556 return ($this->_frameset_nesting_level
> 0);
560 * Test to see if link is an absolute one.
561 * @param string $url Url to test.
562 * @return boolean True if absolute.
565 function _linkIsAbsolute($url) {
566 $parsed = new SimpleUrl($url);
567 return (boolean
)($parsed->getScheme() && $parsed->getHost());
571 * Adds a link to the page.
572 * @param SimpleAnchorTag $tag Link to accept.
575 function _addLink($tag) {
576 $this->_links
[] = $tag;
580 * Test for the presence of a frameset.
581 * @return boolean True if frameset.
584 function hasFrames() {
585 return (boolean
)$this->_frameset
;
589 * Accessor for frame name and source URL for every frame that
590 * will need to be loaded. Immediate children only.
591 * @return boolean/array False if no frameset or
592 * otherwise a hash of frame URLs.
593 * The key is either a numerical
594 * base one index or the name attribute.
597 function getFrameset() {
598 if (! $this->_frameset
) {
602 for ($i = 0; $i < count($this->_frames
); $i++
) {
603 $name = $this->_frames
[$i]->getAttribute('name');
604 $url = new SimpleUrl($this->_frames
[$i]->getAttribute('src'));
605 $urls[$name ?
$name : $i +
1] = $url->makeAbsolute($this->getUrl());
611 * Fetches a list of loaded frames.
612 * @return array/string Just the URL for a single
616 function getFrames() {
617 $url = $this->getUrl();
618 return $url->asString();
622 * Accessor for a list of all fixed links.
623 * @return array List of urls with scheme of
624 * http or https and hostname.
627 function getAbsoluteUrls() {
629 foreach ($this->_links
as $link) {
630 if ($this->_linkIsAbsolute($link->getHref())) {
631 $all[] = $link->getHref();
638 * Accessor for a list of all relative links.
639 * @return array List of urls without hostname.
642 function getRelativeUrls() {
644 foreach ($this->_links
as $link) {
645 if (! $this->_linkIsAbsolute($link->getHref())) {
646 $all[] = $link->getHref();
653 * Space at the ends will be stripped and space in
654 * between is reduced to one space.
655 * @param string $html Typical HTML code.
656 * @return string Content as big string.
659 function _normalise($html) {
660 return preg_replace('/\S\s+\S/', ' ', strtolower(trim($html)));
664 * Matches strings regardles of varying whitespace.
665 * @param string $first First to match with.
666 * @param string $second Second to match against.
667 * @return boolean True if matches even with
668 * whitespace differences.
671 function _isNormalMatch($first, $second) {
672 return ($this->_normalise($first) == $this->_normalise($second));
676 * Accessor for URLs by the link label. Label will match
677 * regardess of whitespace issues and case.
678 * @param string $label Text of link.
679 * @return array List of links with that label.
682 function getUrlsByLabel($label) {
684 foreach ($this->_links
as $link) {
685 if ($this->_isNormalMatch($link->getContent(), $label)) {
686 $matches[] = $this->_getUrlFromLink($link);
693 * Accessor for a URL by the id attribute.
694 * @param string $id Id attribute of link.
695 * @return SimpleUrl URL with that id of false if none.
698 function getUrlById($id) {
699 foreach ($this->_links
as $link) {
700 if ($link->getAttribute('id') === (string)$id) {
701 return $this->_getUrlFromLink($link);
708 * Converts a link into a target URL.
709 * @param SimpleAnchor $link Parsed link.
710 * @return SimpleUrl URL with frame target if any.
713 function _getUrlFromLink($link) {
714 $url = $this->_makeAbsolute($link->getHref());
715 if ($link->getAttribute('target')) {
716 $url->setTarget($link->getAttribute('target'));
722 * Expands expandomatic URLs into fully qualified
724 * @param SimpleUrl $url Relative URL.
725 * @return SimpleUrl Absolute URL.
728 function _makeAbsolute($url) {
729 if (! is_object($url)) {
730 $url = new SimpleUrl($url);
732 return $url->makeAbsolute($this->getUrl());
736 * Sets the title tag contents.
737 * @param SimpleTitleTag $tag Title of page.
740 function _setTitle(&$tag) {
741 $this->_title
= &$tag;
745 * Accessor for parsed title.
746 * @return string Title or false if no title is present.
749 function getTitle() {
751 return $this->_title
->getContent();
757 * Finds a held form by button label. Will only
758 * search correctly built forms.
759 * @param string $label Button label, default 'Submit'.
760 * @return SimpleForm Form object containing the button.
763 function &getFormBySubmitLabel($label) {
764 for ($i = 0; $i < count($this->_complete_forms
); $i++
) {
765 if ($this->_complete_forms
[$i]->hasSubmitLabel($label)) {
766 return $this->_complete_forms
[$i];
773 * Finds a held form by button label. Will only
774 * search correctly built forms.
775 * @param string $name Button name attribute.
776 * @return SimpleForm Form object containing the button.
779 function &getFormBySubmitName($name) {
780 for ($i = 0; $i < count($this->_complete_forms
); $i++
) {
781 if ($this->_complete_forms
[$i]->hasSubmitName($name)) {
782 return $this->_complete_forms
[$i];
789 * Finds a held form by button id. Will only
790 * search correctly built forms.
791 * @param string $id Button ID attribute.
792 * @return SimpleForm Form object containing the button.
795 function &getFormBySubmitId($id) {
796 for ($i = 0; $i < count($this->_complete_forms
); $i++
) {
797 if ($this->_complete_forms
[$i]->hasSubmitId($id)) {
798 return $this->_complete_forms
[$i];
805 * Finds a held form by image label. Will only
806 * search correctly built forms.
807 * @param string $label Usually the alt attribute.
808 * @return SimpleForm Form object containing the image.
811 function &getFormByImageLabel($label) {
812 for ($i = 0; $i < count($this->_complete_forms
); $i++
) {
813 if ($this->_complete_forms
[$i]->hasImageLabel($label)) {
814 return $this->_complete_forms
[$i];
821 * Finds a held form by image button id. Will only
822 * search correctly built forms.
823 * @param string $name Image name.
824 * @return SimpleForm Form object containing the image.
827 function &getFormByImageName($name) {
828 for ($i = 0; $i < count($this->_complete_forms
); $i++
) {
829 if ($this->_complete_forms
[$i]->hasImageName($name)) {
830 return $this->_complete_forms
[$i];
837 * Finds a held form by image button id. Will only
838 * search correctly built forms.
839 * @param string $id Image ID attribute.
840 * @return SimpleForm Form object containing the image.
843 function &getFormByImageId($id) {
844 for ($i = 0; $i < count($this->_complete_forms
); $i++
) {
845 if ($this->_complete_forms
[$i]->hasImageId($id)) {
846 return $this->_complete_forms
[$i];
853 * Finds a held form by the form ID. A way of
854 * identifying a specific form when we have control
856 * @param string $id Form label.
857 * @return SimpleForm Form object containing the matching ID.
860 function &getFormById($id) {
861 for ($i = 0; $i < count($this->_complete_forms
); $i++
) {
862 if ($this->_complete_forms
[$i]->getId() == $id) {
863 return $this->_complete_forms
[$i];
870 * Sets a field on each form in which the field is
872 * @param string $name Field name.
873 * @param string $value Value to set field to.
874 * @return boolean True if value is valid.
877 function setField($name, $value) {
879 for ($i = 0; $i < count($this->_complete_forms
); $i++
) {
880 if ($this->_complete_forms
[$i]->setField($name, $value)) {
888 * Sets a field on the form in which the unique field is
890 * @param string/integer $id Field ID attribute.
891 * @param string $value Value to set field to.
892 * @return boolean True if value is valid.
895 function setFieldById($id, $value) {
896 for ($i = 0; $i < count($this->_complete_forms
); $i++
) {
897 if ($this->_complete_forms
[$i]->setFieldById($id, $value)) {
905 * Accessor for a form element value within a page.
906 * Finds the first match.
907 * @param string $name Field name.
908 * @return string/boolean A string if the field is
909 * present, false if unchecked
910 * and null if missing.
913 function getField($name) {
914 for ($i = 0; $i < count($this->_complete_forms
); $i++
) {
915 $value = $this->_complete_forms
[$i]->getValue($name);
924 * Accessor for a form element value within a page.
925 * Finds the first match.
926 * @param string/integer $id Field ID attribute.
927 * @return string/boolean A string if the field is
928 * present, false if unchecked
929 * and null if missing.
932 function getFieldById($id) {
933 for ($i = 0; $i < count($this->_complete_forms
); $i++
) {
934 $value = $this->_complete_forms
[$i]->getValueById($id);