evaluate module

class evaluate()
evaluate.fromJSON(obj, seenEls, win)

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

Arguments
  • obj (Object) – Arbitrary object containing web elements.

  • seenEls (element.Store) – Known element store to look up web elements from. If undefined, the web element references are returned instead.

  • win (WindowProxy) – Current browsing context, if seenEls is provided.

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

  • StaleElementReferenceError – 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.

Returns

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

evaluate.isCyclic(value)

Tests if an arbitrary object is cyclic.

Element prototypes are by definition acyclic, even when they contain cyclic references. This is because evaluate.toJSON ensures they are marshaled as web elements.

Arguments
  • value (*) – Object to test for cyclical references.

Returns

boolean – True if object is cyclic, false otherwise.

evaluate.isDead(obj, prop)

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.

Arguments
  • obj (Object) – A potentially dead object.

  • prop (string) – Name of a property on the object.

Returns

boolean – True if <var>obj</var> is dead, false otherwise.

evaluate.sandbox(sb, script, args, async=false, file="\"dummy file\"", line=0, timeout=DEFAULT_TIMEOUT)

Evaluate a script in given sandbox.

The the provided script will be wrapped in an anonymous 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 name resolve 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 {@link ScriptTimeoutError} to occur.

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

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.

Arguments
  • sb (nsISandbox) – Sandbox the script will be evaluted in.

  • script (string) – Script to evaluate.

  • args (Array.<?>) – A sequence of arguments to call the script with.

  • async (boolean) – async Indicates if the script should return immediately or wait for the callback to be invoked before returning.

  • file (string) – file File location of the program in the client.

  • line (number) – line Line number of th eprogram in the client.

  • timeout (number) – timeout Duration in milliseconds before interrupting the script.

Throws
Returns

Promise – 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.

evaluate.this.Sandboxes
evaluate.toJSON(obj, seenEls)

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.

Arguments
  • obj (Object) – Object to be marshaled.

  • seenEls (element.Store) – Element store to use for lookup of web element references.

Throws

JavaScriptError – If an object contains cyclic references.

Returns

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