PHP Class SimpleBrowser, simpletest

@package SimpleTest
ファイルを表示 Open project: simpletest/simpletest Class Usage Examples

Public Methods

Method Description
__construct ( ) Starts with a fresh browser with no cookie or any other state information.
addHeader ( string $header ) Adds a header to every fetch.
ageCookies ( integer $interval ) Ages the cookies by the specified time.
authenticate ( string $username, string $password ) : boolean Retries a request after setting the authentication for the current realm.
back ( ) : boolean Equivalent to hitting the back button on the browser.
clearFrameFocus ( ) Clears the frame focus. All frames will be searched for content.
click ( string $label ) : string/boolean Clicks a visible text item. Will first try buttons, then links and then images.
clickImage ( string $label, integer $x = 1, integer $y = 1, hash $additional = false ) : string/boolean Clicks the submit image by some kind of label.
clickImageById ( integer/string $id, integer $x = 1, integer $y = 1, hash $additional = false ) : string/boolean Clicks the submit image by ID attribute.
clickImageByName ( string $name, integer $x = 1, integer $y = 1, hash $additional = false ) : string/boolean Clicks the submit image by the name.
clickLink ( string $label, integer $index ) : boolean Follows a link by label.
clickLinkById ( string $id ) : string/boolean Follows a link by id attribute.
clickSubmit ( string $label = 'Submit', hash $additional = false ) : string/boolean Clicks the submit button by label. The owning form will be submitted by this.
clickSubmitById ( string $id, hash $additional = false ) : string/boolean Clicks the submit button by ID attribute of the button itself. The owning form will be submitted by this.
clickSubmitByName ( string $name, hash $additional = false ) : string/boolean Clicks the submit button by name attribute. The owning form will be submitted by this.
delete ( string/SimpleUrl $url, hash/SimpleFormEncoding $parameters = false ) : string Sends a DELETE request and fetches the response.
forward ( ) : boolean Equivalent to hitting the forward button on the browser.
get ( string/SimpleUrl $url, hash/SimpleFormEncoding $parameters = false ) : string Fetches the page content with a simple GET request.
getAuthentication ( ) : string Accessor for last Authentication type. Only valid straight after a challenge (401).
getBaseUrl ( ) : string Accessor for base URL of page if set via BASE tag
getContent ( ) : string Accessor for raw page information.
getContentAsText ( ) : string Accessor for plain text version of the page.
getCookieValue ( string $host, string $path, string $name ) : string Reads the most specific cookie value from the browser cookies.
getCurrentCookieValue ( string $name ) : string Reads the current cookies for the current URL.
getField ( string $label ) : string/boolean Accessor for a form element value within the page.
getFieldById ( string/integer $id ) : string/boolean Accessor for a form element value within the page.
getFieldByName ( string $name ) : string/boolean Accessor for a form element value within the page. Finds the first match.
getFrameFocus ( ) : integer/string/boolean Accessor for current frame focus. Will be false if no frame has focus.
getFrames ( ) : array Accessor for a breakdown of the frameset.
getHeaders ( ) : string Accessor for raw header information.
getLink ( string $label, integer $index ) : string/boolean Finds a URL by label. Will find the first link found with this link text by default, or a later one if an index is given. The match ignores case and white space issues.
getLinkById ( string $id ) : string/boolean Finds a link by id attribute.
getMimeType ( ) : string Accessor for current MIME type.
getRealm ( ) : string Accessor for last Authentication realm. Only valid straight after a challenge (401).
getRequest ( ) : string Accessor for raw bytes sent down the wire.
getResponseCode ( ) : integer Accessor for last response code.
getTitle ( ) : string Accessor for parsed title.
getTransportError ( ) : string Accessor for last error.
getUrl ( ) : string Accessor for current URL of page or frame if focused.
getUrls ( ) : array Accessor for a list of all links in current page.
head ( string/SimpleUrl $url, hash/SimpleHeadEncoding $parameters = false ) : boolean Fetches the page content with a HEAD request.
ignoreCookies ( ) Switches off cookie sending and recieving.
ignoreFrames ( ) Disables frames support.
isClickable ( string $label ) : boolean Tests to see if a click target exists.
isImage ( string $label ) : boolean Tests to see if an image exists with this title or alt text.
isSubmit ( string $label ) : boolean Tests to see if a submit button exists with this label.
post ( string/SimpleUrl $url, hash/SimpleFormEncoding $parameters = false, string $content_type = false ) : string Fetches the page content with a POST request.
put ( string/SimpleUrl $url, hash/SimpleFormEncoding $parameters = false, string $content_type = false ) : string Fetches the page content with a PUT request.
restart ( string/integer $date = false ) Removes expired and temporary cookies as if the browser was closed and re-opened.
retry ( ) : string/boolean Equivalent to hitting the retry button on the browser.
setConnectionTimeout ( integer $timeout ) Sets the socket timeout for opening a connection.
setCookie ( string $name, string $value, string $host = false, string $path = '/', string $expiry = false ) Sets an additional cookie.
setField ( string $label, string $value, $position = false ) : boolean Sets all form fields with that name.
setFieldById ( string/integer $id, string $value ) : boolean Sets all form fields with that id attribute.
setFieldByName ( string $name, string $value, $position = false ) : boolean Sets all form fields with that name. Will use label if one is available (not yet implemented).
setFrameFocus ( string $name ) : boolean Sets the focus by name.
setFrameFocusByIndex ( integer $choice ) : boolean Sets the focus by index. The integer index starts from 1.
setMaximumNestedFrames ( integer $max ) Sets the maximum number of nesting of framed pages within a framed page to prevent loops.
setMaximumRedirects ( integer $max ) Sets the maximum number of redirects before a page will be loaded anyway.
setParser ( $parser ) Override the default HTML parser, allowing parsers to be plugged in.
submitFormById ( string $id, $additional = false ) : string/boolean Submits a form by the ID.
useCookies ( ) Switches back on the cookie sending and recieving.
useFrames ( ) Enables frames support. Frames will be fetched from now on.
useProxy ( string $proxy, string $username = false, string $password = false ) Sets proxy to use on all requests for when testing from behind a firewall.

