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. For ElementIdentifiers a new entry in the seen element reference store gets added when running in the parent process, otherwise ContentDOMReference is used to retrieve the DOM node.

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

  • seenEls (element.Store|element.ReferenceStore) – Known element store to look up web elements from. If seenEls is an instance of element.ReferenceStore, return WebElement. If seenEls is an instance of element.Store, return Element. If seenEls is undefined the Element from the ContentDOMReference cache is returned when executed in the child process, in the parent process the WebElement is passed-through.

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

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

  • StaleElementReferenceError – If seenEls is an element.ReferenceStore or element.Store 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 or across processes.

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, or the ContentDOMReference registry. Once known, the elements’ associated web element representation is returned.

  • WebElements are transformed to the corresponding ElementIdentifier for use in the content process, if an element.ReferenceStore is provided.

  • 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.ReferenceStore) – 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.