UNPKG

7.22 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 --mocha A JSON string representing a config object to pass to Mocha
90 --log-level Specify a log level; trace, debug, info, warn, error
91 --no-colors Disable colors in Mocha's output
92 --reporter Specify the Mocha reporter to use
93 --timeout Specify the test startup timeout to use
94
95 Examples
96 $ mocha-chrome test.html --no-colors
97 $ mocha-chrome test.html --reporter dot
98 $ mocha-chrome test.html --mocha '{"ui":"tdd"}'
99```
100
101## Events
102
103`mocha-chrome` is technically an event emitter. Due to the asynchronous nature of
104nearly every interaction with headless Chrome, a simple event bus is used to
105handle actions from the browser. You have access to those events if running
106`mocha-chrome` programatically.
107
108Example usage can be found in both [test.js](test/test.js) and [bin/mocha-chrome](bin/mocha-chrome).
109
110#### `config`
111
112 Fired to indicate that `mocha-chrome` should configure mocha.
113
114#### `ended`
115
116 Fired when all tests have ended.
117
118 ##### Parameters
119 `stats` : `object` - A Mocha stats object. eg:
120
121 ```js
122 {
123 suites: 1,
124 tests: 1,
125 passes: 1,
126 pending: 0,
127 failures: 0,
128 start: '2017-08-03T02:12:02.007Z',
129 end: '2017-08-03T02:12:02.017Z',
130 duration: 10
131 }
132 ```
133
134#### `ready`
135
136 Fired to indicate that the mocha script in the client has been loaded.
137
138#### `resourceFailed`
139
140 Fired when a resource fails to load.
141
142 ##### Parameters
143 `data` : `object` - An object containing information about the resource. eg:
144
145 ```js
146 { url, method, reason }
147 ```
148
149#### `started`
150
151 Fired when a resource fails to load.
152
153 ##### Parameters
154 `tests` : `number` - The number of tests being run.
155
156#### `width`
157
158 Fired to indicate that `mocha-chrome` should inform mocha of the width of
159 the current console/terminal.
160
161## Limitations
162
163### Reporters
164
165Reporters are limited to those which don't use `process.stdout.write` to manipulate
166terminal output. eg. `spec`, `xunit`, etc. Examples of reporters which don't presently
167produce expected output formatting include `dot` and `nyan`. The cause of this
168limitation is the lack of a good means to pipe Mocha's built-in `stdout.write`
169through the Chrome Devtools Protocol to `mocha-chrome`.
170
171### Third-Party Reporters
172
173Third party reporters are not currently supported, but support is planned. Contribution
174on that effort is of course welcome.
175
176### Cookies and the `file://` Protocol
177
178Chrome has long-since disabled cookies for files loaded via the `file://` protocol.
179The once-available `--enable-file-cookies` has been removed and we're left with few options.
180If you're in need of cookie support for your local-file test, you may use the following snippet,
181which will shim `document.cookie` with _very basic_ support:
182
183```js
184 Object.defineProperty(document, 'cookie', {
185 get: function () {
186 return this.value || '';
187 },
188 set: function (cookie) {
189 cookie = cookie || '';
190
191 const cutoff = cookie.indexOf(';');
192 const pair = cookie.substring(0, cutoff >= 0 ? cutoff : cookie.length);
193 const cookies = this.value ? this.value.split('; ') : [];
194
195 cookies.push(pair);
196
197 return this.value = cookies.join('; ');
198 }
199 });
200```
201
202## Continuous Integration
203
204Please 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
205Google. Though the article primarily addresses Karma, the setup for Travis CI is
206identical.
207
208## Testing mocha-chrome
209
210```console
211$ npm test
212```
213
214Yep, that's it.
215
216## Contributing
217
218We welcome your contributions! Please have a read of [CONTRIBUTING](CONTRIBUTING.md).
219
220## Attribution
221
222I'd like to thank @nathanboktae for his work on [mocha-phantomjs](https://github.com/nathanboktae/mocha-phantomjs)
223and [mocha-phantomjs-core](https://github.com/nathanboktae/mocha-phantomjs-core);
224two projects I've used extensively over the years, and from which the inspiration
225for this module originates. Many of the nuances of working with mocha in a hosted
226or connected browser environment were solved within `mocha-phantomjs-core` and I
227am personally grateful.