Namespace: evaluate

evaluate

Source:

Classes

this.Sandboxes

Methods

(static) fromJSON(obj, seenElsopt, windowopt) → {Object}

Convert any web elements in arbitrary objects to DOM elements by looking them up in the seen element store.

Parameters:
Name Type Attributes Description
obj Object

Arbitrary object containing web elements.
seenEls element.Store <optional>

Known element store to look up web elements from. If undefined, the web element references are returned instead.
window WindowProxy <optional>

Current browsing context, if seenEls is provided.
Source:
Throws:

  • If seenEls is given and the web element reference has not been seen before.

    Type
    NoSuchElementError

  • If seenEls is given and the element has gone stale, indicating it is no longer attached to the DOM, or its node document is no longer the active document.

    Type
    StaleElementReferenceError
Returns:

Same object as provided by obj with the web elements replaced by DOM elements.

Type
Object

(static) isDead(obj, prop) → {boolean}

Cu.isDeadWrapper does not return true for a dead sandbox that was assosciated with and extension popup. This provides a way to still test for a dead object.

Parameters:
Name Type Description
obj Object

A potentially dead object.
prop string

Name of a property on the object.
Source:
Returns:

True if obj is dead, false otherwise.

Type
boolean

(static) sandbox(sb, script, argsopt, asyncopt, debugopt, fileopt, lineopt, sandboxNameopt, timeoutopt) → {Promise}

Evaluate a script in given sandbox.

If the option var>directInject is not specified, the script will be executed as a function with the args argument applied.

The arguments provided by the args argument are exposed through the arguments object available in the script context, and if the script is executed asynchronously with the async option, an additional last argument that is synonymous to the marionetteScriptFinished global is appended, and can be accessed through arguments[arguments.length - 1].

The timeout option specifies the duration for how long the script should be allowed to run before it is interrupted and aborted. An interrupted script will cause a ScriptTimeoutError to occur.

The async option indicates that the script will not return until the marionetteScriptFinished global callback is invoked, which is analogous to the last argument of the arguments object.

The option directInject causes the script to be evaluated without being wrapped in a function and the provided arguments will be disregarded. This will cause such things as root scope return statements to throw errors because they are not used inside a function.

The file option is used in error messages to provide information on the origin script file in the local end.

The line option is used in error messages, along with filename, to provide the line number in the origin script file on the local end.

Parameters:
Name Type Attributes Default Description
sb nsISandbox

Sandbox the script will be evaluted in.
script string

Script to evaluate.
args Array.<?> <optional>

A sequence of arguments to call the script with.
async boolean <optional>
 false

async Indicates if the script should return immediately or wait for the callback to be invoked before returning.
debug boolean <optional>
 false

debug Attaches an onerror event listener.
file string <optional>
 "dummy file"

file File location of the program in the client.
line number <optional>
 0

line Line number of th eprogram in the client.
sandboxName string <optional>

Name of the sandbox. Elevated system privileges, equivalent to chrome space, will be given if it is system.
timeout number <optional>
 DEFAULT_TIMEOUT

timeout Duration in milliseconds before interrupting the script.
Source:
Throws:

  • If an Error was thrown whilst evaluating the script.

    Type
    JavaScriptError

  • If the script was interrupted due to script timeout.

    Type
    ScriptTimeoutError
Returns:

A promise that when resolved will give you the return value from the script. Note that the return value requires serialisation before it can be sent to the client.

Type
Promise

(static) toJSON(obj, seenEls) → {Object}

Marshal arbitrary objects to JSON-safe primitives that can be transported over the Marionette protocol.

The marshaling rules are as follows:

  • Primitives are returned as is.
  • Collections, such as Array, NodeList, HTMLCollection et al. are expanded to arrays and then recursed.
  • Elements that are not known web elements are added to the seenEls element store. Once known, the elements' associated web element representation is returned.
  • Objects with custom JSON representations, i.e. if they have a callable toJSON function, are returned verbatim. This means their internal integrity are not checked. Be careful.
  • Other arbitrary objects are first tested for cyclic references and then recursed into.
Parameters:
Name Type Description
obj Object

Object to be marshaled.
seenEls element.Store

Element store to use for lookup of web element references.
Source:
Throws:

If an object contains cyclic references.

Type
JavaScriptError
Returns:

Same object as provided by obj with the elements replaced by web elements.

Type
Object