UNPKG

13.2 kBMarkdownView Raw
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
7You 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
17WCT 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
24Your 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
49Note that it is _critical_ that you include `../web-component-tester/browser.js`
50in your test suites. `browser.js` contains all of WCT's client logic (and loads
51bundled 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
55Alternatively, you can write tests in separate `.js` sources. For example,
56`test/awesome-tests.js`:
57
58```js
59suite('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
101audits when given a `test-fixture`.
102The `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
120The easiest way to run your tests is via the `wct` command line tool. Install
121it globally via:
122
123```sh
124npm install -g web-component-tester
125```
126
127Make sure that you also have [Java][java] installed and available on your
128`PATH`.
129
130The `wct` tool will run your tests in all the browsers you have installed. Just
131run it:
132
133```sh
134wct
135```
136
137By default, any tests under `test/` will be run. You can override this by
138specifying particular files (or globs of files) via `wct path/to/files`.
139
140
141### Web Server
142
143If you prefer not to use WCT's command line tool, you can also run WCT tests
144directly in a browser via a web server of your choosing.
145
146Make sure that WCT's `browser.js` is accessible by your web server, and have
147your tests load `browser.js`.
148
149The recommended way to fetch these is via Bower:
150
151 bower install Polymer/web-component-tester --save
152
153
154#### Nested Suites
155
156To help support this case, you can also directly define an index that will load
157any 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
180you based on the suites you ask it to load._
181
182
183# Configuration
184
185The `wct` command line tool will pick up custom configuration from a
186`wct.conf.json` file located in the root of your project.
187Or, you can specify your own file via the `--configFile` command line option.
188Example: `--configFile my.wct.conf.js`
189If you define your own configuration file, make sure you also provide the correct root if needed.
190By 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
205See [`runner/config.ts`](runner/config.ts) for the canonical reference of
206configuration properties.
207
208You can also specify global defaults (such as `sauce.username`, etc) via a
209config file located at `~/wct.conf.json`.
210
211## Plugins
212
213Note that by specifying a plugin's configuration, you are letting WCT know that
214it should load that plugin. If you wish to provide default configuration for a
215plugin, 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
242For more information on Sauce configuration, [see their Wiki](https://wiki.saucelabs.com/display/DOCS/Test+Configuration+Options#TestConfigurationOptions-RequiredSeleniumTestConfigurationSettings)
243
244Requesting that plugin via `--plugin` on the command line (or overriding the
245plugin's configuration to `disabled: false`) will cause the plugin to kick in.
246
247## Variant dependencies
248
249Sometimes you want to run your project's tests against different versions of
250your dependencies. For example, suppose there was a significant change in
251paper-button version `v1.5` and you want to confirm that your code works with
252`v1.4` and `v1.5`.
253
254WCT will serve from the `bower_components` directory in your project's root
255directory as siblings of your project's root directory. So if you depend on
256paper-button, you can import it with the url
257`../paper-button/paper-button.html`.
258
259For each directory that WCT detects with a name like
260`bower_components-${variantName}`, it will also run your tests separately
261against that variant of your dependencies. So you could use the [`directory`
262environment variable](https://bower.io/docs/config/) option with bower to set
263up a `bower_components-button-v1.4` directory while developing. WCT would
264notice 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
268This 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
274By default, WCT will defer tests until `WebComponentsReady` has fired. This
275saves you from having to wait for elements to upgrade and all that yourself.
276
277If 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
282WCT 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
284you. Just write your tests, and you're set.
285
286
287## Chai
288
289Similarly, Chai's [`expect`][chai-bdd] and [`assert`][chai-tdd] interfaces are
290exposed for your convenience.
291
292
293## Custom Environments
294
295If you would rather not load WCT's shared environment, or want to have WCT
296load additional libraries, you can override the list of scripts loaded. There
297are two ways of doing this:
298
299Inside 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
314Alternatively, you can specify these options via the `clientOptions`
315key in `wct.conf.json`.
316
317A reference of the default configuration can be found at
318[browser/config.js](browser/config.js).
319
320
321## Gulp
322
323We also provide Gulp tasks for your use. `gulpfile.js`:
324
325```js
326var gulp = require('gulp');
327require('web-component-tester').gulp.init(gulp, [dependencies]);
328```
329
330Exposes `gulp test:local` and `gulp test:remote`, which depend on the optional
331`dependencies`.
332
333
334## Grunt
335
336Or, Grunt tasks, if you prefer. `gruntfile.js`:
337
338```js
339grunt.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
353grunt.loadNpmTasks('web-component-tester');
354```
355
356Gives 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
362A plugin is a node module that can hook into various steps of WCT's flow. It
363looks 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
379module.exports = function(context, pluginOptions, plugin) {
380 // ...
381};
382```
383
384The plugin can subscribe to hooks via the [`Context`](runner/context.ts)
385object. Any options (via wct.conf.json or command line) are merged into
386`pluginOptions`. And, `plugin` is the instance of [`Plugin`](runner/plugin.ts)
387for 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
391follow.
392
393
394### Node support
395
396WCT supports node versions 6 and up.
397
398WCT 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<!-- References -->
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."