Home

Awesome

eshost

Travis Build Status Appveyor Build Status

Execute ECMAScript code uniformly across any ECMAScript host environment. See also eshost-cli for an easy way to use this library from the command line.

Using eshost, you can create an agent (eg. a web browser or a command-line ECMAScript host) and evaluate scripts within that agent. Code running within the agent has access to the eshost runtime API which enables code to evaluate scripts, create new realms, handle errors, and so forth all without worrying about the host-specific mechanisms for these capabilities are.

eshost consists of a wrapper around the various ways of executing a host and processing its output (called an Agent) and a runtime library for host-agnostic scripts to use.

Installation

npm install eshost

Supported Hosts

HostNameTypeSupported PlatformsDownloadNotes
ch¹ChakraCoreCLIAnyDownload or buildChakra console host.
d8¹V8CLIAnyBuild from sourceV8 console host. Errors are reported on stdout. Use $262.getGlobal and $262.setGlobal to get and set properties of global objects in other realms.
engine262Engine262CLIAnyBuild from sourceAn implementation of ECMA-262 in JavaScript.
graaljsGraalJSCLIAnyDownload
jsshell¹SpiderMonkeyCLIAnyDownloadSpiderMonkey console host.
jsc¹JavaScriptCoreCLIMac²Build from source³
serenity-jsSerenity LibJSCLIAnyBuild from source
nashornNashornCLIAnyBuild from source
nodeNode.jsCLIAnyhttps://nodejs.orgActive LTS versions only
qjs<sup>4</sup>QuickJSCLIAnyBuild from source
xsModdable XSCLIAnyBuild from source
chromeGoogle ChromeBrowserAnyRequires ChromeDriver in your path.
edgeMicrosoft EdgeBrowserWindowsErrors reported from Microsoft Edge are all of type Error. Requires Microsoft WebDriver in your path.
firefoxMozilla FirefoxBrowserAnyRequires GeckoDriver in your path (possibly renamed to wires).
safariApple SafariBrowserMacRequires SafariDriver browser extension.

Installing Engines

esvu or jsvu are the recommended tools for maintaining JavaScript engines for testing purposes. Take a look at the esvu supported engines or jsvu supported engines for more information.

Example Usage

const eshost = require('eshost');
const agent = await eshost.createAgent('d8', { hostPath: 'path/to/d8.exe' });
const result = await agent.evalScript(`
  print(1+1);
`);
console.log(result.stdout);

Documentation

eshost

The eshost object is the main export of the "eshost" module.

eshost.supportedHosts

An array of supported host types.

eshost.createAgent(type: string, options = {}): Agent

Creates an instance of a host agent for a particular host type. See the table above for supported host types.

Agent

initialize(): Promise<void>

Initializes the host and returns a promise that is resolved once the host is initialized. Command line hosts have no initialization as a new process is started for each execution.

This is called for you if you use the createAgent factory.

evalScript(code, options = {}): Promise<Result>

Executes code in the host using the Script goal symbol. Returns a promise for a result object.

evalScript(record, options = {}): Promise<Result>

When evalScript receives a Test262File test record, it executes record.contents in the host using the Script goal symbol, unless record.attrs.flags.module === true, in which case it will execute record.contents in the host using the Module goal symbol. Returns a promise for a result object.

By default, a script will run in eshost until the realm is destroyed. For most command-line hosts, this is done automatically when the script execution queues are empty. However, browsers will remain open waiting for more code to become available. Therefore, eshost will automatically append $262.destroy() to the end of your scripts. This behavior is not correct if you are attempting to execute asynchronous code. In such cases, add async: true to the options.

Result Object

An object with the following keys:

PropertyDescription
stdoutAnything printed to stdout (mostly what you print using print).
stderrAnything printed to stderr
errorIf the script threw an error, it will be an error object. Else, it will be null.

The error object is similar to an error object you get in the host itself. Namely, it has the following keys:

PropertyDescription
nameError name (eg. SyntaxError, TypeError, etc.)
messageError message, if available.
stackAn array of stack frames, if available.

stop(): Promise<void>

Stops the currently executing script. For a console host, this simply kills the child process. For browser hosts, it will kill the current window and create a new one.

destroy(): Promise<void>

Destroys the agent, closing any of its associated resources (eg. browser windows, child processes, etc.).

destroy(): Promise<void>

Tears down the agent. For browsers, this will close the browser window. For most CLI/Shell hosts, this is a no-op.

Runtime Library

print(str)

Prints str to stdout.

$262.global

A reference to the global object.

$262.createRealm(options)

Creates a new realm, returning that realm's runtime library ($).

For example, creating two nested realms:

$sub = $262.createRealm();
$subsub = $sub.createRealm();

You can also use a destroy callback that gets called when the code inside the realm calls $262.destroy(). For example:

$sub = $262.createRealm({
  destroy() {
    print('destroyed!')
  }
});

$sub.evalScript('$262.destroy()'); // prints "destroyed!"

$262.evalScript(code)

Creates a new script and evals code in that realm. If an error is thrown, it will be passed to the onError callback.

Scripts are different from eval in that lexical bindings go into the global lexical contour rather than being scoped to the eval.

$262.destroy()

Destroys the realm. Note that in some hosts, $262.destroy may not actually stop executing code in the realm or even destroy the realm.

$262.getGlobal(name)

Gets a global property name.

$262.setGlobal(name, value)

Sets a global property name to value.

Running the tests

This project's tests can be executed with the following command:

npm test

The above command will cause tests to be run against all supported hosts. Executables for each host must be available on the system's PATH environment variable.

One or more hosts may be skipped from the test run by setting corresponding environment variables whose name match the pattern ESHOST_SKIP_*, where * is the capitalized name of the host. For example, in a Unix-like system, the following command executes the project's tests but skips JavaScriptCore and D8 tests:

ESHOST_SKIP_JSC=1 ESHOST_SKIP_D8=1 npm test

Tests for the "remote" agent can be configured to run against any arbitrary Selenium/WebDriver configuration through the specification of the following environment variables: ESHOST_REMOTE_BROWSERNAME, ESHOST_REMOTE_VERSION, ESHOST_REMOTE_PLATFORM. These values are used to define the host's capabilities; see the above documentation of eshost.createAgent for more details. For example, in a Unix-like system, the following command executes the project's tests in a remote instance of the Firefox web browser:

ESHOST_REMOTE_BROWSERNAME=firefox npm test