Protected Methods

Method Description
buildPage ( SimpleHttpResponse $response ) : SimplePage Assembles the parsing machinery and actually parses a single page.
createHistory ( ) : SimpleBrowserHistory Creates a new empty history list.
createUserAgent ( ) : SimpleUserAgent Creates the underlying user agent.
fetch ( string/SimpleUrl $url, SimpleEncoding $encoding, integer $depth ) : SimplePage Fetches a page.
getParser ( ) : object Get the HTML parser to use. Can be overridden by setParser.
load ( SimpleUrl $url, SimpleEncoding $parameters ) : string Fetches a page or a single frame if that is the current focus.
loadFrame ( array $frames, string/SimpleUrl $url, SimpleFormEncoding $parameters ) : string Fetches a frame into the existing frameset replacing the original.
loadPage ( string/SimpleUrl $url, SimplePostEncoding $parameters ) : string Fetches a page and makes it the current page/frame.
parse ( SimpleHttpResponse $response, integer $depth ) : SimplePage Parses the raw content into a page.

Method Details

__construct() public method

The exception is that a default proxy will be set up if specified in the options.
public __construct ( )

addHeader() public method

Adds a header to every fetch.
public addHeader ( string $header )
$header string Header line to add to every request until cleared.

ageCookies() public method

Ages the cookies by the specified time.
public ageCookies ( integer $interval )
$interval integer Amount in seconds.

authenticate() public method

Retries a request after setting the authentication for the current realm.
public authenticate ( string $username, string $password ) : boolean
$username string Username for realm.
$password string Password for realm.
return boolean True if successful fetch. Note that authentication may still have failed.

back() public method

The browser history is unchanged on failure. The page content is refetched as there is no concept of content caching in SimpleTest.
public back ( ) : boolean
return boolean True if history entry and fetch succeeded

buildPage() protected method

Frees all of the builder memory and so unjams the PHP memory management.
protected buildPage ( SimpleHttpResponse $response ) : SimplePage
$response SimpleHttpResponse Response from fetch.
return SimplePage Parsed top level page.

clearFrameFocus() public method

Clears the frame focus. All frames will be searched for content.
public clearFrameFocus ( )

