UNPKG

mocha-chrome/README.md

Version:

7.47 kBMarkdownView Raw

1[tests]: 	https://img.shields.io/circleci/project/github/shellscape/mocha-chrome.svg
2[tests-url]: https://circleci.com/gh/shellscape/mocha-chrome
3
4[size]: https://packagephobia.now.sh/badge?p=mocha-chrome
5[size-url]: https://packagephobia.now.sh/result?p=mocha-chrome
6
7[![tests][tests]][tests-url]
8[![size][size]][size-url]
9[![libera manifesto](https://img.shields.io/badge/libera-manifesto-lightgrey.svg)](https://liberamanifesto.com)
10
11# mocha-chrome
12
13:coffee: Run Mocha tests using headless Google Chrome
14
15## Requirements
16
17`mocha-chrome` requires Node v8.0.0 or higher.
18
19`mocha-chrome` is a development tool, which means you can use tools like [NVM](https://github.com/creationix/nvm) and [nodenv](https://github.com/nodenv/nodenv) to manage your installed versions, and temporarily switch to v8+ to run tests on your machine. Most modern CI environments also support specifying the version of Node to run.
20
21## Getting Started
22
23To begin, you'll need to install `mocha-chrome`:
24
25```console
26$ npm install mocha-chrome --save-dev
27```
28
29Then you'll need a local npm install of mocha:
30
31```console
32$ npm install mocha --save-dev
33```
34
35To run the tests, you'll need an HTML file with some basics:
36
37```html
38<!doctype>
39<html>
40  <head>
41    <title>Test</title>
42    <meta charset="utf-8">
43    <link rel="stylesheet" href="../../node_modules/mocha/mocha.css" />
44    <script src="../../node_modules/mocha/mocha.js"></script>
45    <script src="../../node_modules/chai/chai.js"></script>
46  </head>
47  <body>
48    <div id="mocha"></div>
49    <script>
50      expect = chai.expect;
51
52      // add tests here
53
54      mocha.run();
55    </script>
56  </body>
57</html>
58
59```
60
61You can then add your tests either through an external script file or inline within a `<script>` tag. Running the tests is easy, either with the CLI binary, or programmatically.
62
63## CLI
64
65```console
66$ mocha-chrome --help
67
68  Usage
69    $ mocha-chrome <file.html> [options]
70
71  Options
72    --chrome-flags              A JSON string representing an array of flags to pass to Chrome
73    --ignore-console            Suppress console logging
74    --ignore-exceptions         Suppress exceptions logging
75    --ignore-resource-errors    Suppress resource error logging
76    --log-level                 Specify a log level; trace, debug, info, warn, error
77    --mocha                     A JSON string representing a config object to pass to Mocha
78    --no-colors                 Disable colors in Mocha's output
79    --reporter                  Specify the Mocha reporter to use
80    --timeout                   Specify the test startup timeout to use
81    --version
82
83  Examples
84    $ mocha-chrome test.html --no-colors
85    $ mocha-chrome test.html --reporter dot
86    $ mocha-chrome test.html --mocha '{"ui":"tdd"}'
87```
88
89## Events
90
91`mocha-chrome` is technically an event emitter. Due to the asynchronous nature of nearly every interaction with headless Chrome, a simple event bus is used to handle actions from the browser. You have access to those events if running `mocha-chrome` programatically.
92
93Example usage can be found in both [test.js](test/test.js) and [bin/mocha-chrome](bin/mocha-chrome).
94
95#### `config`
96
97  Fired to indicate that `mocha-chrome` should configure mocha.
98
99#### `ended`
100
101  Fired when all tests have ended.
102
103##### Parameters
104  `stats` : `object` - A Mocha stats object. eg:
105
106  ```js
107  {
108    suites: 1,
109    tests: 1,
110    passes: 1,
111    pending: 0,
112    failures: 0,
113    start: '2017-08-03T02:12:02.007Z',
114    end: '2017-08-03T02:12:02.017Z',
115    duration: 10
116  }
117  ```
118
119#### `ready`
120
121  Fired to indicate that the mocha script in the client has been loaded.
122
123#### `resourceFailed`
124
125  Fired when a resource fails to load.
126
127  ##### Parameters
128  `data` : `object` - An object containing information about the resource. eg:
129
130  ```js
131  { url, method, reason }
132  ```
133
134#### `started`
135
136  Fired when a resource fails to load.
137
138  ##### Parameters
139  `tests` : `number` - The number of tests being run.
140
141#### `width`
142
143  Fired to indicate that `mocha-chrome` should inform mocha of the width of the current console/terminal.
144
145## Limitations
146
147### Reporters
148
149Reporters are limited to those which don't use `process.stdout.write` to manipulate terminal output. eg. `spec`, `xunit`, etc. Examples of reporters which don't presently produce expected output formatting include `dot` and `nyan`. The cause of this limitation is the lack of a good means to pipe Mocha's built-in `stdout.write` through the Chrome Devtools Protocol to `mocha-chrome`.
150
151### Third-Party Reporters
152
153Third party reporters are not currently supported, but support is planned. Contribution on that effort is of course welcome.
154
155### Cookies and the `file://` Protocol
156
157Chrome has long-since disabled cookies for files loaded via the `file://` protocol. The once-available `--enable-file-cookies` has been removed and we're left with few options. If you're in need of cookie support for your local-file test, you may use the following snippet, which will shim `document.cookie` with _very basic_ support:
158
159```js
160  Object.defineProperty(document, 'cookie', {
161    get: function () {
162      return this.value || '';
163    },
164    set: function (cookie) {
165      cookie = cookie || '';
166
167      const cutoff = cookie.indexOf(';');
168      const pair = cookie.substring(0, cutoff >= 0 ? cutoff : cookie.length);
169      const cookies = this.value ? this.value.split('; ') : [];
170
171      cookies.push(pair);
172
173      return this.value = cookies.join('; ');
174    }
175  });
176```
177
178## Continuous Integration
179
180### Circle CI
181
182Running on Circle CI requires that Chrome is installed and running in the container your tests are running within. Please refer to this article for details: https://discuss.circleci.com/t/installing-chrome-inside-of-your-docker-container/9067. Alternatively, you can use a pre-built CircleCI image with browsers installed. You'll have to choose a tag with the `-browsers` suffix from the [full tag list](https://circleci.com/docs/2.0/docker-image-tags.json).
183
184### Travis CI
185
186Please refer to the _"Running it all on Travis CI"_ portion of the guide on [Automated testing with Headless Chrome](https://developers.google.com/web/updates/2017/06/headless-karma-mocha-chai) from
187Google. Though the article primarily addresses Karma, the setup for Travis CI is
188identical.
189
190As of January 8th, 2018, Travis CI has upgraded from Trusty -> Xenial to address the [Meltdown](https://en.wikipedia.org/wiki/Meltdown_(security_vulnerability)) security vulnerability. There are issues with Chrome in Xenial that can currently be worked around with `sudo: required`. At some point this workaround may be removable. For the near term, please add `sudo: required` to Travis CI configuration files. See [travis-ci/travis-ci#8836](travis-ci/travis-ci#8836). Credit: [@smalls](https://github.com/shellscape/mocha-chrome/pull/21).
191
192
193
194## Testing mocha-chrome
195
196```console
197$ npm test
198```
199
200Yep, that's it.
201
202## Contributing
203
204We welcome your contributions! Please have a read of [CONTRIBUTING](.github/CONTRIBUTING.md).
205
206## Attribution
207
208I'd like to thank @nathanboktae for his work on [mocha-phantomjs](https://github.com/nathanboktae/mocha-phantomjs) and [mocha-phantomjs-core](https://github.com/nathanboktae/mocha-phantomjs-core); two projects I've used extensively over the years, and from which the inspiration for this module originates. Many of the nuances of working with mocha in a hosted or connected browser environment were solved within `mocha-phantomjs-core` and I am personally grateful.

1	`[tests]: https://img.shields.io/circleci/project/github/shellscape/mocha-chrome.svg`
2	`[tests-url]: https://circleci.com/gh/shellscape/mocha-chrome`
3
4	`[size]: https://packagephobia.now.sh/badge?p=mocha-chrome`
5	`[size-url]: https://packagephobia.now.sh/result?p=mocha-chrome`
6
7	`[![tests][tests]][tests-url]`
8	`[![size][size]][size-url]`
9	`[![libera manifesto](https://img.shields.io/badge/libera-manifesto-lightgrey.svg)](https://liberamanifesto.com)`
10
11	`# mocha-chrome`
12
13	`:coffee: Run Mocha tests using headless Google Chrome`
14
15	`## Requirements`
16
17	`mocha-chrome` requires Node v8.0.0 or higher.
18
19	`mocha-chrome` is a development tool, which means you can use tools like [NVM](https://github.com/creationix/nvm) and [nodenv](https://github.com/nodenv/nodenv) to manage your installed versions, and temporarily switch to v8+ to run tests on your machine. Most modern CI environments also support specifying the version of Node to run.
20
21	`## Getting Started`
22
23	To begin, you'll need to install `mocha-chrome`:
24
25	```console
26	`$ npm install mocha-chrome --save-dev`
27	```
28
29	`Then you'll need a local npm install of mocha:`
30
31	```console
32	`$ npm install mocha --save-dev`
33	```
34
35	`To run the tests, you'll need an HTML file with some basics:`
36
37	```html
38	`<!doctype>`
39	`<html>`
40	`<head>`
41	`<title>Test</title>`
42	`<meta charset="utf-8">`
43	`<link rel="stylesheet" href="../../node_modules/mocha/mocha.css" />`
44	`<script src="../../node_modules/mocha/mocha.js"></script>`
45	`<script src="../../node_modules/chai/chai.js"></script>`
46	`</head>`
47	`<body>`
48	`<div id="mocha"></div>`
49	`<script>`
50	`expect = chai.expect;`
51
52	`// add tests here`
53
54	`mocha.run();`
55	`</script>`
56	`</body>`
57	`</html>`
58
59	```
60
61	You can then add your tests either through an external script file or inline within a `<script>` tag. Running the tests is easy, either with the CLI binary, or programmatically.
62
63	`## CLI`
64
65	```console
66	`$ mocha-chrome --help`
67
68	`Usage`
69	`$ mocha-chrome <file.html> [options]`
70
71	`Options`
72	`--chrome-flags A JSON string representing an array of flags to pass to Chrome`
73	`--ignore-console Suppress console logging`
74	`--ignore-exceptions Suppress exceptions logging`
75	`--ignore-resource-errors Suppress resource error logging`
76	`--log-level Specify a log level; trace, debug, info, warn, error`
77	`--mocha A JSON string representing a config object to pass to Mocha`
78	`--no-colors Disable colors in Mocha's output`
79	`--reporter Specify the Mocha reporter to use`
80	`--timeout Specify the test startup timeout to use`
81	`--version`
82
83	`Examples`
84	`$ mocha-chrome test.html --no-colors`
85	`$ mocha-chrome test.html --reporter dot`
86	`$ mocha-chrome test.html --mocha '{"ui":"tdd"}'`
87	```
88
89	`## Events`
90
91	`mocha-chrome` is technically an event emitter. Due to the asynchronous nature of nearly every interaction with headless Chrome, a simple event bus is used to handle actions from the browser. You have access to those events if running `mocha-chrome` programatically.
92
93	`Example usage can be found in both [test.js](test/test.js) and [bin/mocha-chrome](bin/mocha-chrome).`
94
95	#### `config`
96
97	Fired to indicate that `mocha-chrome` should configure mocha.
98
99	#### `ended`
100
101	`Fired when all tests have ended.`
102
103	`##### Parameters`
104	`stats` : `object` - A Mocha stats object. eg:
105
106	```js
107	`{`
108	`suites: 1,`
109	`tests: 1,`
110	`passes: 1,`
111	`pending: 0,`
112	`failures: 0,`
113	`start: '2017-08-03T02:12:02.007Z',`
114	`end: '2017-08-03T02:12:02.017Z',`
115	`duration: 10`
116	`}`
117	```
118
119	#### `ready`
120
121	`Fired to indicate that the mocha script in the client has been loaded.`
122
123	#### `resourceFailed`
124
125	`Fired when a resource fails to load.`
126
127	`##### Parameters`
128	`data` : `object` - An object containing information about the resource. eg:
129
130	```js
131	`{ url, method, reason }`
132	```
133
134	#### `started`
135
136	`Fired when a resource fails to load.`
137
138	`##### Parameters`
139	`tests` : `number` - The number of tests being run.
140
141	#### `width`
142
143	Fired to indicate that `mocha-chrome` should inform mocha of the width of the current console/terminal.
144
145	`## Limitations`
146
147	`### Reporters`
148
149	Reporters are limited to those which don't use `process.stdout.write` to manipulate terminal output. eg. `spec`, `xunit`, etc. Examples of reporters which don't presently produce expected output formatting include `dot` and `nyan`. The cause of this limitation is the lack of a good means to pipe Mocha's built-in `stdout.write` through the Chrome Devtools Protocol to `mocha-chrome`.
150
151	`### Third-Party Reporters`
152
153	`Third party reporters are not currently supported, but support is planned. Contribution on that effort is of course welcome.`
154
155	### Cookies and the `file://` Protocol
156
157	Chrome has long-since disabled cookies for files loaded via the `file://` protocol. The once-available `--enable-file-cookies` has been removed and we're left with few options. If you're in need of cookie support for your local-file test, you may use the following snippet, which will shim `document.cookie` with _very basic_ support:
158
159	```js
160	`Object.defineProperty(document, 'cookie', {`
161	`get: function () {`
162	`return this.value \|\| '';`
163	`},`
164	`set: function (cookie) {`
165	`cookie = cookie \|\| '';`
166
167	`const cutoff = cookie.indexOf(';');`
168	`const pair = cookie.substring(0, cutoff >= 0 ? cutoff : cookie.length);`
169	`const cookies = this.value ? this.value.split('; ') : [];`
170
171	`cookies.push(pair);`
172
173	`return this.value = cookies.join('; ');`
174	`}`
175	`});`
176	```
177
178	`## Continuous Integration`
179
180	`### Circle CI`
181
182	Running on Circle CI requires that Chrome is installed and running in the container your tests are running within. Please refer to this article for details: https://discuss.circleci.com/t/installing-chrome-inside-of-your-docker-container/9067. Alternatively, you can use a pre-built CircleCI image with browsers installed. You'll have to choose a tag with the `-browsers` suffix from the [full tag list](https://circleci.com/docs/2.0/docker-image-tags.json).
183
184	`### Travis CI`
185
186	`Please refer to the _"Running it all on Travis CI"_ portion of the guide on [Automated testing with Headless Chrome](https://developers.google.com/web/updates/2017/06/headless-karma-mocha-chai) from`
187	`Google. Though the article primarily addresses Karma, the setup for Travis CI is`
188	`identical.`
189
190	As of January 8th, 2018, Travis CI has upgraded from Trusty -> Xenial to address the [Meltdown](https://en.wikipedia.org/wiki/Meltdown_(security_vulnerability)) security vulnerability. There are issues with Chrome in Xenial that can currently be worked around with `sudo: required`. At some point this workaround may be removable. For the near term, please add `sudo: required` to Travis CI configuration files. See [travis-ci/travis-ci#8836](travis-ci/travis-ci#8836). Credit: [@smalls](https://github.com/shellscape/mocha-chrome/pull/21).
191
192
193
194	`## Testing mocha-chrome`
195
196	```console
197	`$ npm test`
198	```
199
200	`Yep, that's it.`
201
202	`## Contributing`
203
204	`We welcome your contributions! Please have a read of [CONTRIBUTING](.github/CONTRIBUTING.md).`
205
206	`## Attribution`
207
208	I'd like to thank @nathanboktae for his work on [mocha-phantomjs](https://github.com/nathanboktae/mocha-phantomjs) and [mocha-phantomjs-core](https://github.com/nathanboktae/mocha-phantomjs-core); two projects I've used extensively over the years, and from which the inspiration for this module originates. Many of the nuances of working with mocha in a hosted or connected browser environment were solved within `mocha-phantomjs-core` and I am personally grateful.