UNPKG

mocha-chrome/README.md

Version:

7.74 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    --chrome-launcher           Chrome launcher options (see https://github.com/GoogleChrome/chrome-launcher#launchopts)
74    --ignore-console            Suppress console logging
75    --ignore-exceptions         Suppress exceptions logging
76    --ignore-resource-errors    Suppress resource error logging
77    --log-level                 Specify a log level; trace, debug, info, warn, error
78    --mocha                     A JSON string representing a config object to pass to Mocha
79    --no-colors                 Disable colors in Mocha's output
80    --reporter                  Specify the Mocha reporter to use
81    --timeout                   Specify the test startup timeout to use
82    --version
83
84  Examples
85  $ mocha-chrome test.html --no-colors
86  $ mocha-chrome test.html --reporter dot
87  $ mocha-chrome test.html --mocha '\{"ui":"tdd"\}'
88  $ mocha-chrome test.html --chrome-flags '["--some-flag", "--and-another-one"]'
89  $ mocha-chrome test.html --chrome-launcher.maxConnectionRetries=10
90```
91
92## Events
93
94`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.
95
96Example usage can be found in both [test.js](test/test.js) and [bin/mocha-chrome](bin/mocha-chrome).
97
98#### `config`
99
100  Fired to indicate that `mocha-chrome` should configure mocha.
101
102#### `ended`
103
104  Fired when all tests have ended.
105
106##### Parameters
107  `stats` : `object` - A Mocha stats object. eg:
108
109  ```js
110  {
111    suites: 1,
112    tests: 1,
113    passes: 1,
114    pending: 0,
115    failures: 0,
116    start: '2017-08-03T02:12:02.007Z',
117    end: '2017-08-03T02:12:02.017Z',
118    duration: 10
119  }
120  ```
121
122#### `ready`
123
124  Fired to indicate that the mocha script in the client has been loaded.
125
126#### `resourceFailed`
127
128  Fired when a resource fails to load.
129
130  ##### Parameters
131  `data` : `object` - An object containing information about the resource. eg:
132
133  ```js
134  { url, method, reason }
135  ```
136
137#### `started`
138
139  Fired when a resource fails to load.
140
141  ##### Parameters
142  `tests` : `number` - The number of tests being run.
143
144#### `width`
145
146  Fired to indicate that `mocha-chrome` should inform mocha of the width of the current console/terminal.
147
148## Limitations
149
150### Reporters
151
152Reporters 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`.
153
154### Third-Party Reporters
155
156Third party reporters are not currently supported, but support is planned. Contribution on that effort is of course welcome.
157
158### Cookies and the `file://` Protocol
159
160Chrome 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:
161
162```js
163  Object.defineProperty(document, 'cookie', {
164    get: function () {
165      return this.value || '';
166    },
167    set: function (cookie) {
168      cookie = cookie || '';
169
170      const cutoff = cookie.indexOf(';');
171      const pair = cookie.substring(0, cutoff >= 0 ? cutoff : cookie.length);
172      const cookies = this.value ? this.value.split('; ') : [];
173
174      cookies.push(pair);
175
176      return this.value = cookies.join('; ');
177    }
178  });
179```
180
181## Continuous Integration
182
183### Circle CI
184
185Running 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).
186
187### Travis CI
188
189Please 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
190Google. Though the article primarily addresses Karma, the setup for Travis CI is
191identical.
192
193As 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).
194
195
196
197## Testing mocha-chrome
198
199```console
200$ npm test
201```
202
203Yep, that's it.
204
205## Contributing
206
207We welcome your contributions! Please have a read of [CONTRIBUTING](.github/CONTRIBUTING.md).
208
209## Attribution
210
211I'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	`--chrome-launcher Chrome launcher options (see https://github.com/GoogleChrome/chrome-launcher#launchopts)`
74	`--ignore-console Suppress console logging`
75	`--ignore-exceptions Suppress exceptions logging`
76	`--ignore-resource-errors Suppress resource error logging`
77	`--log-level Specify a log level; trace, debug, info, warn, error`
78	`--mocha A JSON string representing a config object to pass to Mocha`
79	`--no-colors Disable colors in Mocha's output`
80	`--reporter Specify the Mocha reporter to use`
81	`--timeout Specify the test startup timeout to use`
82	`--version`
83
84	`Examples`
85	`$ mocha-chrome test.html --no-colors`
86	`$ mocha-chrome test.html --reporter dot`
87	`$ mocha-chrome test.html --mocha '\{"ui":"tdd"\}'`
88	`$ mocha-chrome test.html --chrome-flags '["--some-flag", "--and-another-one"]'`
89	`$ mocha-chrome test.html --chrome-launcher.maxConnectionRetries=10`
90	```
91
92	`## Events`
93
94	`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.
95
96	`Example usage can be found in both [test.js](test/test.js) and [bin/mocha-chrome](bin/mocha-chrome).`
97
98	#### `config`
99
100	Fired to indicate that `mocha-chrome` should configure mocha.
101
102	#### `ended`
103
104	`Fired when all tests have ended.`
105
106	`##### Parameters`
107	`stats` : `object` - A Mocha stats object. eg:
108
109	```js
110	`{`
111	`suites: 1,`
112	`tests: 1,`
113	`passes: 1,`
114	`pending: 0,`
115	`failures: 0,`
116	`start: '2017-08-03T02:12:02.007Z',`
117	`end: '2017-08-03T02:12:02.017Z',`
118	`duration: 10`
119	`}`
120	```
121
122	#### `ready`
123
124	`Fired to indicate that the mocha script in the client has been loaded.`
125
126	#### `resourceFailed`
127
128	`Fired when a resource fails to load.`
129
130	`##### Parameters`
131	`data` : `object` - An object containing information about the resource. eg:
132
133	```js
134	`{ url, method, reason }`
135	```
136
137	#### `started`
138
139	`Fired when a resource fails to load.`
140
141	`##### Parameters`
142	`tests` : `number` - The number of tests being run.
143
144	#### `width`
145
146	Fired to indicate that `mocha-chrome` should inform mocha of the width of the current console/terminal.
147
148	`## Limitations`
149
150	`### Reporters`
151
152	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`.
153
154	`### Third-Party Reporters`
155
156	`Third party reporters are not currently supported, but support is planned. Contribution on that effort is of course welcome.`
157
158	### Cookies and the `file://` Protocol
159
160	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:
161
162	```js
163	`Object.defineProperty(document, 'cookie', {`
164	`get: function () {`
165	`return this.value \|\| '';`
166	`},`
167	`set: function (cookie) {`
168	`cookie = cookie \|\| '';`
169
170	`const cutoff = cookie.indexOf(';');`
171	`const pair = cookie.substring(0, cutoff >= 0 ? cutoff : cookie.length);`
172	`const cookies = this.value ? this.value.split('; ') : [];`
173
174	`cookies.push(pair);`
175
176	`return this.value = cookies.join('; ');`
177	`}`
178	`});`
179	```
180
181	`## Continuous Integration`
182
183	`### Circle CI`
184
185	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).
186
187	`### Travis CI`
188
189	`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`
190	`Google. Though the article primarily addresses Karma, the setup for Travis CI is`
191	`identical.`
192
193	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).
194
195
196
197	`## Testing mocha-chrome`
198
199	```console
200	`$ npm test`
201	```
202
203	`Yep, that's it.`
204
205	`## Contributing`
206
207	`We welcome your contributions! Please have a read of [CONTRIBUTING](.github/CONTRIBUTING.md).`
208
209	`## Attribution`
210
211	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.