UNPKG

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