This component wraps a WebDriver driver.
A driver can be used to control a browser installed on the system. On startup, a webdriver instance is built. When the
driver is ready, the onDriverReady event is fired.
| Option | Type | Description |
|---|---|---|
asyncScriptTimeout |
{Integer} |
The number of milliseconds to wait before timing out calls to executeAsyncScript (see below). Defaults to 10000 (10 seconds). |
browser |
{String} |
A lowercase string identifying which supported browser to use. The SELENIUM_BROWSER environment variable will always take precedence over this value. Defaults to "firefox". |
browserOptions |
{Object} |
A map of browser options, keyed at the top level by the browser name ("chrome", "ie", etc.). If options exist for that.options.browser, they will be passed to the builder before the driver is created. |
headlessBrowserOptions |
{Object} |
A map of browser options (see above) to use when running the tests in "headless" mode. If there are no options for a given browser here, the options in browserOptions will be used instead. |
logOnQuit |
{Boolean} |
Whether to dump the webdriver log output to console.log when the browser is quit. Defaults to false. |
Retrieves an actions instance that can be used to perform one or more actions in the current browser. This value is
passed as the result of onActionsComplete. Returns a promise that is resolved with the same value.
Typically you will use {that}.actionsHelper (see below) rather than calling this directly. If you choose to use this directly,
be aware that you must explicitly call perform
to complete your action sequence.
View the WebDriver API documentation for more details on the underlying actions function.
A helper which constructs an entire sequence of actions and executes them in order (including adding the final perform
step to indicate that the sequence is complete). Fires onActionsHelperComplete when all actions have been performed.
Returns a promise that is resolved when all actions have been performed.
Each element in actionsArray is expected to be an object whose fn value represents the function name to be executed,
and whose args value represents the arguments to be passed to the function. For example:
{ fn: "sendKeys", args: [fluid.webdriver.Key.TAB, fluid.webdriver.Key.TAB]};Note that if you wish to pass multiple actions, you will need to pass an array as the first argument, as in:
[{ fn: "sendKeys", args: [fluid.webdriver.Key.TAB]}, { fn: "sendKeys", args: [fluid.webdriver.Key.TAB]}];The range of supported actions and options can be found in the WebDriver documentation.
This function is not used or tested in this module, but is exposed for future developers to explore and extend as desired.
View the WebDriver API documentation for more details on the underlying call function.
Close the current window.
View the WebDriver API documentation for more details on the underlying close function.
Return all WebDriver logs that have accumulated since the last call to this function. The required type variable
filters the results by type.
Based on informal testing, it appears that only "browser" and "driver" are supported by the underlying function.
Execute script on the client side with var_args arguments. A final implicit callback argument is provided, the
callback must be executed before a result will be returned. Fires the onExecuteAsyncScript event when the script has
finished executing. Returns a promise that is resolved once the supplied callback is called. The results will contain
the return value passed to the callback.
View the WebDriver API documentation for more details on the underlying executeAsyncScript function.
Execute script immediately with var_args arguments. Fires the onExecuteScript event when the script has
finished executing. Returns a promise that is resolved once the script is executed. The results will contain the
return value of script.
View the WebDriver API documentation for more details on the underlying executeScript function.
Find and return a particular element using locator, which is typically defined using fluid.webdriver.By (see below).
Fires the onFindElement event when the search is complete. Returns a promise that is resolved once the search is
complete. If an element is found, the element itself will be the result. If there are multiple elements, the result
will be the first matching element. If there are no matching elements, the onError event will be fired.
View the WebDriver API documentation for more details on the underlying findElement function.
Find and return a particular element using locator, which is typically defined using fluid.webdriver.By (see below).
Fires the onFindElements event when the search is complete. Returns a promise that is resolved once the search is
complete. The results contain an array of matching elements, or an empty array if no matching elements are found.
View the WebDriver API documentation for more details on the underlying findElements function.
Instructs the browser to navigate to url. Fires the onGetComplete event when the page has finished loading. Returns
a promise that is resolved once the page has finished loading.
View the WebDriver API documentation for more details on the underlying get function.
This function is not used or tested in this module, but is exposed for future developers to explore and extend as desired.
View the WebDriver API documentation for more details on the underlying getAllWindowHandles function.
Retrieve the current capabilities of the browser window. The event onGetCapabilitiesComplete is fired with the value.
Returns a promise that will be resolved with the current capabilties.
View the WebDriver API documentation for more details on the underlying getCapabilities function.
Retrieve the current effective URL of the browser window. The event onGetCurrentUrlComplete is fired with the value.
Returns a promise that will be resolved with the current URL.
View the WebDriver API documentation for more details on the underlying getCurrentUrl function.
Retrieve the current browser window's page source. The event 'onGetPageSource' is fired with the result of this call. Returns a promise that will be resolved with the value of the page source.
View the WebDriver API documentation for more details on the underlying getPageSource function.
This function is not used or tested in this module, but is exposed for future developers to explore and extend as desired.
View the WebDriver API documentation for more details on the underlying getSession function.
Retrieve the current browser window's title. The event 'onGetTitle' is fired with the result of this call. Returns a promise that will be resolved with the value of the page title.
View the WebDriver API documentation for more details on the underlying getTitle function.
This function is not used or tested in this module, but is exposed for future developers to explore and extend as desired.
View the WebDriver API documentation for more details on the underlying getWindowHandle function.
Confirm whether an element that matches locator exists. locator is typically defined using fluid.webdriver.By
(see below). The event onIsElementPresentComplete is fired with the result. Returns a promise that will be resolved
with the result.
View the WebDriver API documentation for more details on the underlying isElementPresent function.
This function is not used or tested in this module, but is exposed for future developers to explore and extend as desired.
View the WebDriver API documentation for more details on the underlying manage function.
Retrieves an navigate instance that can be used to navigate using the current browser . This value is
passed as the result of onNavigateComplete. Returns a promise that is resolved with the same value.
Typically you will use {that}.navigateHelper rather than calling this directly.
View the WebDriver API documentation for more details on the underlying navigate function.
A convenience helper to make it easier to work with navigate. Instantiates a navigator and then executes its fnName
function with args arguments. Fires onNavigateHelperComplete when navigation is completed. Returns a promise that
is resolved when navigation is completed.
See the WebDriver API documentation for details regarding the supported navigation functions and their arguments.
Instruct the current browser to quit. Fires the event onQuitComplete once the browser has finished shutting down.
Returns a promise that is resolved when the browser has finished shutting down.
View the WebDriver API documentation for more details on the underlying quit function.
This function is not used or tested in this module, but is exposed for future developers to explore and extend as desired.
View the WebDriver API documentation for more details on the underlying schedule function.
This function is not used or tested in this module, but is exposed for future developers to explore and extend as desired.
View the WebDriver API documentation for more details on the underlying setFileDetector function.
Instructs the browser to sleep for ms milliseconds. Fires an onSleepComplete event once the browser has slept for
the specified time. Returns a promise that will be resolved once the browser has slept for the specified time.
View the WebDriver API documentation for more details on the underlying sleep function.
This function is not used or tested in this module, but is exposed for future developers to explore and extend as desired.
View the WebDriver API documentation for more details on the underlying switchTo function.
Take a screenshot of the current browser window. The onTakeScreenshotComplete event is fired with the results.
Returns a promise that will be resolved with the results once the screenshot has been taken. The results in this case
are base64 encoded binary data in PNG format.
View the WebDriver API documentation for more details on the underlying takeScreenshot function.
This function is not used or tested in this module, but is exposed for future developers to explore and extend as desired.
View the WebDriver API documentation for more details on the underlying touchActions function.
Instruct the browser to wait until condition is true. condition is typically defined using fluid.webdriver.until
(see below). Fires onWaitComplete when the condition has been met, or onError if the request times out. Returns
a promise that will be resolved when the condition is true. The optional opt_timeout parameter represents the number
of milliseconds to wait for condition before timing out. The optional opt_message parameter is a custom message
that will be used when rejecting the promise. This message will appear near the beginning of the message element of
a Javascript Error.
Note that Javascript Error objects cannot be serialized properly using JSON.stringify. To see the error details,
you'll need to either inspect individual elements (such as message), or to call the Error object's toString method.
Here are sample sequence steps with a comment regarding the probably value.
{
func: "{testEnvironment}.webdriver.wait",
args: [fluid.webdriver.until.alertIsPresent(), 500, "Custom message."]
},
{
listener: "console.log",
args: ["{arguments}.message"
}
/*
Outputs something like:
Error: Custom message.
Wait timed out after 2264ms
*/Note that the leading text "Error: " and the trailing details are not configurable, and will always appear in the message.
View the WebDriver API documentation for more details on the underlying wait function.
In addition to the "wrapped" events mentioned above, this component has a unique event (onError that is fired
whenever any of the promises created by a "wrapped" function encounter an error.
The By object provided by the webdriver library is available under this global name. It is used to construct
selectors for use with invokers like findElement (see above).
View the WebDriver API documentation for more details on the By object.
The until object provided by the webdriver library is available under this global name. It is used to construct
conditions for use with the wait invoker (see above).
View the WebDriver API documentation for more details on the until object.
The underlying WebDriver driver allows you to override two key pieces of information using environment variables:
- The browser to be used.
- The external Selenium server to be used (if any).
By default, this grade uses Chrome to run tests. You can change this by passing options.browser in your component
options (see below), or you can set the SELENIUM_BROWSER
environment variable to one of the supported browsers
(in lowercase form). Note that this option is not compatible with the use of the multi-browser harness,
if you are using that, you should use the BROWSERS environment variable instead.
By default, this package will work without a Selenium instance. If you have your own Selenium server, you can use it
by setting the SELENIUM_REMOTE_URL environment variable to the URL of your server.
In addition, this package supports a HEADLESS environment variable, which can be used to run supported browsers
(currently only Chrome) in "headless" mode.
The WebDriver API does not provide any mechanism to trap HTTP response codes or errors, for example that result when trying to open a page that doesn't exist. However, it also does not interfere with the browser's continued operation following an error. So, you can (for example) confirm that your site provides an error message when a page isn't found, but you couldn't confirm that it sends the correct status code.