NAME
Lithium::WebDriver - A WebDriver Client
DESCRIPTION
The Lithium::WebDriver module is accessed by the Synacor::Test::Selenium module to ensure commonality with existing tests.
FUNCTIONS
External functions are called with a parameterized format ie: DRIVER->some_function(timeout=> $some_timeout, selector => 'some css string')
new
Instantiate a new Web Driver object,
- protocol
-
Either http or https defaults to http
- host
-
A host string to connect to, defaults to localhost.
- port
-
Port to connect over.
- connection_timeout
-
Given in seconds, defaults to 3.
Calling
my $DRIVER = Lithium::WebDriver->new( connection_timeout => <INT>, host => <STRING>, port => <INT>, protocol => <STRING>, window_tracking => ['noop', 'strict'], );
Return Values
A webdriver object.
Parameters
connect
Connect to webdriver and open url. The url parameter is optional, if one was specified when creating the driver object.
- url
-
Unkeyed parameter denoting the url for the webdriver to connect to and test.
Calling
$DRIVER->connect( $url, );
Return Values
Parameters
disconnect
Stop the webdriver gracefully.
maximize
Maximize the currently selected window.
open
Navigate to a URL in the currently active window. The url does not need to be qualified as it will then be taken as the path parameter to the uri.
- url
-
The url to navigate to, paths without hostnames are valid.
- timeout
-
Optional keyed parameter in seconds, defaults to 3.
Calling
$DRIVER->open( url => <STRING>, timeout => <INT>, );
Return Values
False if the webdriver status is negative
Parameters
visit
This is an alias for open.
open_window
Navigate to a URL in a new window. The url does not need to be qualified as it will then be taken as the path parameter to the uri.
window_tracking
Turn on, or off window tracking strictness (local window list). The only parameter is noop for off, or strict for maintaining the most up-to-date local window list.
The only parameters are 'noop' or 'strict' strings. Noop disables window list updating for most calls, and 'strict' is the legacy behavior.
update_windows
Manually update the window list. This function takes no paramters, and has no return values. This function has no parameters or return values. This is a useful function when window_tracking is set to noop.
select_window
given a method navigate to a differnet (or same) opened window.
- method
-
Available methods are last, num, title and first. Title and num require a value parameter, otherwise first and last do not require a value parameter.
- value
-
Either the title or window number to switch to.
- timeout
-
Timeout on waiting for windows to get their document readiness. Defaults to 3 seconds.
Calling
$DRIVER->select_window( method => <STRING>, value => <STRING>, timeout => <INT>, );
Return Values
Parameters
close_window
Close a window by either switching to it and closing it or closing the current window, if no parameters are set.
Calling
$DRIVER->close_window( [method => <STRING>,] [value => <STRING>,] [timeout => <INT>,] );
Return Value
Parameters
See select_window for parameter descriptions
window_size
Set the window size, given no parameters defaults to Full 1080 HD :)
window_handle
return the opaque window ID of the currently active window.
window
Alias of window_handle
window_handles
return an array of opaque window ids
windows
Alias of window_handles
window_names
Get an array of all the currently opened windows.
source
Get the current html source of the currently focused page. This chould change depending on javascript calls.
refresh
Refresh the current page, equivelent to hitting the f5 key or ctrl+R, there is also a built in waiting for the document (current page) to finish loading (document.ready)
implicit_wait
When searching for a HTML element, wait on the server (page to load/javascript). Takes a time in seconds.
sessions
Get a list of all the current sessions
status
Get the webdriver status, useful to see if it's up, without instantiating a session.
title
Get the title of the currently focused window
url
Get the url of the currently focused window.
run
run javascript function represented by string input.
- js
-
A string representation of the javascript to run.
Calling
$DRIVER->run( js => "SOME javascript here", );
Return Values
The return value of the executed javascript.
Parameters
run_async
run asyncronus javascript (XHR?), similar to run.
attribute
Given a css identifier, get a html attribute of the first found element.
- selector
-
The css string element identifier.
- attr
-
The specific attribute to get, options are: exist/present, html, text, selected, location, displayed/visible, otherwise any valid html attribute can be used.
- timeout
-
Time in seconds to wait for the webdriver to find the element using the css string.
Calling
$DRIVER->attribute( attr => <STRING>, timeout => <INT>, selector => <STRING> );
Return Values
False on unable to find or unable to find element attribute.
Parameters
present($selector)
Alias to $attribute( attr => 'present', selector => $selector);
visible
Alias to $attribute( attr => 'visible', selector => $selector);
text
Alias to $attribute( attr => 'text', selector => $selector);
value
Alias to $attribute( attr => 'value', selector => $selector);
html
Alias to $attribute( attr => 'html', selector => $selector);
dropdown
manipulate dropdowns.
- selector
-
The CSS element selector for the dropdown element.
- timeout
-
Timeout after this many seconds if unable to find this element.
- method
-
The method to use to return the dropdown options can be label or value, where label is the text label that shows up and value is the value that would be set on selection
- value
-
The option to pick by means of method, this parameter is optional. If unset an array of values/labels will be returned.
Calling
$DRIVER->dropdown( selector => $selector, timeout => $timeout, method => 'label|value', value => $label_name, );
Return Value
False on unable to find element. False on unexistent option. If no value is given return a list of options values or labels.
Parameters
log_types
Get the log types from the webdriver.
Calling
$DRIVER->log_types();
Return Values
The log types represented by and array of strings.
Parameters
None
browser_logs
Get the WebBrowser logs from the connected driver.
Calling
$DRIVER->browser_logs();
Return Values
A perl data structure representing the web-console, log lines.
The log lines, represent by an array of the following element structure:
{ level: The log level of the message ie: INFO, WARN, CRIT. timestamp: Milliesecond unix timestamp. message: Character string of the message. }
Parameters
None.
har_logs
Get HAR logs (Http Archive).
Calling
$DRIVER->har_logs(type => <STRING>);
Return Values
If a type [error, info] is given then the return object is an array of http calls, that consist of the follow object:
{ method: Http method ie: GET status: The http code (204) reason: The string explaination of the http code. url: The url of the http call }
Otherwise if no type is set a perl object of the complete, HAR is returned.
Parameters
mouseover
By using a css selector ($selector), find a html input element and move the mouse to hover over it.
- selector
-
A css selector for a html input element, can be of any sort of input (text area or otherwise).
- timeout
-
Time out and return false after a given amount of seconds.
Calling
Return Values
Parameters
click
By using a css selector ($selector), find a html element and attempt to click on it. This function also supports clicking on the element at a given location (x, y from the upper left corner).
- selector
-
A css selector for a clickable html element.
- timeout
-
Time out and return false after a given amount of seconds.
- x
-
The x cordinate from the upper left corner of the html element (OPTIONAL).
- y
-
The y cordinate from the upper left corner of the html element (OPTIONAL).
Calling
$DRIVER->click( selector => $selector, timeout => $timeout, x => $x, y => $y, );
Return Value
False on unable to find $selector
Parameters
type
By using a css selector ($selector), find a html input element and type a string ($value) into it. This check times out after the set timeout ($timeout) in seconds.
- selector
-
A css selector for a html input element, can be of any sort of input (text area or otherwise).
- value
-
The string you wish to type into the selector element.
- timeout
-
Time out and return false after a given amount of seconds.
Calling
$DRIVER->type( selector => $selector, timeout => $timeout, value => $value, );
Return Value
False on unable to find $selector
Parameters
check
Check a checkbox. Will leave a checked checkbox checked.
- selector
-
The css selector string that will match the first element
- timeout
-
time out in seconds, will return false on timeout.
Calling
$DRIVER->check( selector => $selector, timeout => $timeout, );
Return Value
False on unable to find $selector
Parameters
uncheck
Un-check a checkbox.
screenshot
Get a screenshot of the currently active window.
- filename
-
The file name to save the screenshot to.
Parameters
frame
Change the DOM context to that of an iframe. A selector value of default will change to the beginning frame context, IE the Top Level parent, and a selector value of parent will go up one level. When switching frames, the entire DOM context is switched to the newly selected iframe. You will have to reset your context to go to select any elements outside of the current iframe.
- 0
-
Indicates the function failed to switch context, or the frame id was not found.
- 1
-
Indicates successful context switching.
- selector
-
The CSS Selector of the iframe to switch context to. The other possible value is 'default' which will reset the context to the main/top level frame, or the original DOM.
- timeout
-
The time to wait for search for an iframe by CSS selector.
Calling
$DRIVER->frame( selector => 'css selector|default|parent', timeout => INT);
Return Values
Parameters
reset_frame
When a frame is selected, then the flow is continued, often, the original page has been left, either by form submittal or page reload, this function provides a failsafe, to reset the internal state machine to before an iframe was entered.
- 1
-
The call to /frame was a success
- 0
-
The call to /frame was not successful, but this will not affect future calls.
Calling
$DRIVER->reset_frame();
Return Values
Parameter
None.
wait_for_it
Given another function in this module, turn it into a waiting function, until either a timeout or a successful return.
- 0
-
Indicates the subroutine passed in never returned positively, and wait_for_it timed out.
- 1
-
Expected the subroutine passed in returned positively.
- subroutine
-
An anonymous sub to be executed until it returns a true value.
- timeout
-
Time to wait for sub to return true.
Calling
$DRIVER->wait_for_it( sub { <code returning a boolean value> }, $timeout);
Return Values
Parameters
Add all parameters for the called sub to the end of the function call.
wait_timeout
Sets the implicit wait timeout of the WebDriver instance. Takes a time in seconds.
cancel
Used to cancel a JS alert() dialog.
confirm
Used to confirm a JS alert() dialog.
alert_text
Used to set or get the text of a JS alert() dialog.
If passed a string, it will set the alert text and pop up a new alert. Otherwise, will return the current alert text.
BUGS
Early in development it was found that after setting a useragent string, with phantomjs it would get dropped when a new window was manually created or created by a website (think target='_blank'). A bug was filed with ghostdriver project but little progress has been made.
A possible work around is to determine the redirection url, and navigate your first window to it, as this window still has the "fake" user agent. A second one is to not use target="_blank" in your anchor tags, as this is commonally seen as poor website design, ie: that choice should be left up to the user.
AUTHOR
Written by Dan Molik <dan at d3fy dot net>