Marionette JS Client

API Docs for: 0.5.0
Show:

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:

Methods

_convertFunction

(
  • fn
)
String private

Converts an function into a string that can be sent to marionette.

Parameters:

Returns:

String:

function string.

_executeScript

(
  • options
  • callback
)
Object private

Executes a remote string of javascript. the javascript string will be wrapped in a function by marionette.

Parameters:

  • options Object

    objects of execute script.

    • type String

      command type like 'executeScript'.

    • value String

      javascript string.

    • args String

      arguments for script.

    • timeout Boolean

      timeout only used in 'executeJSScript'.

  • callback Function

    executes when script finishes.

Returns:

Object:

self.

_findElement

(
  • type
  • query
  • method
  • elementId
  • callback
)
private

Finds element.

Parameters:

  • type String

    type of command to send like 'findElement'.

  • query String

    search query.

  • method String

    search method.

  • elementId String

    id of element to search within.

  • callback Function

    executes with element uuid(s).

_getActorId

(
  • callback
)
private

Finds the actor for this instance.

Parameters:

  • callback Function

    executed when response is sent.

_newSession

(
  • callback
)
private

Starts a remote session.

Parameters:

_prepareArguments

(
  • arguments
)
Array private

Prepares arguments for script commands. Formats Marionette.Element's sod marionette can use them in script commands.

Parameters:

  • arguments Array

    list of args for wrapped function.

Returns:

Array:

processed arguments.

_sendCommand

(
  • command
  • responseKey
  • callback
)
private chainable

Sends request and formats response.

Parameters:

  • command Object

    marionette command.

  • responseKey String

    the part of the response to pass \ unto the callback.

  • callback Object

    wrapped callback.

_transformResultValue

(
  • value
)
Object | Marionette.Element private

Processes result of command if an {'ELEMENT': 'uuid'} combination is returned a Marionette.Element instance will be created and returned.

Parameters:

  • value Object

    original result from server.

Returns:

Object | Marionette.Element:

processed result.

addHook

(
  • type
  • handler
)
chainable

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); });

Parameters:

  • type String

    name of hook.

  • handler Function

    for hook must take a single argument (see above).

deleteSession

(
  • callback
)
chainable

Destroys current session.

Parameters:

  • callback Function

    executed when session is destroyed.

executeAsyncScript

(
  • script
  • [args]
  • callback
)
Object chainable

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:

  • script String

    script to run.

  • [args] Array optional

    optional args for script.

  • callback Function

    will receive result of the return \ call in the script if there is one.

Returns:

Object:

self.

executeJsScript

(
  • script
  • [args]
  • [timeout]
  • callback
)
Object chainable

Executes a remote script will block. Script is not wrapped in a function.

Parameters:

  • script String

    script to run.

  • [args] Array optional

    optional args for script.

  • [timeout] Array optional

    optional args for timeout.

  • callback Function

    will receive result of the return \ call in the script if there is one.

Returns:

Object:

self.

executeScript

(
  • script
  • [args]
  • callback
)
Object chainable

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:

  • script String

    script to run.

  • [args] Array optional

    optional args for script.

  • callback Function

    will receive result of the return \ call in the script if there is one.

Returns:

Object:

self.

findElement

(
  • query
  • method
  • elementId
  • callback
)
chainable

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() {

   });
});

Parameters:

  • query String

    search query.

  • method String

    search method.

  • elementId String

    id of element to search within.

  • callback Function

    executes with element uuid.

findElements

(
  • query
  • method
  • elementId
  • callback
)
chainable

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) {
});

Parameters:

  • query String

    search query.

  • method String

    search method.

  • elementId String

    id of element to search within.

  • callback Function

    executes with an array of element uuids.

getLogs

(
  • callback
)
chainable

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:

  • callback Function

    receive an array of logs.

getUrl

(
  • callback
)
chainable

Gets url location for device.

Parameters:

getWindow

(
  • [callback]
)
Object chainable

Callback will receive the id of the current window.

Parameters:

  • [callback] Function optional

    executed with id of current window.

Returns:

Object:

self.

