Package Exports

web-component-tester
web-component-tester/runner/config.js
web-component-tester/runner/test

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (web-component-tester) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

web-component-tester makes testing your web components a breeze!

You get a browser-based testing environment, configured out of the box with:

Mocha as a test framework.
Chai assertions.
Async to keep your sanity.
Lodash (3.0) to repeat fewer things.
Sinon and sinon-chai to test just your things.

WCT will run your tests against whatever browsers you have locally installed, or remotely via Sauce Labs.

Getting Started

`.html` Suites

Your test suites can be .html documents. For example, test/awesomest-tests.html:

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <script src="../../webcomponentsjs/webcomponents.min.js"></script>
  <script src="../../web-component-tester/browser.js"></script>
  <link rel="import" href="../awesome-element.html">
</head>
<body>
  <awesome-element id="fixture"></awesome-element>
  <script>
    suite('<awesome-element>', function() {
      test('is awesomest', function() {
        assert.isTrue(document.getElementById('fixture').awesomest);
      });
    });
  </script>
</body>
</html>

`.js` Suites

Or, you can write tests in separate .js sources, which run in the context of your text index. For example, test/awesome-tests.js:.

suite('AwesomeLib', function() {
  test('is awesome', function() {
    assert.isTrue(AwesomeLib.awesome);
  });
});

Running Your Tests

`wct`

The easiest way to run your tests is via the wct command line tool. Install it globally via:

npm install -g web-component-tester

Make sure that you also have Java installed and available on your PATH.

The wct tool will run your tests in all the browsers you have installed. Just run it:

wct

By default, any tests under test/ will be run. You can run particular files (or globs of files) via wct path/to/files.

Web Server

Alternatively, you can run your tests directly by hosting them via a web server (sorry, file:// is not supported). You'll need to save WCT's browser.js in order to go this route. The recommended approach is to depend on WCT via Bower:

bower install Polymer/web-component-tester --save

Nested Suites

To help support this case, you can also directly define an index that will load any desired tests:

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <script src="../../webcomponentsjs/webcomponents.min.js"></script>
    <script src="../../web-component-tester/browser.js"></script>
    <script src="../awesome.js"></script>
  </head>
  <body>
    <script>
      WCT.loadSuites([
        'awesome-tests.js',
        'awesomest-tests.html',
      ]);
    </script>
  </body>
</html>

Configuration

The wct command line tool will pick up custom configuration from a wct.conf.js file located in the root of your project. It should export the custom configuration:

module.exports = {
  verbose: true,
  sauce: {
    username 'boo',
  },
};

See runner/config.js for the canonical reference of configuration properties.

You can also specify global defaults (such as sauce.username, etc) via a config file located at ~/wct.conf.js.

Nitty Gritty

Mocha

WCT supports Mocha's TDD (suite/test/etc) and BDD (describe/it/etc) interfaces, and will call mocha.setup/mocha.run for you. Just write your tests, and you're set.

Chai

Similarly, Chai's expect and assert interfaces are exposed for your convenience.

Command Line

The wct tool, and the gulp and grunt integration, support several command line flags:

--remote: Uses the default remote browsers, and if omitted uses the default local browsers.

Note that you will need a valid Sauce Labs account for this. Let WCT know your credentials via envrionment variables:

export SAUCE_USERNAME=username
export SAUCE_ACCESS_KEY=abcdef01-abcd-abcd-abcd-abcdef012345

--browsers BROWSER,BROWSER: Override the browsers that will be run. Browsers can be specified via local names such as chrome, canary, firefox, aurora, ie, etc. Remote browsers can be specified via <PLATFORM>/<BROWSER>[@<VERSION>].

--persistent: Doesn't close the browsers after their first run. Refresh the browser windows to re-run tests.

Custom Environments

If you would rather not load WCT's shared environment (everything but Mocha is optional), you've got a couple options: Set the WCTSkipEnvironment = true before loading browser.js. Or...

<script src="../../web-component-tester/browser.js?skipEnv"></script>

Gulp

We also provide Gulp tasks for your use. gulpfile.js:

var gulp = require('gulp');
require('web-component-tester').gulp.init(gulp);

Exposes gulp test:local and gulp test:remote.

Grunt

Or, Grunt tasks, if you prefer. gruntfile.js:

grunt.initConfig({
  'wct-test': {
    local: {
      options: {remote: false},
    },
    remote: {
      options: {remote: true},
    },
    chrome: {
      options: {browsers: ['chrome']},
    },
  },
});

grunt.loadNpmTasks('web-component-tester');

Gives you two grunt tasks: wct-test:local and wct-test:remote. The options you can use are specified in runner/config.js.

web-component-tester