3 * Base include file for SimpleTest
5 * @subpackage WebTester
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');
16 require_once(dirname(__FILE__
) . '/selector.php');
20 * Creates tags and widgets given HTML tag
23 * @subpackage WebTester
25 class SimpleTagBuilder
{
28 * Factory for the tag objects. Creates the
29 * appropriate tag object for the incoming tag name
31 * @param string $name HTML tag name.
32 * @param hash $attributes Element attributes.
33 * @return SimpleTag Tag object.
36 function createTag($name, $attributes) {
38 'a' => 'SimpleAnchorTag',
39 'title' => 'SimpleTitleTag',
40 'base' => 'SimpleBaseTag',
41 'button' => 'SimpleButtonTag',
42 'textarea' => 'SimpleTextAreaTag',
43 'option' => 'SimpleOptionTag',
44 'label' => 'SimpleLabelTag',
45 'form' => 'SimpleFormTag',
46 'frame' => 'SimpleFrameTag');
47 $attributes = $this->_keysToLowerCase($attributes);
48 if (array_key_exists($name, $map)) {
49 $tag_class = $map[$name];
50 return new $tag_class($attributes);
51 } elseif ($name == 'select') {
52 return $this->_createSelectionTag($attributes);
53 } elseif ($name == 'input') {
54 return $this->_createInputTag($attributes);
56 return new SimpleTag($name, $attributes);
60 * Factory for selection fields.
61 * @param hash $attributes Element attributes.
62 * @return SimpleTag Tag object.
65 function _createSelectionTag($attributes) {
66 if (isset($attributes['multiple'])) {
67 return new MultipleSelectionTag($attributes);
69 return new SimpleSelectionTag($attributes);
73 * Factory for input tags.
74 * @param hash $attributes Element attributes.
75 * @return SimpleTag Tag object.
78 function _createInputTag($attributes) {
79 if (! isset($attributes['type'])) {
80 return new SimpleTextTag($attributes);
82 $type = strtolower(trim($attributes['type']));
84 'submit' => 'SimpleSubmitTag',
85 'image' => 'SimpleImageSubmitTag',
86 'checkbox' => 'SimpleCheckboxTag',
87 'radio' => 'SimpleRadioButtonTag',
88 'text' => 'SimpleTextTag',
89 'hidden' => 'SimpleTextTag',
90 'password' => 'SimpleTextTag',
91 'file' => 'SimpleUploadTag');
92 if (array_key_exists($type, $map)) {
93 $tag_class = $map[$type];
94 return new $tag_class($attributes);
100 * Make the keys lower case for case insensitive look-ups.
101 * @param hash $map Hash to convert.
102 * @return hash Unchanged values, but keys lower case.
105 function _keysToLowerCase($map) {
107 foreach ($map as $key => $value) {
108 $lower[strtolower($key)] = $value;
115 * SAX event handler. Maintains a list of
116 * open tags and dispatches them as they close.
117 * @package SimpleTest
118 * @subpackage WebTester
120 class SimplePageBuilder
extends SimpleSaxListener
{
123 var $_private_content_tag;
126 * Sets the builder up empty.
129 function SimplePageBuilder() {
130 $this->SimpleSaxListener();
134 * Frees up any references so as to allow the PHP garbage
135 * collection from unset() to work.
141 unset($this->_private_content_tags
);
145 * Reads the raw content and send events
146 * into the page to be built.
147 * @param $response SimpleHttpResponse Fetched response.
148 * @return SimplePage Newly parsed page.
151 function &parse($response) {
152 $this->_tags
= array();
153 $this->_page
= &$this->_createPage($response);
154 $parser = &$this->_createParser($this);
155 $parser->parse($response->getContent());
156 $this->_page
->acceptPageEnd();
161 * Creates an empty page.
162 * @return SimplePage New unparsed page.
165 function &_createPage($response) {
166 $page = new SimplePage($response);
171 * Creates the parser used with the builder.
172 * @param $listener SimpleSaxListener Target of parser.
173 * @return SimpleSaxParser Parser to generate
174 * events for the builder.
177 function &_createParser(&$listener) {
178 $parser = new SimpleHtmlSaxParser($listener);
183 * Start of element event. Opens a new tag.
184 * @param string $name Element name.
185 * @param hash $attributes Attributes without content
186 * are marked as true.
187 * @return boolean False on parse error.
190 function startElement($name, $attributes) {
191 $factory = new SimpleTagBuilder();
192 $tag = $factory->createTag($name, $attributes);
196 if ($tag->getTagName() == 'label') {
197 $this->_page
->acceptLabelStart($tag);
198 $this->_openTag($tag);
201 if ($tag->getTagName() == 'form') {
202 $this->_page
->acceptFormStart($tag);
205 if ($tag->getTagName() == 'frameset') {
206 $this->_page
->acceptFramesetStart($tag);
209 if ($tag->getTagName() == 'frame') {
210 $this->_page
->acceptFrame($tag);
213 if ($tag->isPrivateContent() && ! isset($this->_private_content_tag
)) {
214 $this->_private_content_tag
= &$tag;
216 if ($tag->expectEndTag()) {
217 $this->_openTag($tag);
220 $this->_page
->acceptTag($tag);
225 * End of element event.
226 * @param string $name Element name.
227 * @return boolean False on parse error.
230 function endElement($name) {
231 if ($name == 'label') {
232 $this->_page
->acceptLabelEnd();
235 if ($name == 'form') {
236 $this->_page
->acceptFormEnd();
239 if ($name == 'frameset') {
240 $this->_page
->acceptFramesetEnd();
243 if ($this->_hasNamedTagOnOpenTagStack($name)) {
244 $tag = array_pop($this->_tags
[$name]);
245 if ($tag->isPrivateContent() && $this->_private_content_tag
->getTagName() == $name) {
246 unset($this->_private_content_tag
);
248 $this->_addContentTagToOpenTags($tag);
249 $this->_page
->acceptTag($tag);
256 * Test to see if there are any open tags awaiting
257 * closure that match the tag name.
258 * @param string $name Element name.
259 * @return boolean True if any are still open.
262 function _hasNamedTagOnOpenTagStack($name) {
263 return isset($this->_tags
[$name]) && (count($this->_tags
[$name]) > 0);
267 * Unparsed, but relevant data. The data is added
269 * @param string $text May include unparsed tags.
270 * @return boolean False on parse error.
273 function addContent($text) {
274 if (isset($this->_private_content_tag
)) {
275 $this->_private_content_tag
->addContent($text);
277 $this->_addContentToAllOpenTags($text);
283 * Any content fills all currently open tags unless it
284 * is part of an option tag.
285 * @param string $text May include unparsed tags.
288 function _addContentToAllOpenTags($text) {
289 foreach (array_keys($this->_tags
) as $name) {
290 for ($i = 0, $count = count($this->_tags
[$name]); $i < $count; $i++
) {
291 $this->_tags
[$name][$i]->addContent($text);
297 * Parsed data in tag form. The parsed tag is added
298 * to every open tag. Used for adding options to select
300 * @param SimpleTag $tag Option tags only.
303 function _addContentTagToOpenTags(&$tag) {
304 if ($tag->getTagName() != 'option') {
307 foreach (array_keys($this->_tags
) as $name) {
308 for ($i = 0, $count = count($this->_tags
[$name]); $i < $count; $i++
) {
309 $this->_tags
[$name][$i]->addTag($tag);
315 * Opens a tag for receiving content. Multiple tags
316 * will be receiving input at the same time.
317 * @param SimpleTag $tag New content tag.
320 function _openTag(&$tag) {
321 $name = $tag->getTagName();
322 if (! in_array($name, array_keys($this->_tags
))) {
323 $this->_tags
[$name] = array();
325 $this->_tags
[$name][] = &$tag;
330 * A wrapper for a web page.
331 * @package SimpleTest
332 * @subpackage WebTester
339 var $_left_over_labels;
341 var $_complete_forms;
344 var $_frameset_nesting_level;
345 var $_transport_error;
356 * Parses a page ready to access it's contents.
357 * @param SimpleHttpResponse $response Result of HTTP fetch.
360 function SimplePage($response = false) {
361 $this->_links
= array();
362 $this->_title
= false;
363 $this->_left_over_labels
= array();
364 $this->_open_forms
= array();
365 $this->_complete_forms
= array();
366 $this->_frameset
= false;
367 $this->_frames
= array();
368 $this->_frameset_nesting_level
= 0;
369 $this->_text
= false;
371 $this->_extractResponse($response);
373 $this->_noResponse();
378 * Extracts all of the response information.
379 * @param SimpleHttpResponse $response Response being parsed.
382 function _extractResponse($response) {
383 $this->_transport_error
= $response->getError();
384 $this->_raw
= $response->getContent();
385 $this->_sent
= $response->getSent();
386 $this->_headers
= $response->getHeaders();
387 $this->_method
= $response->getMethod();
388 $this->_url
= $response->getUrl();
389 $this->_request_data
= $response->getRequestData();
393 * Sets up a missing response.
396 function _noResponse() {
397 $this->_transport_error
= 'No page fetched yet';
399 $this->_sent
= false;
400 $this->_headers
= false;
401 $this->_method
= 'GET';
403 $this->_request_data
= false;
407 * Original request as bytes sent down the wire.
408 * @return mixed Sent content.
411 function getRequest() {
416 * Accessor for raw text of page.
417 * @return string Raw unparsed content.
425 * Accessor for plain text of page as a text browser
427 * @return string Plain text of page.
431 if (! $this->_text
) {
432 $this->_text
= SimpleHtmlSaxParser
::normalise($this->_raw
);
438 * Accessor for raw headers of page.
439 * @return string Header block as text.
442 function getHeaders() {
443 if ($this->_headers
) {
444 return $this->_headers
->getRaw();
450 * Original request method.
451 * @return string GET, POST or HEAD.
454 function getMethod() {
455 return $this->_method
;
459 * Original resource name.
460 * @return SimpleUrl Current url.
468 * Base URL if set via BASE tag page url otherwise
469 * @return SimpleUrl Base url.
472 function getBaseUrl() {
477 * Original request data.
478 * @return mixed Sent content.
481 function getRequestData() {
482 return $this->_request_data
;
486 * Accessor for last error.
487 * @return string Error from last response.
490 function getTransportError() {
491 return $this->_transport_error
;
495 * Accessor for current MIME type.
496 * @return string MIME type as string; e.g. 'text/html'
499 function getMimeType() {
500 if ($this->_headers
) {
501 return $this->_headers
->getMimeType();
507 * Accessor for HTTP response code.
508 * @return integer HTTP response code received.
511 function getResponseCode() {
512 if ($this->_headers
) {
513 return $this->_headers
->getResponseCode();
519 * Accessor for last Authentication type. Only valid
520 * straight after a challenge (401).
521 * @return string Description of challenge type.
524 function getAuthentication() {
525 if ($this->_headers
) {
526 return $this->_headers
->getAuthentication();
532 * Accessor for last Authentication realm. Only valid
533 * straight after a challenge (401).
534 * @return string Name of security realm.
537 function getRealm() {
538 if ($this->_headers
) {
539 return $this->_headers
->getRealm();
545 * Accessor for current frame focus. Will be
546 * false as no frames.
547 * @return array Always empty.
550 function getFrameFocus() {
555 * Sets the focus by index. The integer index starts from 1.
556 * @param integer $choice Chosen frame.
557 * @return boolean Always false.
560 function setFrameFocusByIndex($choice) {
565 * Sets the focus by name. Always fails for a leaf page.
566 * @param string $name Chosen frame.
567 * @return boolean False as no frames.
570 function setFrameFocus($name) {
575 * Clears the frame focus. Does nothing for a leaf page.
578 function clearFrameFocus() {
582 * Adds a tag to the page.
583 * @param SimpleTag $tag Tag to accept.
586 function acceptTag(&$tag) {
587 if ($tag->getTagName() == "a") {
588 $this->_addLink($tag);
589 } elseif ($tag->getTagName() == "base") {
590 $this->_setBase($tag);
591 } elseif ($tag->getTagName() == "title") {
592 $this->_setTitle($tag);
593 } elseif ($this->_isFormElement($tag->getTagName())) {
594 for ($i = 0; $i < count($this->_open_forms
); $i++
) {
595 $this->_open_forms
[$i]->addWidget($tag);
597 $this->_last_widget
= &$tag;
602 * Opens a label for a described widget.
603 * @param SimpleFormTag $tag Tag to accept.
606 function acceptLabelStart(&$tag) {
607 $this->_label
= &$tag;
608 unset($this->_last_widget
);
612 * Closes the most recently opened label.
615 function acceptLabelEnd() {
616 if (isset($this->_label
)) {
617 if (isset($this->_last_widget
)) {
618 $this->_last_widget
->setLabel($this->_label
->getText());
619 unset($this->_last_widget
);
621 $this->_left_over_labels
[] = SimpleTestCompatibility
::copy($this->_label
);
623 unset($this->_label
);
628 * Tests to see if a tag is a possible form
630 * @param string $name HTML element name.
631 * @return boolean True if form element.
634 function _isFormElement($name) {
635 return in_array($name, array('input', 'button', 'textarea', 'select'));
639 * Opens a form. New widgets go here.
640 * @param SimpleFormTag $tag Tag to accept.
643 function acceptFormStart(&$tag) {
644 $this->_open_forms
[] = new SimpleForm($tag, $this);
648 * Closes the most recently opened form.
651 function acceptFormEnd() {
652 if (count($this->_open_forms
)) {
653 $this->_complete_forms
[] = array_pop($this->_open_forms
);
658 * Opens a frameset. A frameset may contain nested
660 * @param SimpleFramesetTag $tag Tag to accept.
663 function acceptFramesetStart(&$tag) {
664 if (! $this->_isLoadingFrames()) {
665 $this->_frameset
= &$tag;
667 $this->_frameset_nesting_level++
;
671 * Closes the most recently opened frameset.
674 function acceptFramesetEnd() {
675 if ($this->_isLoadingFrames()) {
676 $this->_frameset_nesting_level
--;
681 * Takes a single frame tag and stashes it in
682 * the current frame set.
683 * @param SimpleFrameTag $tag Tag to accept.
686 function acceptFrame(&$tag) {
687 if ($this->_isLoadingFrames()) {
688 if ($tag->getAttribute('src')) {
689 $this->_frames
[] = &$tag;
695 * Test to see if in the middle of reading
697 * @return boolean True if inframeset.
700 function _isLoadingFrames() {
701 if (! $this->_frameset
) {
704 return ($this->_frameset_nesting_level
> 0);
708 * Test to see if link is an absolute one.
709 * @param string $url Url to test.
710 * @return boolean True if absolute.
713 function _linkIsAbsolute($url) {
714 $parsed = new SimpleUrl($url);
715 return (boolean
)($parsed->getScheme() && $parsed->getHost());
719 * Adds a link to the page.
720 * @param SimpleAnchorTag $tag Link to accept.
723 function _addLink($tag) {
724 $this->_links
[] = $tag;
728 * Marker for end of complete page. Any work in
729 * progress can now be closed.
732 function acceptPageEnd() {
733 while (count($this->_open_forms
)) {
734 $this->_complete_forms
[] = array_pop($this->_open_forms
);
736 foreach ($this->_left_over_labels
as $label) {
737 for ($i = 0, $count = count($this->_complete_forms
); $i < $count; $i++
) {
738 $this->_complete_forms
[$i]->attachLabelBySelector(
739 new SimpleById($label->getFor()),
746 * Test for the presence of a frameset.
747 * @return boolean True if frameset.
750 function hasFrames() {
751 return (boolean
)$this->_frameset
;
755 * Accessor for frame name and source URL for every frame that
756 * will need to be loaded. Immediate children only.
757 * @return boolean/array False if no frameset or
758 * otherwise a hash of frame URLs.
759 * The key is either a numerical
760 * base one index or the name attribute.
763 function getFrameset() {
764 if (! $this->_frameset
) {
768 for ($i = 0; $i < count($this->_frames
); $i++
) {
769 $name = $this->_frames
[$i]->getAttribute('name');
770 $url = new SimpleUrl($this->_frames
[$i]->getAttribute('src'));
771 $urls[$name ?
$name : $i +
1] = $this->expandUrl($url);
777 * Fetches a list of loaded frames.
778 * @return array/string Just the URL for a single page.
781 function getFrames() {
782 $url = $this->expandUrl($this->getUrl());
783 return $url->asString();
787 * Accessor for a list of all links.
788 * @return array List of urls with scheme of
789 * http or https and hostname.
794 foreach ($this->_links
as $link) {
795 $url = $this->_getUrlFromLink($link);
796 $all[] = $url->asString();
802 * Accessor for URLs by the link label. Label will match
803 * regardess of whitespace issues and case.
804 * @param string $label Text of link.
805 * @return array List of links with that label.
808 function getUrlsByLabel($label) {
810 foreach ($this->_links
as $link) {
811 if ($link->getText() == $label) {
812 $matches[] = $this->_getUrlFromLink($link);
819 * Accessor for a URL by the id attribute.
820 * @param string $id Id attribute of link.
821 * @return SimpleUrl URL with that id of false if none.
824 function getUrlById($id) {
825 foreach ($this->_links
as $link) {
826 if ($link->getAttribute('id') === (string)$id) {
827 return $this->_getUrlFromLink($link);
834 * Converts a link tag into a target URL.
835 * @param SimpleAnchor $link Parsed link.
836 * @return SimpleUrl URL with frame target if any.
839 function _getUrlFromLink($link) {
840 $url = $this->expandUrl($link->getHref());
841 if ($link->getAttribute('target')) {
842 $url->setTarget($link->getAttribute('target'));
848 * Expands expandomatic URLs into fully qualified
850 * @param SimpleUrl $url Relative URL.
851 * @return SimpleUrl Absolute URL.
854 function expandUrl($url) {
855 if (! is_object($url)) {
856 $url = new SimpleUrl($url);
858 $location = $this->getBaseUrl() ?
$this->getBaseUrl() : new SimpleUrl();
859 return $url->makeAbsolute($location->makeAbsolute($this->getUrl()));
863 * Sets the base url for the page.
864 * @param SimpleTag $tag Base URL for page.
867 function _setBase(&$tag) {
868 $url = $tag->getAttribute('href');
869 $this->_base
= new SimpleUrl($url);
873 * Sets the title tag contents.
874 * @param SimpleTitleTag $tag Title of page.
877 function _setTitle(&$tag) {
878 $this->_title
= &$tag;
882 * Accessor for parsed title.
883 * @return string Title or false if no title is present.
886 function getTitle() {
888 return $this->_title
->getText();
894 * Finds a held form by button label. Will only
895 * search correctly built forms.
896 * @param SimpleSelector $selector Button finder.
897 * @return SimpleForm Form object containing
901 function &getFormBySubmit($selector) {
902 for ($i = 0; $i < count($this->_complete_forms
); $i++
) {
903 if ($this->_complete_forms
[$i]->hasSubmit($selector)) {
904 return $this->_complete_forms
[$i];
912 * Finds a held form by image using a selector.
913 * Will only search correctly built forms.
914 * @param SimpleSelector $selector Image finder.
915 * @return SimpleForm Form object containing
919 function &getFormByImage($selector) {
920 for ($i = 0; $i < count($this->_complete_forms
); $i++
) {
921 if ($this->_complete_forms
[$i]->hasImage($selector)) {
922 return $this->_complete_forms
[$i];
930 * Finds a held form by the form ID. A way of
931 * identifying a specific form when we have control
933 * @param string $id Form label.
934 * @return SimpleForm Form object containing the matching ID.
937 function &getFormById($id) {
938 for ($i = 0; $i < count($this->_complete_forms
); $i++
) {
939 if ($this->_complete_forms
[$i]->getId() == $id) {
940 return $this->_complete_forms
[$i];
948 * Sets a field on each form in which the field is
950 * @param SimpleSelector $selector Field finder.
951 * @param string $value Value to set field to.
952 * @return boolean True if value is valid.
955 function setField($selector, $value, $position=false) {
957 for ($i = 0; $i < count($this->_complete_forms
); $i++
) {
958 if ($this->_complete_forms
[$i]->setField($selector, $value, $position)) {
966 * Accessor for a form element value within a page.
967 * @param SimpleSelector $selector Field finder.
968 * @return string/boolean A string if the field is
969 * present, false if unchecked
970 * and null if missing.
973 function getField($selector) {
974 for ($i = 0; $i < count($this->_complete_forms
); $i++
) {
975 $value = $this->_complete_forms
[$i]->getValue($selector);