getWindows

(
  • [callback]
)
chainable

Callback will receive an array of window ids.

Parameters:

  • [callback] Function optional

    executes with an array of ids.

getWindowType

(
  • [callback]
)
Object

Returns the type of current window.

Parameters:

  • [callback] Function optional

    executes with window type.

Returns:

Object:

self.

goBack

(
  • callback
)
chainable

Drives window back.

Parameters:

goForward

(
  • callback
)
chainable

Drives window forward.

Parameters:

goUrl

(
  • url
  • callback
)
chainable

Drives browser to a url.

Parameters:

  • url String

    location.

  • callback Function

    executes when finished driving browser to url.

importScript

(
  • script
  • callback
)
chainable

Imports a script into the marionette context for the duration of the session.

Good for prototyping new marionette commands.

Parameters:

  • script String

    javascript string blob.

  • callback Function

    called with boolean.

log

(
  • message
  • level
  • callback
)
Object chainable

Logs a message on marionette server.

Parameters:

Returns:

Object:

self.

pageSource

(
  • [callback]
)
Object

Returns a string representation of the DOM in current page.

Parameters:

  • [callback] Function optional

    optional receives the page source.

Returns:

Object:

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(...);

Parameters:

  • name String | Null

    to expose plugin on in the client.

  • plugin Function | Object

    function/module.

  • [optional] Object optional

    options to pass to plugin.

refresh

(
  • callback
)
Object

Refreshes current window on device.

Parameters:

Returns:

Object:

self.

runHook

(
  • type
  • callback
)
protected

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.
});

Parameters:

  • type String

    of hook to run.

  • callback Function

    to run once hooks are done.

scope

(
  • options
)
Marionette.Client

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:

  • options Object

    for scopped client.

Returns:

Marionette.Client:

scoped client instance.

screenshot

(
  • [options]
  • callback
)
chainable

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

Parameters:

send

(
  • cmd
  • cb
)
chainable

Sends a command to the server. Adds additional information like actor and session to command if not present.

Parameters:

  • cmd Object

    to be sent over the wire.

  • cb Function

    executed when response is sent.

sessionCapabilities

(
  • [callback]
)
Object

Returns the capabilities of the current session.

Parameters:

  • [callback] Function optional

    with capabilities of current session.

Returns:

Object:

A JSON representing capabilities.

setContext

(
  • context
  • callback
)
chainable

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';

Parameters:

  • context String

    either: 'chome' or 'content'.

  • callback Function

    receives boolean.

setScriptTimeout

(
  • timeout
  • callback
)
Object chainable

Sets the script timeout

Parameters:

  • timeout Numeric

    max time in ms.

  • callback Function

    executed with boolean status.

Returns:

Object:

self.

setSearchTimeout

(
  • timeout
  • callback
)
Object chainable

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:

  • timeout Numeric

    max time in ms.

  • callback Function

    executed with boolean status.

Returns:

Object:

self.

startSession

(
  • callback
)

Finds actor and creates connection to marionette. This is a combination of calling getMarionetteId and then newSession.

Parameters:

  • callback Function

    executed when session is started.

switchToFrame

(
  • id
  • callback
)
chainable

Switches context of marionette to specific iframe.

Parameters:

switchToWindow

(
  • id
  • callback
)
chainable

Switches context of marionette to specific window.

Parameters:

  • id String

    window id you can find these with getWindow(s).

  • callback Function

    called with boolean.

title

(
  • [callback]
)
Object

Returns the title of current window.

Parameters:

  • [callback] Function optional

    optional receives title.

Returns:

Object:

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.

Parameters:

  • test Function

    to execute.

  • [options] Object optional

    for timeout see above.

    • [interval] Number optional

      time between running test.

    • [timeout] Number optional

      maximum wallclock time before failing test.

  • [callback] Function optional

    optional callback.

Properties

_hooks

Object private

Object of hoooks.

{ hookName: [hook1, hook2] }

actor

String

Actor id for instance

CHROME

String

Constant for chrome context.

CONTENT

String

Constant for content context.

session

String

Session id for instance.