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
|
17 | users may choose to use the `--old-and-busted` flag, because your version is not
|
18 | the 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 |
|
26 | That will run the **cli** using `babel-register`, which inherently runs slower
|
27 | due to the nature of `babel-register`. If you're attempting to use the **api**,
|
28 | you'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)
|
32 | to manage your installed versions, and temporarily switch to v8+ to run tests on
|
33 | your machine. Most modern CI environments also support specifying the version of
|
34 | Node to run.
|
35 |
|
36 | ## Getting Started
|
37 |
|
38 | To begin, you'll need to install `mocha-chrome`:
|
39 |
|
40 | ```console
|
41 | $ npm install mocha-chrome --save-dev
|
42 | ```
|
43 |
|
44 | Then you'll need a local npm install of mocha:
|
45 |
|
46 | ```console
|
47 | $ npm install mocha --save-dev
|
48 | ```
|
49 |
|
50 | To 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 |
|
76 | You can then add your tests either through an external script file or
|
77 | inline within a `<script>` tag. Running the tests is easy, either with the CLI
|
78 | binary, 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
|
112 | nearly every interaction with headless Chrome, a simple event bus is used to
|
113 | handle actions from the browser. You have access to those events if running
|
114 | `mocha-chrome` programatically.
|
115 |
|
116 | Example 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 |
|
173 | Reporters are limited to those which don't use `process.stdout.write` to manipulate
|
174 | terminal output. eg. `spec`, `xunit`, etc. Examples of reporters which don't presently
|
175 | produce expected output formatting include `dot` and `nyan`. The cause of this
|
176 | limitation is the lack of a good means to pipe Mocha's built-in `stdout.write`
|
177 | through the Chrome Devtools Protocol to `mocha-chrome`.
|
178 |
|
179 | ### Third-Party Reporters
|
180 |
|
181 | Third party reporters are not currently supported, but support is planned. Contribution
|
182 | on that effort is of course welcome.
|
183 |
|
184 | ### Cookies and the `file://` Protocol
|
185 |
|
186 | Chrome has long-since disabled cookies for files loaded via the `file://` protocol.
|
187 | The once-available `--enable-file-cookies` has been removed and we're left with few options.
|
188 | If you're in need of cookie support for your local-file test, you may use the following snippet,
|
189 | which 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 |
|
212 | 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
|
213 | Google. Though the article primarily addresses Karma, the setup for Travis CI is
|
214 | identical.
|
215 |
|
216 | ## Testing mocha-chrome
|
217 |
|
218 | ```console
|
219 | $ npm test
|
220 | ```
|
221 |
|
222 | Yep, that's it.
|
223 |
|
224 | ## Contributing
|
225 |
|
226 | We welcome your contributions! Please have a read of [CONTRIBUTING](CONTRIBUTING.md).
|
227 |
|
228 | ## Attribution
|
229 |
|
230 | I'd like to thank @nathanboktae for his work on [mocha-phantomjs](https://github.com/nathanboktae/mocha-phantomjs)
|
231 | and [mocha-phantomjs-core](https://github.com/nathanboktae/mocha-phantomjs-core);
|
232 | two projects I've used extensively over the years, and from which the inspiration
|
233 | for this module originates. Many of the nuances of working with mocha in a hosted
|
234 | or connected browser environment were solved within `mocha-phantomjs-core` and I
|
235 | am personally grateful.
|