You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -10,13 +10,13 @@ Using eshost, you can create an agent (eg. a web browser or a command-line ECMAS
10
10
11
11
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.
12
12
13
-
###Installation
13
+
## Installation
14
14
15
15
```
16
16
npm install eshost
17
17
```
18
18
19
-
###Supported Hosts
19
+
## Supported Hosts
20
20
21
21
| Host | Supported Platforms | Download | Notes |
22
22
|------|---------------------|----------|-------|
@@ -35,11 +35,11 @@ npm install eshost
35
35
* 1: It is possible to build jsc on other platforms, but not supported.
36
36
* 2: Also available on your Mac system at `/System/Library/Frameworks/JavaScriptCore.framework/Versions/A/Resources/jsc`.
Creates an instance of a host agent for a particular host type. See the table above for supported host types.
62
+
63
+
`options`:
64
+
65
+
| Property | Description |
66
+
|-|-|
67
+
|`hostPath`| Path to host to execute. For console hosts, this argument is required. For the specific browser runners, hostPath is optional and if omitted, the location for that browser will be detected automatically. |
68
+
|`hostArguments`| Command line arguments used when invoking your host. Not supported for browser hosts. `hostArguments` is an array of strings as you might pass to Node's spawn API. |
69
+
|`transform`| A function to map the source to some other source before running the result on the underlying host. |
70
+
|`webHost`| for web browser hosts only; URL host name from which to serve browser assets; optional; defaults to `"localhost"`|
71
+
|`webPort`| for web browser hosts only; URL port number from which to serve browser assets; optional; defaults to `1337`|
72
+
|`capabilities`| for `remote` host only; the Selenium/WebDriver capabilities to request for the remote session; all specified attributes will be forwarded to the server; [a listing of available attributes is available in the Selenium project's wiki](https://github.com/SeleniumHQ/selenium/wiki/DesiredCapabilities); the following attributes are required: ` { browserName, platform, version }`|
73
+
|`webdriverServer`| for `remote` host only; URL of the WebDriver server to which commands should be issued |
74
+
58
75
59
-
##### Options
60
76
61
-
***hostPath**: Path to host to execute. For console hosts, this argument is required. For the specific browser runners, hostPath is optional and if omitted, the location for that browser will be detected automatically.
62
-
***hostArguments**: Command line arguments used when invoking your host. Not supported for browser hosts. **hostArguments** is an array of strings as you might pass to Node's spawn API.
63
-
***transform**: A function to map the source to some other source before running the result on the underlying host.
64
-
***webHost**: for web browser hosts only; URL host name from which to serve browser assets; optional; defaults to `"localhost"`
65
-
***webPort**: for web browser hosts only; URL port number from which to serve browser assets; optional; defaults to `1337`
66
-
***capabilities**: for `remote` host only; the Selenium/WebDriver capabilities to request for the remote session; all specified attributes will be forwarded to the server; [a listing of available attributes is available in the Selenium project's wiki](https://github.com/SeleniumHQ/selenium/wiki/DesiredCapabilities); the following attributes are required:
67
-
***capabilities.browserName**
68
-
***capabilities.platform**
69
-
***capabilities.version**
70
-
***webdriverServer**: for `remote` host only; URL of the WebDriver server to which commands should be issued
77
+
### `Agent`
71
78
72
-
### Agent API
73
-
#### initialize(): Promise<void>
79
+
#### `initialize(): Promise<void>`
74
80
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.
75
81
76
82
This is called for you if you use the createAgent factory.
Executes `code` in the host using the _Script_ goal symbol. Returns a promise for a result object.
80
86
81
-
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 `$.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.
When `evalScript` receives a `Test262Stream` 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.
84
90
85
-
* async: True if the test is expected to call `$.destroy()`on the root realm when it's finished. When false, $.destroy() is added for you.
91
+
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 `$.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.
86
92
87
-
#### stop(): Promise<void>
93
+
`options`:
94
+
95
+
| Property | Description | Default Value |
96
+
|-|-|-|
97
+
|`async`| Set to `true` if the test is expected to call `$.destroy()` on the root realm when it's finished. When false, `$.destroy()` is added for you. |`false`|
98
+
99
+
#### `stop(): Promise<void>`
88
100
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.
89
101
90
-
#### destroy(): Promise<void>
102
+
#### `destroy(): Promise<void>`
91
103
Destroys the agent, closing any of its associated resources (eg. browser windows, child processes, etc.).
92
104
93
-
##### Result Object
105
+
##### `Result Object`
94
106
An object with the following keys:
95
107
96
-
* stdout: anything printed to stdout (mostly what you print using `print`).
97
-
* stderr: anything printed to stderr
98
-
* error: if the script threw an error, it will be an error object. Else, it will be null.
108
+
| Property | Description |
109
+
|-|-|
110
+
|`stdout`| Anything printed to stdout (mostly what you print using `print`). |
111
+
|`stderr`| Anything printed to stderr |
112
+
|`error`| If the script threw an error, it will be an error object. Else, it will be null. |
113
+
99
114
100
-
The error object is similar to the error object you get in the host itself. Namely, it has the following keys:
115
+
The `error` object is similar to an error object you get in the host itself. Namely, it has the following keys:
101
116
102
-
* name: Error name (eg. SyntaxError, TypeError, etc.)
103
-
* message: Error message
104
-
* stack: An array of stack frames.
117
+
| Property | Description |
118
+
|-|-|
119
+
|`name`| Error name (eg. SyntaxError, TypeError, etc.) |
120
+
|`message`| Error message |
121
+
|`stack`| An array of stack frames. |
105
122
106
-
#### destroy(): Promise<void>
123
+
#### `destroy(): Promise<void>`
107
124
Tears down the agent. For browsers, this will close the browser window.
108
125
109
126
### Runtime Library
110
127
111
-
#### print(str)
128
+
#### `print(str)`
112
129
Prints `str` to stdout.
113
130
114
-
#### $.global
131
+
#### `$.global`
115
132
A reference to the global object.
116
133
117
-
#### $.createRealm(options)
134
+
#### `$.createRealm(options)`
118
135
Creates a new realm, returning that realm's runtime library ($).
119
136
120
137
For example, creating two nested realms:
@@ -128,34 +145,38 @@ You can also use a destroy callback that gets called when the code inside the re
128
145
129
146
```js
130
147
$sub =$.createRealm({
131
-
destroy:function() {
148
+
destroy() {
132
149
print('destroyed!')
133
150
}
134
151
});
135
152
136
153
$sub.evalScript('$.destroy()'); // prints "destroyed!"
137
154
```
138
155
139
-
Options:
156
+
`options`:
157
+
158
+
| Property | Description |
159
+
|-|-|
160
+
|`globals`| An object containing properties to add to the global object in the new realm. |
161
+
|`destroy`| A callback that is called when the code executing in the realm destroys its realm (ie. by calling `$.destroy()`). |
162
+
140
163
141
-
* globals: an object containing properties to add to the global object in the new realm.
142
-
* destroy: a callback that is called when the code executing in the realm destroys its realm (ie. by calling `$.destroy()`).
143
164
144
-
#### $.evalScript(code)
165
+
#### `$.evalScript(code)`
145
166
Creates a new script and evals `code` in that realm. If an error is thrown, it will be passed to the onError callback.
146
167
147
168
Scripts are different from eval in that lexical bindings go into the global lexical contour rather than being scoped to the eval.
148
169
149
-
#### $.destroy()
170
+
#### `$.destroy()`
150
171
Destroys the realm. Note that in some hosts, $.destroy may not actually stop executing code in the realm or even destroy the realm.
151
172
152
-
#### $.getGlobal(name)
173
+
#### `$.getGlobal(name)`
153
174
Gets a global property name.
154
175
155
-
#### $.setGlobal(name, value)
176
+
#### `$.setGlobal(name, value)`
156
177
Sets a global property name to value.
157
178
158
-
###Running the tests
179
+
## Running the tests
159
180
160
181
This project's tests can be executed with the following command:
0 commit comments