Marionette.Client Class
Initializes client.You must create and initialize a driver and pass it into the client before using the client itself.
Marionette JS Client supports both async and sync modes... The documentation reflects the sync modes but you can also pass a callback into most calls for the sync version. If you attempt to use callbacks with a sync driver they will be called but run synchronously.
// all drivers conform to this api
// var Marionette = require('marionette-client');
var driver = new Marionette.Drivers.Tcp({});
var client;
driver.connect(function(err) {
if (err) {
// handle error case...
}
client = new Marionette.Client(driver, {
// optional default callback can be used to implement
// a generator interface or other non-callback based api.
defaultCallback: function(err, result) {
console.log('CALLBACK GOT:', err, result);
}
});
// by default commands run in a queue.
// assuming there is not a fatal error each command
// will execute sequentially.
client.startSession(function () {
client.goUrl('http://google.com')
.executeScript(function() {
alert(document.title);
})
.deleteSession();
});
});// alternatively there is a lazy api which test runners can use.
var client = new Client(null, { lazy: true });
// accepts same arguments as normal constructor calls. client.resetWithDriver(driver, {});
Constructor
Marionette.Client
-
driver -
options
Parameters:
-
driverMarionette.Drivers.Abstractfully initialized client.
-
optionsObjectoptions for driver.
Item Index
Methods
- _convertFunction
- _executeScript
- _findElement
- _getActorId
- _newSession
- _prepareArguments
- _sendCommand
- _transformResultValue
- addHook
- deleteSession
- executeAsyncScript
- executeJsScript
- executeScript
- findElement
- findElements
- getLogs
- getUrl
- getWindow
- getWindows
- getWindowType
- goBack
- goForward
- goUrl
- importScript
- log
- pageSource
- plugin
- refresh
- runHook
- scope
- screenshot
- send
- sessionCapabilities
- setContext
- setScriptTimeout
- setSearchTimeout
- startSession
- switchToFrame
- switchToWindow
- title
- waitFor
Methods
_convertFunction
-
fn
Converts an function into a string that can be sent to marionette.
Returns:
function string.
_executeScript
-
options -
callback
Executes a remote string of javascript. the javascript string will be wrapped in a function by marionette.
Parameters:
Returns:
self.
_findElement
-
type -
query -
method -
elementId -
callback
Finds element.
_getActorId
-
callback
Finds the actor for this instance.
Parameters:
-
callbackFunctionexecuted when response is sent.
_newSession
-
callback -
desired
Starts a remote session.
_prepareArguments
-
arguments
Prepares arguments for script commands. Formats Marionette.Element's sod marionette can use them in script commands.
Parameters:
-
argumentsArraylist of args for wrapped function.
Returns:
processed arguments.
_sendCommand
-
command -
responseKey -
callback
Sends request and formats response.
_transformResultValue
-
value
Processes result of command if an {'ELEMENT': 'uuid'} combination is returned a Marionette.Element instance will be created and returned.
Parameters:
-
valueObjectoriginal result from server.
Returns:
processed result.
addHook
-
type -
handler
Adds a hook to the stack. Hooks run in serial order until all hooks complete. Execution of hooks halts on first error.
client.addHook('sessionStart', function(done) { // this is the client this.executeScript(function() {}, done); });
deleteSession
-
callback
Destroys current session.
Parameters:
-
callbackFunctionexecuted when session is destroyed.
executeAsyncScript
-
script -
[args] -
callback
Script is wrapped in a function and will be executed asynchronously.
NOTE: that setScriptTimeout must be set prior to using this method as the timeout defaults to zero.
function remote () {
window.addEventListener('someevent', function() {
// special method to notify that async script is complete.
marionetteScriptFinished({ fromRemote: true })
});
}
client.executeAsyncScript(remote, function(err, value) {
// value === { fromRemote: true }
});Parameters:
Returns:
self.
executeJsScript
-
script -
[args] -
[timeout] -
callback
Executes a remote script will block. Script is not wrapped in a function.
Parameters:
Returns:
self.
executeScript
-
script -
[args] -
callback
Executes a remote script will block. Script is wrapped in a function.
// its is very important to remember that the contents of this
// method are "stringified" (Function#toString) and sent over the
// wire to execute on the device. So things like scope will not be
// the same. If you need to pass other information in arguments
// option should be used.
// assume that this element is the result of findElement
var element;
var config = {
event: 'magicCustomEvent',
detail: { foo: true }
};
var remoteArgs = [element, details];
// unlike other callbacks this one will execute _on device_
function remoteFn(element, details) {
// element in this context is a real dom element now.
var event = document.createEvent('CustomEvent');
event.initCustomEvent(config.event, true, true, event.detail);
element.dispatchEvent(event);
return { success: true };
}
client.executeJsScript(remoteFn, remoteArgs, function(err, value) {
// value => { success: true }
});Parameters:
Returns:
self.
findElement
-
query -
method -
elementId -
callback
Attempts to find a dom element (via css selector, xpath, etc...) "elements" returned are instances of Marionette.Element
// with default options
client.findElement('#css-selector', function(err, element) {
if (err) {
// handle case where element was not found
}
// see element interface for all methods, etc..
element.click(function() {
});
});findElements
-
query -
method -
elementId -
callback
Finds multiple elements in the dom. This method has the same api signature as FindElement the only difference is where findElement returns a single element this method will return an array of elements in the callback.
// find all links in the document
client.findElements('a[href]', function(err, element) {
});getLogs
-
callback
Retrieves all logs on the marionette server. The response from marionette is an array of arrays.
device.getLogs(function(err, logs){
//logs => [
[
'msg',
'level',
'Fri Apr 27 2012 11:00:32 GMT-0700 (PDT)'
]
]
});Parameters:
-
callbackFunctionreceive an array of logs.
getUrl
-
callback
Gets url location for device.
Parameters:
-
callbackFunctionreceives url.
getWindow
-
[callback]
Callback will receive the id of the current window.
Parameters:
-
[callback]Function optionalexecuted with id of current window.
Returns:
self.
getWindows
-
[callback]
Callback will receive an array of window ids.
Parameters:
-
[callback]Function optionalexecutes with an array of ids.
getWindowType
-
[callback]
Returns the type of current window.
Parameters:
-
[callback]Function optionalexecutes with window type.
Returns:
self.
goForward
-
callback
Drives window forward.
Parameters:
-
callbackFunctionreceives boolean.
goUrl
-
url -
callback
Drives browser to a url.
importScript
-
script -
callback
Imports a script into the marionette context for the duration of the session.
Good for prototyping new marionette commands.
log
-
message -
level -
callback
Logs a message on marionette server.
Parameters:
Returns:
self.
pageSource
-
[callback]
Returns a string representation of the DOM in current page.
Parameters:
-
[callback]Function optionaloptional receives the page source.
Returns:
self.
plugin
-
name -
plugin -
[optional]
Adds a plugin to the client instance.
// add imaginary forms plugin
client.plugin('forms', moduleForForms, { options: true });
client.forms.fill();
// tie into common plugin interface without exposing a new api.
client.plugin(null, module, {});
// chaining
client
.plugin('forms', require('form-module'))
.plguin('apps', require('apps-module'))
.plugin('other', require('...'));
client.forms.fill(...);
client.apps.launch(...);refresh
-
callback
Refreshes current window on device.
Parameters:
-
callbackFunctionboolean success.
Returns:
self.
runHook
-
type -
callback
Run all hooks of a given type. Hooks may be added as the result of running other hooks which could potentially result in an infinite loop without stack overflow...
this.runHook('startSession', function(err) {
// do something with error if there is one.
});scope
-
options
Creates a client which has a fixed window, frame, scriptTimeout and searchTimeout.
client.setSearchTimeout(1000).setContext('content');
var timeout = client.scope({ searchTimeout: 250 });
var chrome = client.scope({ context: 'chrome' });
// executed with 250 timeout
timeout.findElement('...');
// executes in chrome context.
chrome.executeScript();
// executed in content with search timeout of 1000
client.findElement('...');Parameters:
-
optionsObjectfor scopped client.
Returns:
scoped client instance.
screenshot
-
[options] -
callback
Creates a base64-encoded screenshot of the element, or the current frame if no element is specified.
client.screenshot({
element: elementToScreenshot
});Options:
* (Element) element: The element to take a screenshot of. If
unspecified, will take a screenshot of the current frame
* (Array) highlights: A list of element objects to draw a red box
around in the returned screenshot.send
-
cmd -
cb
Sends a command to the server. Adds additional information like actor and session to command if not present.
sessionCapabilities
-
[callback]
Returns the capabilities of the current session.
Parameters:
-
[callback]Function optionalwith capabilities of current session.
Returns:
A JSON representing capabilities.
setContext
-
context -
callback
Switches context of window. The current context can be found with .context.
// default context client.context === 'content';
client.setContext('chrome', function() { // .. wait for switch });
client.context === 'chrome';
setScriptTimeout
-
timeout -
callback
Sets the script timeout
Parameters:
-
timeoutNumericmax time in ms.
-
callbackFunctionexecuted with boolean status.
Returns:
self.
setSearchTimeout
-
timeout -
callback
Sets a timeout for the find methods.
When searching for an element using either Marionette.findElement or Marionette.findElements, the method will continue trying to locate the element for up to timeout ms.
This can be useful if, for example, the element you’re looking for might not exist immediately, because it belongs to a page which is currently being loaded.
Parameters:
-
timeoutNumericmax time in ms.
-
callbackFunctionexecuted with boolean status.
Returns:
self.
startSession
-
callback -
desired
Finds actor and creates connection to marionette. This is a combination of calling getMarionetteId and then newSession.
switchToFrame
-
[id] -
[options] -
callback
Switches context of marionette to specific iframe.
Parameters:
-
[id]String | Marionette.Element optionaliframe id or element. If you call this function without an argument, it will switch to the top-level frame.
-
[options]Object optionaloptions to be mixed in the command parameters.
-
[focus]Boolean optionalIf 'true', will switch the focus to the frame.
-
-
callbackFunctioncalled with boolean.
switchToWindow
-
id -
callback
Switches context of marionette to specific window.
title
-
[callback]
Returns the title of current window.
Parameters:
-
[callback]Function optionaloptional receives title.
Returns:
self.
waitFor
-
test -
[options] -
[callback]
Utility for waiting for a success condition to be met.
// sync style
client.waitFor(function() {
return element.displayed();
});
// async style
client.waitFor(function(done) {
element.displayed(done);
});Options:
* (Number) interval: time between running test
* (Number) timeout: maximum wallclock time before failing test.