JSDoc: Namespace: evaluate

# Namespace: evaluate

## evaluate

Source:
  - evaluate.js, line 36

### Classes

this.Sandboxes

### Methods

#### (static) fromJSON(obj, seenEls, win, shadowRoot) → {Object}

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

##### Parameters:

Name | Type | Description
--- | --- | ---
`obj` | Object | Arbitrary object containing web elements.
`seenEls` | element.Store | Element store to use for lookup of web element references.
`win` | Window | Window.
`shadowRoot` | ShadowRoot | Shadow root.

Source:
  - evaluate.js, line 205

##### 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:
  - evaluate.js, line 317

##### 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:
  - evaluate.js, line 104

##### 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}

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

Any DOM elements are converted to web elements by looking them up and/or adding them to the element store provided.

##### Parameters:

Name | Type | Description
--- | --- | ---
`obj` | Object | Object to be marshaled.
`seenEls` | element.Store | Element store to use for lookup of web element references.

Source:
  - evaluate.js, line 260

##### Returns:

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

Type
  Object