click() public method

Clicks a visible text item. Will first try buttons, then links and then images.
public click ( string $label ) : string/boolean
$label string Visible text or alt text.
return string/boolean

clickImage() public method

Usually the alt tag or the nearest equivalent. The owning form will be submitted by this. Clicking outside of the boundary of the coordinates will result in a failure.
public clickImage ( string $label, integer $x = 1, integer $y = 1, hash $additional = false ) : string/boolean
$label string ID attribute of button.
$x integer X-coordinate of imaginary click.
$y integer Y-coordinate of imaginary click.
$additional hash Additional form data.
return string/boolean

clickImageById() public method

The owning form will be submitted by this. Clicking outside of the boundary of the coordinates will result in a failure.
public clickImageById ( integer/string $id, integer $x = 1, integer $y = 1, hash $additional = false ) : string/boolean
$id integer/string
$x integer X-coordinate of imaginary click.
$y integer Y-coordinate of imaginary click.
$additional hash Additional form data.
return string/boolean

clickImageByName() public method

Usually the alt tag or the nearest equivalent. The owning form will be submitted by this. Clicking outside of the boundary of the coordinates will result in a failure.
public clickImageByName ( string $name, integer $x = 1, integer $y = 1, hash $additional = false ) : string/boolean
$name string Name attribute of button.
$x integer X-coordinate of imaginary click.
$y integer Y-coordinate of imaginary click.
$additional hash Additional form data.
return string/boolean

clickLinkById() public method

Follows a link by id attribute.
public clickLinkById ( string $id ) : string/boolean
$id string ID attribute value.
return string/boolean

clickSubmit() public method

Clicks the submit button by label. The owning form will be submitted by this.
public clickSubmit ( string $label = 'Submit', hash $additional = false ) : string/boolean
$label string Button label. An unlabeled button can be triggered by 'Submit'.
$additional hash Additional form data.
return string/boolean

clickSubmitById() public method

Clicks the submit button by ID attribute of the button itself. The owning form will be submitted by this.
public clickSubmitById ( string $id, hash $additional = false ) : string/boolean
$id string Button ID.
$additional hash Additional form data.
return string/boolean

clickSubmitByName() public method

Clicks the submit button by name attribute. The owning form will be submitted by this.
public clickSubmitByName ( string $name, hash $additional = false ) : string/boolean
$name string Button name.
$additional hash Additional form data.
return string/boolean

createHistory() protected method

Creates a new empty history list.
protected createHistory ( ) : SimpleBrowserHistory
return SimpleBrowserHistory New list.

createUserAgent() protected method

Creates the underlying user agent.
protected createUserAgent ( ) : SimpleUserAgent
return SimpleUserAgent Content fetcher.

delete() public method

Sends a DELETE request and fetches the response.
public delete ( string/SimpleUrl $url, hash/SimpleFormEncoding $parameters = false ) : string
$url string/SimpleUrl
$parameters hash/SimpleFormEncoding
return string Content of page or false.

fetch() protected method

Jointly recursive with the parse() method as it descends a frameset.
protected fetch ( string/SimpleUrl $url, SimpleEncoding $encoding, integer $depth ) : SimplePage
$url string/SimpleUrl
$encoding SimpleEncoding GET/POST parameters.
$depth integer Nested frameset depth protection.
return SimplePage Parsed page.

forward() public method

The browser history is unchanged on failure. The page content is refetched as there is no concept of content caching in SimpleTest.
public forward ( ) : boolean
return boolean True if history entry and fetch succeeded

get() public method

Fetches the page content with a simple GET request.
public get ( string/SimpleUrl $url, hash/SimpleFormEncoding $parameters = false ) : string
$url string/SimpleUrl
$parameters hash/SimpleFormEncoding
return string Content of page or false.

getAuthentication() public method

Accessor for last Authentication type. Only valid straight after a challenge (401).
public getAuthentication ( ) : string
return string Description of challenge type.

getBaseUrl() public method

Accessor for base URL of page if set via BASE tag
public getBaseUrl ( ) : string
return string base URL

getContent() public method

Accessor for raw page information.
public getContent ( ) : string
return string Original text content of web page.

