UNPKG

6.68 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 supporting a lower version number at this time. If you're in a situation where Node cannot be upgraded on a production server, not to worry! `mocha-chrome` is a dev 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.
16
17## Getting Started
18
19To begin, you'll need to install `mocha-chrome`:
20
21```console
22$ npm install mocha-chrome --save-dev
23```
24
25Then you'll need a local npm install of mocha:
26
27```console
28$ npm install mocha --save-dev
29```
30
31To run the tests, you'll need an HTML file with some basics:
32
33```html
34<!doctype>
35<html>
36 <head>
37 <title>Test</title>
38 <meta charset="utf-8">
39 <link rel="stylesheet" href="../../node_modules/mocha/mocha.css" />
40 <script src="../../node_modules/mocha/mocha.js"></script>
41 <script src="../../node_modules/chai/chai.js"></script>
42 </head>
43 <body>
44 <div id="mocha"></div>
45 <script>
46 expect = chai.expect;
47
48 // add tests here
49
50 mocha.run();
51 </script>
52 </body>
53</html>
54
55```
56
57You can then add your tests either through an external script file or
58inline within a `<script>` tag. Running the tests is easy, either with the CLI
59binary, or programmatically.
60
61## CLI
62
63```console
64$ mocha-chrome --help
65
66 Usage
67 $ mocha-chrome <file.html> [options]
68
69 Options
70 --mocha A JSON string representing a config object to pass to Mocha
71 --log-level Specify a log level; trace, debug, info, warn, error
72 --no-colors Disable colors in Mocha's output
73 --reporter Specify the Mocha reporter to use
74 --timeout Specify the test startup timeout to use
75
76 Examples
77 $ mocha-chrome test.html --no-colors
78 $ mocha-chrome test.html --reporter dot
79 $ mocha-chrome test.html --mocha '{"ui":"tdd"}'
80```
81
82## Events
83
84`mocha-chrome` is technically an event emitter. Due to the asynchronous nature of
85nearly every interaction with headless Chrome, a simple event bus is used to
86handle actions from the browser. You have access to those events if running
87`mocha-chrome` programatically.
88
89Example usage can be found in both [test.js](test/test.js) and [bin/mocha-chrome](bin/mocha-chrome).
90
91#### `config`
92
93 Fired to indicate that `mocha-chrome` should configure mocha.
94
95#### `ended`
96
97 Fired when all tests have ended.
98
99 ##### Parameters
100 `stats` : `object` - A Mocha stats object. eg:
101
102 ```js
103 {
104 suites: 1,
105 tests: 1,
106 passes: 1,
107 pending: 0,
108 failures: 0,
109 start: '2017-08-03T02:12:02.007Z',
110 end: '2017-08-03T02:12:02.017Z',
111 duration: 10
112 }
113 ```
114
115#### `ready`
116
117 Fired to indicate that the mocha script in the client has been loaded.
118
119#### `resourceFailed`
120
121 Fired when a resource fails to load.
122
123 ##### Parameters
124 `data` : `object` - An object containing information about the resource. eg:
125
126 ```js
127 { url, method, reason }
128 ```
129
130#### `started`
131
132 Fired when a resource fails to load.
133
134 ##### Parameters
135 `tests` : `number` - The number of tests being run.
136
137#### `width`
138
139 Fired to indicate that `mocha-chrome` should inform mocha of the width of
140 the current console/terminal.
141
142## Limitations
143
144### Reporters
145
146Reporters are limited to those which don't use `process.stdout.write` to manipulate
147terminal output. eg. `spec`, `xunit`, etc. Examples of reporters which don't presently
148produce expected output formatting include `dot` and `nyan`. The cause of this
149limitation is the lack of a good means to pipe Mocha's built-in `stdout.write`
150through the Chrome Devtools Protocol to `mocha-chrome`.
151
152### Third-Party Reporters
153
154Third party reporters are not currently supported, but support is planned. Contribution
155on that effort is of course welcome.
156
157### Cookies and the `file://` Protocol
158
159Chrome has long-since disabled cookies for files loaded via the `file://` protocol.
160The once-available `--enable-file-cookies` has been removed and we're left with few options.
161If you're in need of cookie support for your local-file test, you may use the following snippet,
162which will shim `document.cookie` with _very basic_ support:
163
164```js
165 Object.defineProperty(document, 'cookie', {
166 get: function () {
167 return this.value || '';
168 },
169 set: function (cookie) {
170 cookie = cookie || '';
171
172 const cutoff = cookie.indexOf(';');
173 const pair = cookie.substring(0, cutoff >= 0 ? cutoff : cookie.length);
174 const cookies = this.value ? this.value.split('; ') : [];
175
176 cookies.push(pair);
177
178 return this.value = cookies.join('; ');
179 }
180 });
181```
182
183## Continuous Integration
184
185Please 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
186Google. Though the article primarily addresses Karma, the setup for Travis CI is
187identical.
188
189## Testing mocha-chrome
190
191```console
192$ npm test
193```
194
195Yep, that's it.
196
197## Contributing
198
199We welcome your contributions! Please have a read of [CONTRIBUTING](CONTRIBUTING.md).
200
201## Attribution
202
203I'd like to thank @nathanboktae for his work on [mocha-phantomjs](https://github.com/nathanboktae/mocha-phantomjs)
204and [mocha-phantomjs-core](https://github.com/nathanboktae/mocha-phantomjs-core);
205two projects I've used extensively over the years, and from which the inspiration
206for this module originates. Many of the nuances of working with mocha in a hosted
207or connected browser environment were solved within `mocha-phantomjs-core` and I
208am personally grateful.