UNPKG

7.83 kBMarkdownView Raw
1# mocha-chrome
2
3:coffee: Run Mocha tests using headless Google Chrome
4
5[![Build Status](https://travis-ci.org/shellscape/mocha-chrome.svg?branch=master)](https://travis-ci.org/shellscape/mocha-chrome)
6[![Known Vulnerabilities](https://snyk.io/test/github/shellscape/mocha-chrome/badge.svg)](https://snyk.io/test/github/shellscape/mocha-chrome)
7[![npm version](https://badge.fury.io/js/mocha-chrome.svg)](https://badge.fury.io/js/mocha-chrome)
8[![GitHub version](https://badge.fury.io/gh/shellscape%2Fmocha-chrome.svg)](http://badge.fury.io/gh/shellscape%2Fmocha-chrome)
9[![Open Source Love](https://badges.frapsoft.com/os/mit/mit.svg?v=102)](https://github.com/ellerbrock/open-source-badge/)
10[![Dependency Status](https://david-dm.org/shellscape/mocha-chrome.svg)](https://david-dm.org/shellscape/mocha-chrome)
11[![devDependencies Status](https://david-dm.org/shellscape/mocha-chrome/dev-status.svg)](https://david-dm.org/shellscape/mocha-chrome?type=dev)
12
13## Requirements
14
15`mocha-chrome`requires Node v8.0.0 or higher. Unfortunately the project won't be
16_directly_ supporting a lower version number at this time. However, old-node
17users may choose to use the `--old-and-busted` flag, because your version is not
18the new hotness - it's old and busted;
19
20```console
21--old-and-busted Take pity upon users of old-node. This option will run moche-chrome
22 under Node < 8 using babel-register. Use at your own risk, and
23 without support.
24```
25
26That will run the **cli** using `babel-register`, which inherently runs slower
27due to the nature of `babel-register`. If you're attempting to use the **api**,
28you'll have to mimic the `.babelrc` and `babel-register` setup in this repo.
29
30`mocha-chrome` is a dev tool, which means you can use tools like
31[NVM](https://github.com/creationix/nvm) and [nodenv](https://github.com/nodenv/nodenv)
32to manage your installed versions, and temporarily switch to v8+ to run tests on
33your machine. Most modern CI environments also support specifying the version of
34Node to run.
35
36## Getting Started
37
38To begin, you'll need to install `mocha-chrome`:
39
40```console
41$ npm install mocha-chrome --save-dev
42```
43
44Then you'll need a local npm install of mocha:
45
46```console
47$ npm install mocha --save-dev
48```
49
50To run the tests, you'll need an HTML file with some basics:
51
52```html
53<!doctype>
54<html>
55 <head>
56 <title>Test</title>
57 <meta charset="utf-8">
58 <link rel="stylesheet" href="../../node_modules/mocha/mocha.css" />
59 <script src="../../node_modules/mocha/mocha.js"></script>
60 <script src="../../node_modules/chai/chai.js"></script>
61 </head>
62 <body>
63 <div id="mocha"></div>
64 <script>
65 expect = chai.expect;
66
67 // add tests here
68
69 mocha.run();
70 </script>
71 </body>
72</html>
73
74```
75
76You can then add your tests either through an external script file or
77inline within a `<script>` tag. Running the tests is easy, either with the CLI
78binary, or programmatically.
79
80## CLI
81
82```console
83$ mocha-chrome --help
84
85 Usage
86 $ mocha-chrome <file.html> [options]
87
88 Options
89 --chrome-flags A JSON string representing an array of flags to pass to Chrome
90 --ignore-console Suppress console logging
91 --ignore-exceptions Suppress exceptions logging
92 --ignore-resource-errors Suppress resource error logging
93 --log-level Specify a log level; trace, debug, info, warn, error
94 --mocha A JSON string representing a config object to pass to Mocha
95 --no-colors Disable colors in Mocha's output
96 --old-and-busted Take pity upon users of old-node. This option will run moche-chrome
97 under Node < 8 using babel-register. Use at your own risk, and
98 without support.
99 --reporter Specify the Mocha reporter to use
100 --timeout Specify the test startup timeout to use
101 --version
102
103 Examples
104 $ mocha-chrome test.html --no-colors
105 $ mocha-chrome test.html --reporter dot
106 $ mocha-chrome test.html --mocha '{"ui":"tdd"}'
107```
108
109## Events
110
111`mocha-chrome` is technically an event emitter. Due to the asynchronous nature of
112nearly every interaction with headless Chrome, a simple event bus is used to
113handle actions from the browser. You have access to those events if running
114`mocha-chrome` programatically.
115
116Example usage can be found in both [test.js](test/test.js) and [bin/mocha-chrome](bin/mocha-chrome).
117
118#### `config`
119
120 Fired to indicate that `mocha-chrome` should configure mocha.
121
122#### `ended`
123
124 Fired when all tests have ended.
125
126 ##### Parameters
127 `stats` : `object` - A Mocha stats object. eg:
128
129 ```js
130 {
131 suites: 1,
132 tests: 1,
133 passes: 1,
134 pending: 0,
135 failures: 0,
136 start: '2017-08-03T02:12:02.007Z',
137 end: '2017-08-03T02:12:02.017Z',
138 duration: 10
139 }
140 ```
141
142#### `ready`
143
144 Fired to indicate that the mocha script in the client has been loaded.
145
146#### `resourceFailed`
147
148 Fired when a resource fails to load.
149
150 ##### Parameters
151 `data` : `object` - An object containing information about the resource. eg:
152
153 ```js
154 { url, method, reason }
155 ```
156
157#### `started`
158
159 Fired when a resource fails to load.
160
161 ##### Parameters
162 `tests` : `number` - The number of tests being run.
163
164#### `width`
165
166 Fired to indicate that `mocha-chrome` should inform mocha of the width of
167 the current console/terminal.
168
169## Limitations
170
171### Reporters
172
173Reporters are limited to those which don't use `process.stdout.write` to manipulate
174terminal output. eg. `spec`, `xunit`, etc. Examples of reporters which don't presently
175produce expected output formatting include `dot` and `nyan`. The cause of this
176limitation is the lack of a good means to pipe Mocha's built-in `stdout.write`
177through the Chrome Devtools Protocol to `mocha-chrome`.
178
179### Third-Party Reporters
180
181Third party reporters are not currently supported, but support is planned. Contribution
182on that effort is of course welcome.
183
184### Cookies and the `file://` Protocol
185
186Chrome has long-since disabled cookies for files loaded via the `file://` protocol.
187The once-available `--enable-file-cookies` has been removed and we're left with few options.
188If you're in need of cookie support for your local-file test, you may use the following snippet,
189which will shim `document.cookie` with _very basic_ support:
190
191```js
192 Object.defineProperty(document, 'cookie', {
193 get: function () {
194 return this.value || '';
195 },
196 set: function (cookie) {
197 cookie = cookie || '';
198
199 const cutoff = cookie.indexOf(';');
200 const pair = cookie.substring(0, cutoff >= 0 ? cutoff : cookie.length);
201 const cookies = this.value ? this.value.split('; ') : [];
202
203 cookies.push(pair);
204
205 return this.value = cookies.join('; ');
206 }
207 });
208```
209
210## Continuous Integration
211
212Please 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
213Google. Though the article primarily addresses Karma, the setup for Travis CI is
214identical.
215
216## Testing mocha-chrome
217
218```console
219$ npm test
220```
221
222Yep, that's it.
223
224## Contributing
225
226We welcome your contributions! Please have a read of [CONTRIBUTING](CONTRIBUTING.md).
227
228## Attribution
229
230I'd like to thank @nathanboktae for his work on [mocha-phantomjs](https://github.com/nathanboktae/mocha-phantomjs)
231and [mocha-phantomjs-core](https://github.com/nathanboktae/mocha-phantomjs-core);
232two projects I've used extensively over the years, and from which the inspiration
233for this module originates. Many of the nuances of working with mocha in a hosted
234or connected browser environment were solved within `mocha-phantomjs-core` and I
235am personally grateful.