getContentAsText() public method

Accessor for plain text version of the page.
public getContentAsText ( ) : string
return string Normalised text representation.

getCookieValue() public method

Reads the most specific cookie value from the browser cookies.
public getCookieValue ( string $host, string $path, string $name ) : string
$host string Host to search.
$path string Applicable path.
$name string Name of cookie to read.
return string False if not present, else the value as a string.

getCurrentCookieValue() public method

Reads the current cookies for the current URL.
public getCurrentCookieValue ( string $name ) : string
$name string Key of cookie to find.
return string Null if there is no current URL, false if the cookie is not set.

getField() public method

Finds the first match.
public getField ( string $label ) : string/boolean
$label string Field label.
return string/boolean

getFieldById() public method

Accessor for a form element value within the page.
public getFieldById ( string/integer $id ) : string/boolean
$id string/integer
return string/boolean

getFieldByName() public method

Accessor for a form element value within the page. Finds the first match.
public getFieldByName ( string $name ) : string/boolean
$name string Field name.
return string/boolean

getFrameFocus() public method

Accessor for current frame focus. Will be false if no frame has focus.
public getFrameFocus ( ) : integer/string/boolean
return integer/string/boolean

getFrames() public method

Accessor for a breakdown of the frameset.
public getFrames ( ) : array
return array Hash tree of frames by name or index if no name.

getHeaders() public method

Accessor for raw header information.
public getHeaders ( ) : string
return string Header block.

getLinkById() public method

Finds a link by id attribute.
public getLinkById ( string $id ) : string/boolean
$id string ID attribute value.
return string/boolean

getMimeType() public method

Accessor for current MIME type.
public getMimeType ( ) : string
return string MIME type as string; e.g. 'text/html'

getParser() protected method

Otherwise scans through the available parsers and uses the first one which is available.
protected getParser ( ) : object
return object SimplePHPPageBuilder or SimpleTidyPageBuilder

getRealm() public method

Accessor for last Authentication realm. Only valid straight after a challenge (401).
public getRealm ( ) : string
return string Name of security realm.

getRequest() public method

Accessor for raw bytes sent down the wire.
public getRequest ( ) : string
return string Original text sent.

getResponseCode() public method

Accessor for last response code.
public getResponseCode ( ) : integer
return integer Last HTTP response code received.

getTitle() public method

Accessor for parsed title.
public getTitle ( ) : string
return string Title or false if no title is present.

getTransportError() public method

Accessor for last error.
public getTransportError ( ) : string
return string Error from last response.

getUrl() public method

Accessor for current URL of page or frame if focused.
public getUrl ( ) : string
return string Location of current page or frame as a string.

getUrls() public method

Accessor for a list of all links in current page.
public getUrls ( ) : array
return array List of urls with scheme of http or https and hostname.

head() public method

Will affect cookies, but will not change the base URL.
public head ( string/SimpleUrl $url, hash/SimpleHeadEncoding $parameters = false ) : boolean
$url string/SimpleUrl
$parameters hash/SimpleHeadEncoding
return boolean True if successful.

ignoreCookies() public method

Switches off cookie sending and recieving.
public ignoreCookies ( )

ignoreFrames() public method

Frames will not be fetched and the frameset page will be used instead.
public ignoreFrames ( )

isClickable() public method

Tests to see if a click target exists.
public isClickable ( string $label ) : boolean
$label string Visible text or alt text.
return boolean True if target present.

isImage() public method

Tests to see if an image exists with this title or alt text.
public isImage ( string $label ) : boolean
$label string Image text.
return boolean True if present.

isSubmit() public method

Tests to see if a submit button exists with this label.
public isSubmit ( string $label ) : boolean
$label string Button label.
return boolean True if present.

load() protected method

Fetches a page or a single frame if that is the current focus.
protected load ( SimpleUrl $url, SimpleEncoding $parameters ) : string
$url SimpleUrl Target to fetch.
$parameters SimpleEncoding GET/POST parameters.
return string Raw content of page.

loadFrame() protected method

Fetches a frame into the existing frameset replacing the original.
protected loadFrame ( array $frames, string/SimpleUrl $url, SimpleFormEncoding $parameters ) : string
$frames array List of names to drill down.
$url string/SimpleUrl
$parameters SimpleFormEncoding POST parameters.
return string Raw content of page.

