No description, website, or topics provided.
Clone or download
Pull request Compare This branch is 624 commits behind Polymer:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

NPM version Build Status

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

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

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>
  <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">
  <awesome-element id="fixture"></awesome-element>
    suite('<awesome-element>', function() {
      test('is awesomest', function() {

.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() {

Running Your Tests


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:


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>
    <meta charset="utf-8">
    <script src="../../webcomponentsjs/webcomponents.min.js"></script>
    <script src="../../web-component-tester/browser.js"></script>
    <script src="../awesome.js"></script>


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


By default, WCT will defer tests until polymer-ready has fired. This saves you from having to wait for elements to upgrade and all that yourself.

If you need to test something that occurs before that event, the testImmediate helper 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).


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


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>


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

var gulp = require('gulp');

Exposes gulp test:local and gulp test:remote.


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

  'wct-test': {
    local: {
      options: {remote: false},
    remote: {
      options: {remote: true},
    chrome: {
      options: {browsers: ['chrome']},


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


WCT also supports plugins. A plugin is a node module that can hook into various steps of WCT's flow.

A plugin looks like this:


  "wct-plugin": {
    "cli-options": {
      ... option configuration (nomnom)

plugin.js (the plugin's main module)

module.exports = function(context, pluginOptions, plugin) {
  // ...

The plugin can subscribe to hooks via the Context object. Any options (via wct.conf.js or command line) are merged into pluginOptions. And, plugin is the instance of Plugin for the plugin.

wct-local and wct-sauce are example plugins you can follow.