1 | [![NPM version](http://img.shields.io/npm/v/web-component-tester.svg?style=flat-square)](https://npmjs.org/package/web-component-tester)
|
2 | [![Build Status](http://img.shields.io/travis/Polymer/web-component-tester.svg?style=flat-square)](https://travis-ci.org/Polymer/web-component-tester)
|
3 | [![Gitter](http://img.shields.io/badge/slack-join%20chat%20%E2%86%92-brightgreen.svg?style=flat-square)](https://polymer-slack.herokuapp.com/)
|
4 |
|
5 | `web-component-tester` makes testing your web components a breeze!
|
6 |
|
7 | You get a browser-based testing environment, configured out of the box with:
|
8 |
|
9 | * [Mocha][mocha] as a test framework.
|
10 | * [Chai][chai] assertions.
|
11 | * [Async][async] to keep your sanity.
|
12 | * [Lodash][lodash] (3.0) to repeat fewer things.
|
13 | * [Sinon][sinon] and [sinon-chai][sinon-chai] to test just your things.
|
14 | * [test-fixture][test-fixture] for easy fixture testing with `<template>` tags.
|
15 | * [accessibility-developer-tools][a11ydevtools] through `a11ySuite` for simple, automated Accessibility testing.
|
16 |
|
17 | WCT will [run your tests](#running-your-tests) against whatever browsers you have locally installed, or remotely via Sauce Labs.
|
18 |
|
19 |
|
20 | # Getting Started
|
21 |
|
22 | ## `.html` Suites
|
23 |
|
24 | Your test suites can be `.html` documents. For example,
|
25 | `test/awesomest-tests.html`:
|
26 |
|
27 | ```html
|
28 | <!doctype html>
|
29 | <html>
|
30 | <head>
|
31 | <meta charset="utf-8">
|
32 | <script src="../../webcomponentsjs/webcomponents-lite.js"></script>
|
33 | <script src="../../web-component-tester/browser.js"></script>
|
34 | <link rel="import" href="../awesome-element.html">
|
35 | </head>
|
36 | <body>
|
37 | <awesome-element id="fixture"></awesome-element>
|
38 | <script>
|
39 | suite('<awesome-element>', function() {
|
40 | test('is awesomest', function() {
|
41 | assert.isTrue(document.getElementById('fixture').awesomest);
|
42 | });
|
43 | });
|
44 | </script>
|
45 | </body>
|
46 | </html>
|
47 | ```
|
48 |
|
49 | Note that it is _critical_ that you include `../web-component-tester/browser.js`
|
50 | in your test suites. `browser.js` contains all of WCT's client logic (and loads
|
51 | bundled libraries like mocha and chai). You can also load it from the absolute URL `/components/web-component-tester/browser.js`.
|
52 |
|
53 | ## `.js` Suites
|
54 |
|
55 | Alternatively, you can write tests in separate `.js` sources. For example,
|
56 | `test/awesome-tests.js`:
|
57 |
|
58 | ```js
|
59 | suite('AwesomeLib', function() {
|
60 | test('is awesome', function() {
|
61 | assert.isTrue(AwesomeLib.awesome);
|
62 | });
|
63 | });
|
64 | ```
|
65 |
|
66 | ## Special Features
|
67 |
|
68 | ### test-fixture
|
69 | `test-fixture` can be used to reset DOM state between test runs.
|
70 | ```html
|
71 | <test-fixture id="simple">
|
72 | <template>
|
73 | <div></div>
|
74 | </template>
|
75 | </test-fixture>
|
76 | <script>
|
77 | suite('classList', () => {
|
78 | let div;
|
79 | setup(() => {
|
80 | div = fixture('simple');
|
81 | });
|
82 | test('foo', () => {
|
83 | div.classList.add('foo');
|
84 | assertSomethingOrOther(div);
|
85 | });
|
86 | test('bar', () => {
|
87 | div.classList.add('bar');
|
88 | assertNoFooClass(div);
|
89 | });
|
90 | });
|
91 | ```
|
92 |
|
93 | ### a11ySuite(fixureId, ignoredTests, beforeEach)
|
94 | |Parameter|Type|Descrption|
|
95 | |---|---|---|
|
96 | |fixtureId|String|ID of the fixture to instantiate and test|
|
97 | |ignoredTests|Array<string> (optional)|Tests to ignore. <br />Test names are found [here](https://github.com/GoogleChrome/accessibility-developer-tools/blob/master/dist/js/axs_testing.js) as calls to axs.AuditRules.addRule()|
|
98 | |beforeEach|Function (optional)|Called before each test is run|
|
99 |
|
100 | `a11ySuite` provides an simple way to run accessibility-developer-tools' high quality accessibility
|
101 | audits when given a `test-fixture`.
|
102 | The `a11ySuite` will show all the audit results via the standard Mocha test output.
|
103 | ```html
|
104 | <test-fixture id="NoLabel">
|
105 | <template>
|
106 | <paper-radio-button id="radio-1"></paper-radio-button>
|
107 | </template>
|
108 | </test-fixture>
|
109 |
|
110 | <script>
|
111 | a11ySuite('NoLabel');
|
112 | </script>
|
113 | ```
|
114 | ![Accessibility Suite Test Run](a11ySuiteExample.png)
|
115 |
|
116 | ## Running Your Tests
|
117 |
|
118 | ### `wct`
|
119 |
|
120 | The easiest way to run your tests is via the `wct` command line tool. Install
|
121 | it globally via:
|
122 |
|
123 | ```sh
|
124 | npm install -g web-component-tester
|
125 | ```
|
126 |
|
127 | Make sure that you also have [Java][java] installed and available on your
|
128 | `PATH`.
|
129 |
|
130 | The `wct` tool will run your tests in all the browsers you have installed. Just
|
131 | run it:
|
132 |
|
133 | ```sh
|
134 | wct
|
135 | ```
|
136 |
|
137 | By default, any tests under `test/` will be run. You can override this by
|
138 | specifying particular files (or globs of files) via `wct path/to/files`.
|
139 |
|
140 |
|
141 | ### Web Server
|
142 |
|
143 | If you prefer not to use WCT's command line tool, you can also run WCT tests
|
144 | directly in a browser via a web server of your choosing.
|
145 |
|
146 | Make sure that WCT's `browser.js` is accessible by your web server, and have
|
147 | your tests load `browser.js`.
|
148 |
|
149 | The recommended way to fetch these is via Bower:
|
150 |
|
151 | bower install Polymer/web-component-tester --save
|
152 |
|
153 |
|
154 | #### Nested Suites
|
155 |
|
156 | To help support this case, you can also directly define an index that will load
|
157 | any desired tests:
|
158 |
|
159 | ```html
|
160 | <!doctype html>
|
161 | <html>
|
162 | <head>
|
163 | <meta charset="utf-8">
|
164 | <script src="../../webcomponentsjs/webcomponents-lite.js"></script>
|
165 | <script src="../../web-component-tester/browser.js"></script>
|
166 | <script src="../awesome.js"></script>
|
167 | </head>
|
168 | <body>
|
169 | <script>
|
170 | WCT.loadSuites([
|
171 | 'awesome-tests.js',
|
172 | 'awesomest-tests.html',
|
173 | ]);
|
174 | </script>
|
175 | </body>
|
176 | </html>
|
177 | ```
|
178 |
|
179 | _When you use `wct` on the command line, it is generating an index like this for
|
180 | you based on the suites you ask it to load._
|
181 |
|
182 |
|
183 | # Configuration
|
184 |
|
185 | The `wct` command line tool will pick up custom configuration from a
|
186 | `wct.conf.json` file located in the root of your project.
|
187 | Or, you can specify your own file via the `--configFile` command line option.
|
188 | Example: `--configFile my.wct.conf.js`
|
189 | If you define your own configuration file, make sure you also provide the correct root if needed.
|
190 | By default it will use the directory in which the configuration file is found as rootpath, which can result in errors if the file is in a sub directory.
|
191 |
|
192 | It should export the custom configuration:
|
193 |
|
194 | ```js
|
195 | {
|
196 | "verbose": true,
|
197 | "plugins": {
|
198 | "local": {
|
199 | "browsers": ["chrome", "firefox"]
|
200 | }
|
201 | }
|
202 | }
|
203 | ```
|
204 |
|
205 | See [`runner/config.ts`](runner/config.ts) for the canonical reference of
|
206 | configuration properties.
|
207 |
|
208 | You can also specify global defaults (such as `sauce.username`, etc) via a
|
209 | config file located at `~/wct.conf.json`.
|
210 |
|
211 | ## Plugins
|
212 |
|
213 | Note that by specifying a plugin's configuration, you are letting WCT know that
|
214 | it should load that plugin. If you wish to provide default configuration for a
|
215 | plugin, but not enable it, you can have it default to disabled:
|
216 |
|
217 | ```js
|
218 | {
|
219 | "plugins": {
|
220 | "sauce": {
|
221 | "disabled": true,
|
222 | "browsers": [{
|
223 | "browserName": "microsoftedge",
|
224 | "platform": "Windows 10",
|
225 | "version": ""
|
226 | }, {
|
227 | "browserName": "internet explorer",
|
228 | "platform": "Windows 8.1",
|
229 | "version": "11"
|
230 | },
|
231 | {
|
232 | "browserName": "safari",
|
233 | "platform": "OS X 10.11",
|
234 | "version": "9"
|
235 | }
|
236 | ]
|
237 | }
|
238 | }
|
239 | }
|
240 | ```
|
241 |
|
242 | For more information on Sauce configuration, [see their Wiki](https://wiki.saucelabs.com/display/DOCS/Test+Configuration+Options#TestConfigurationOptions-RequiredSeleniumTestConfigurationSettings)
|
243 |
|
244 | Requesting that plugin via `--plugin` on the command line (or overriding the
|
245 | plugin's configuration to `disabled: false`) will cause the plugin to kick in.
|
246 |
|
247 | ## Variant dependencies
|
248 |
|
249 | Sometimes you want to run your project's tests against different versions of
|
250 | your dependencies. For example, suppose there was a significant change in
|
251 | paper-button version `v1.5` and you want to confirm that your code works with
|
252 | `v1.4` and `v1.5`.
|
253 |
|
254 | WCT will serve from the `bower_components` directory in your project's root
|
255 | directory as siblings of your project's root directory. So if you depend on
|
256 | paper-button, you can import it with the url
|
257 | `../paper-button/paper-button.html`.
|
258 |
|
259 | For each directory that WCT detects with a name like
|
260 | `bower_components-${variantName}`, it will also run your tests separately
|
261 | against that variant of your dependencies. So you could use the [`directory`
|
262 | environment variable](https://bower.io/docs/config/) option with bower to set
|
263 | up a `bower_components-button-v1.4` directory while developing. WCT would
|
264 | notice that directory and run your tests in two different variations, one where
|
265 | `../paper-button/paper-button.html` gets `v1.4`, the other where it gets
|
266 | `v1.5`.
|
267 |
|
268 | This is implemented by starting one test server per variant, and one copy of each launched browser per test server.
|
269 |
|
270 | # Nitty Gritty
|
271 |
|
272 | ## Polymer
|
273 |
|
274 | By default, WCT will defer tests until `WebComponentsReady` has fired. This
|
275 | saves you from having to wait for elements to upgrade and all that yourself.
|
276 |
|
277 | If you need to test something that occurs before that event, the [`testImmediate` helper](https://github.com/Polymer/web-component-tester/blob/master/browser/environment/helpers.js#L29-41) can be used. Or, if you just want tests to run as soon as possible, you can disable the delay by setting `WCT.waitForFrameworks = false` (though, they are still async due to Mocha).
|
278 |
|
279 |
|
280 | ## Mocha
|
281 |
|
282 | WCT supports Mocha's [TDD][mocha-tdd] (`suite`/`test`/etc) and [BDD][mocha-bdd]
|
283 | (`describe`/`it`/etc) interfaces, and will call `mocha.setup`/`mocha.run` for
|
284 | you. Just write your tests, and you're set.
|
285 |
|
286 |
|
287 | ## Chai
|
288 |
|
289 | Similarly, Chai's [`expect`][chai-bdd] and [`assert`][chai-tdd] interfaces are
|
290 | exposed for your convenience.
|
291 |
|
292 |
|
293 | ## Custom Environments
|
294 |
|
295 | If you would rather not load WCT's shared environment, or want to have WCT
|
296 | load additional libraries, you can override the list of scripts loaded. There
|
297 | are two ways of doing this:
|
298 |
|
299 | Inside your test code (before `browser.js` is loaded):
|
300 | ```html
|
301 | <script>
|
302 | WCT = {
|
303 | environmentScripts: [
|
304 | // Mocha and Stacky are required dependencies
|
305 | 'stacky/lib/parsing.js',
|
306 | 'stacky/lib/formatting.js',
|
307 | 'stacky/lib/normalization.js',
|
308 | 'mocha/mocha.js',
|
309 | // Include anything else that you like!
|
310 | ],
|
311 | };
|
312 | ```
|
313 |
|
314 | Alternatively, you can specify these options via the `clientOptions`
|
315 | key in `wct.conf.json`.
|
316 |
|
317 | A reference of the default configuration can be found at
|
318 | [browser/config.js](browser/config.js).
|
319 |
|
320 |
|
321 | ## Gulp
|
322 |
|
323 | We also provide Gulp tasks for your use. `gulpfile.js`:
|
324 |
|
325 | ```js
|
326 | var gulp = require('gulp');
|
327 | require('web-component-tester').gulp.init(gulp, [dependencies]);
|
328 | ```
|
329 |
|
330 | Exposes `gulp test:local` and `gulp test:remote`, which depend on the optional
|
331 | `dependencies`.
|
332 |
|
333 |
|
334 | ## Grunt
|
335 |
|
336 | Or, Grunt tasks, if you prefer. `gruntfile.js`:
|
337 |
|
338 | ```js
|
339 | grunt.initConfig({
|
340 | 'wct-test': {
|
341 | local: {
|
342 | options: {remote: false},
|
343 | },
|
344 | remote: {
|
345 | options: {remote: true},
|
346 | },
|
347 | chrome: {
|
348 | options: {browsers: ['chrome']},
|
349 | },
|
350 | },
|
351 | });
|
352 |
|
353 | grunt.loadNpmTasks('web-component-tester');
|
354 | ```
|
355 |
|
356 | Gives you two grunt tasks: `wct-test:local` and `wct-test:remote`. The
|
357 | `options` you can use are specified in [`runner/config.ts`](runner/config.ts).
|
358 |
|
359 |
|
360 | # Plugin Authoring
|
361 |
|
362 | A plugin is a node module that can hook into various steps of WCT's flow. It
|
363 | looks like this:
|
364 |
|
365 | `package.json`:
|
366 | ```js
|
367 | {
|
368 | // ...
|
369 | "wct-plugin": {
|
370 | "cli-options": {
|
371 | // ... option configuration (nomnom)
|
372 | }
|
373 | }
|
374 | }
|
375 | ```
|
376 |
|
377 | `plugin.js` (the plugin's main module)
|
378 | ```js
|
379 | module.exports = function(context, pluginOptions, plugin) {
|
380 | // ...
|
381 | };
|
382 | ```
|
383 |
|
384 | The plugin can subscribe to hooks via the [`Context`](runner/context.ts)
|
385 | object. Any options (via wct.conf.json or command line) are merged into
|
386 | `pluginOptions`. And, `plugin` is the instance of [`Plugin`](runner/plugin.ts)
|
387 | for the plugin.
|
388 |
|
389 | [wct-local](https://github.com/Polymer/wct-local) and
|
390 | [wct-sauce](https://github.com/Polymer/wct-sauce) are example plugins you can
|
391 | follow.
|
392 |
|
393 |
|
394 | ### Node support
|
395 |
|
396 | WCT supports node versions 6 and up.
|
397 |
|
398 | WCT experimentally supports running tests for web-components which are installed via npm to `node_modules` (instead of via bower to `bower_components`) by use of an `--npm` flag. Components which wish to support npm-based installation should include `wct-browser-legacy` in their `devDependencies`, which is a package that contains only the client-side javascript necessary for executing WCT tests in an npm-based environment.
|
399 |
|
400 |
|
401 |
|
402 | [async]: https://github.com/caolan/async "Async.js"
|
403 | [chai-bdd]: http://chaijs.com/api/bdd/ "Chai's BDD Interface"
|
404 | [chai-tdd]: http://chaijs.com/api/assert/ "Chai's TDD Interface"
|
405 | [chai]: http://chaijs.com/ "Chai Assertion Library"
|
406 | [java]: https://java.com/download "Java"
|
407 | [mocha-bdd]: http://mochajs.org/#bdd-interface "Mocha's BDD Interface"
|
408 | [mocha-tdd]: http://mochajs.org/#tdd-interface "Mocha's TDD Interface"
|
409 | [mocha]: http://mochajs.org/ "Mocha Test Framework"
|
410 | [sauce]: http://saucelabs.com "Sauce Labs"
|
411 | [opensauce]: https://saucelabs.com/opensauce "Open Sauce Testing"
|
412 | [lodash]: https://lodash.com/ "Lo-Dash"
|
413 | [sinon]: http://sinonjs.org/ "Sinon.JS"
|
414 | [sinon-chai]: https://github.com/domenic/sinon-chai "Chai assertions for Sinon"
|
415 | [test-fixture]: https://github.com/PolymerElements/test-fixture "Easy DOM fixture testing"
|
416 | [a11ydevtools]: https://github.com/GoogleChrome/accessibility-developer-tools "A collection of audit rules checking for common accessibility problems, and an API for running these rules in an HTML page."
|