loadPage() protected method

Fetches a page and makes it the current page/frame.
protected loadPage ( string/SimpleUrl $url, SimplePostEncoding $parameters ) : string
$url string/SimpleUrl
$parameters SimplePostEncoding POST parameters.
return string Raw content of page.

parse() protected method

Will load further frame pages unless frames are disabled.
protected parse ( SimpleHttpResponse $response, integer $depth ) : SimplePage
$response SimpleHttpResponse Response from fetch.
$depth integer Nested frameset depth.
return SimplePage Parsed HTML.

post() public method

Fetches the page content with a POST request.
public post ( string/SimpleUrl $url, hash/SimpleFormEncoding $parameters = false, string $content_type = false ) : string
$url string/SimpleUrl
$parameters hash/SimpleFormEncoding
$content_type string MIME Content-Type of the request body
return string Content of page.

put() public method

Fetches the page content with a PUT request.
public put ( string/SimpleUrl $url, hash/SimpleFormEncoding $parameters = false, string $content_type = false ) : string
$url string/SimpleUrl
$parameters hash/SimpleFormEncoding
$content_type string MIME Content-Type of the request body
return string Content of page.

restart() public method

Removes expired and temporary cookies as if the browser was closed and re-opened.
public restart ( string/integer $date = false )
$date string/integer

retry() public method

Will attempt to repeat the page fetch. If there is no history to repeat it will give false.
public retry ( ) : string/boolean
return string/boolean

setConnectionTimeout() public method

Sets the socket timeout for opening a connection.
public setConnectionTimeout ( integer $timeout )
$timeout integer Maximum time in seconds.

setCookie() public method

If a cookie has the same name and path it is replaced.
public setCookie ( string $name, string $value, string $host = false, string $path = '/', string $expiry = false )
$name string Cookie key.
$value string Value of cookie.
$host string Host upon which the cookie is valid.
$path string Cookie path if not host wide.
$expiry string Expiry date.

setField() public method

Sets all form fields with that name.
public setField ( string $label, string $value, $position = false ) : boolean
$label string Name or label of field in forms.
$value string New value of field.
return boolean True if field exists, otherwise false.

setFieldById() public method

Sets all form fields with that id attribute.
public setFieldById ( string/integer $id, string $value ) : boolean
$id string/integer
$value string New value of field.
return boolean True if field exists, otherwise false.

setFieldByName() public method

Sets all form fields with that name. Will use label if one is available (not yet implemented).
public setFieldByName ( string $name, string $value, $position = false ) : boolean
$name string Name of field in forms.
$value string New value of field.
return boolean True if field exists, otherwise false.

setFrameFocus() public method

Sets the focus by name.
public setFrameFocus ( string $name ) : boolean
$name string Chosen frame.
return boolean True if frame exists.

setFrameFocusByIndex() public method

Sets the focus by index. The integer index starts from 1.
public setFrameFocusByIndex ( integer $choice ) : boolean
$choice integer Chosen frame.
return boolean True if frame exists.

setMaximumNestedFrames() public method

Sets the maximum number of nesting of framed pages within a framed page to prevent loops.
public setMaximumNestedFrames ( integer $max )
$max integer Highest depth allowed.

setMaximumRedirects() public method

Sets the maximum number of redirects before a page will be loaded anyway.
public setMaximumRedirects ( integer $max )
$max integer Most hops allowed.

setParser() public method

Override the default HTML parser, allowing parsers to be plugged in.
public setParser ( $parser )

submitFormById() public method

Submits a form by the ID.
public submitFormById ( string $id, $additional = false ) : string/boolean
$id string The form ID. No submit button value will be sent.
return string/boolean

useCookies() public method

Switches back on the cookie sending and recieving.
public useCookies ( )

useFrames() public method

Enables frames support. Frames will be fetched from now on.
public useFrames ( )

useProxy() public method

Set URL to false to disable.
public useProxy ( string $proxy, string $username = false, string $password = false )
$proxy string Proxy URL.
$username string Proxy username for authentication.
$password string Proxy password for authentication.