Switch branches/tags
web-component-tester@6.9.0 web-component-tester@6.9.0-pre.1 web-component-tester@6.8.0 web-component-tester@6.7.1 web-component-tester@6.7.0 web-component-tester@6.6.0 wct-sauce@2.1.0 wct-sauce@2.0.3 wct-sauce@2.0.2 wct-mocha@1.0.0 wct-mocha@1.0.0-pre.3 wct-mocha@1.0.0-pre.2 wct-local@2.1.3 wct-local@2.1.2 wct-local@2.1.1 wct-browser-legacy@1.0.2 wct-browser-legacy@1.0.1 wct-browser-legacy@1.0.0 v0.0.20131107 v0.0.20131025 v0.0.20131010 v0.0.20131003 v0.0.20130912 v0.0.20130905 v0.0.20130829 polyserve@0.27.13 polyserve@0.27.12 polyserve@0.27.11 polyserve@0.27.10 polyserve@0.27.9 polyserve@0.27.8 polyserve@0.27.7 polyserve@0.27.6 polyserve@0.27.5 polyserve@0.27.4 polyserve@0.27.3 polyserve@0.27.2 polyserve@0.27.1 @polymer/tools-common@2.0.1 @polymer/gen-typescript-declarations@1.5.1 @polymer/gen-typescript-declarations@1.5.0 @polymer/esm-amd-loader@1.0.3 @polymer/esm-amd-loader@1.0.2 @polymer/esm-amd-loader@1.0.1 @polymer/esm-amd-loader@1.0.0 @polymer/esm-amd-loader@0.1.1 @polymer/esm-amd-loader@0.1.0 polymer-workspaces@2.2.0 polymer-project-config@4.0.2 polymer-project-config@4.0.1 polymer-project-config@4.0.0 polymer-project-config@3.14.0 polymer-modulizer@0.4.1 polymer-linter@3.0.1 polymer-linter@3.0.0 polymer-linter@3.0.0-pre.7 polymer-linter@3.0.0-pre.6 polymer-editor-service@2.2.2 polymer-editor-service@2.2.1 polymer-cli@1.9.1 polymer-cli@1.9.0 polymer-cli@1.9.0-pre.2 polymer-cli@1.9.0-pre.1 polymer-cli@1.8.1 polymer-cli@1.8.0 polymer-cli@1.7.7 polymer-cli@1.7.6 polymer-cli@1.7.4 polymer-cli@1.7.3 polymer-cli@1.7.1 polymer-cli@1.7.0 polymer-cli@1.7.0-pre.17 polymer-cli@1.7.0-pre.16 polymer-cli@1.7.0-pre.15 polymer-cli@1.7.0-pre.14 polymer-cli@1.7.0-pre.13 polymer-cli@1.7.0-pre.12 polymer-cli@1.7.0-pre.11 polymer-cli@1.7.0-pre.10 polymer-cli@1.7.0-pre.9 polymer-cli@1.7.0-pre.8 polymer-cli@1.7.0-pre.7 polymer-cli@1.7.0-pre.6 polymer-cli@1.7.0-pre.5 polymer-bundler@4.0.4 polymer-bundler@4.0.3 polymer-bundler@4.0.2 polymer-bundler@4.0.0 polymer-bundler@4.0.0-pre.7 polymer-bundler@4.0.0-pre.6 polymer-bundler@4.0.0-pre.5 polymer-build@3.1.1 polymer-build@3.1.0 polymer-build@3.0.4 polymer-build@3.0.3 polymer-build@3.0.2 polymer-build@3.0.0 polymer-build@3.0.0-pre.17 polymer-build@3.0.0-pre.16 polymer-build@3.0.0-pre.15
Nothing to show
Find file History
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Add 'packages/web-component-tester/' from commit 'e5e980593fba8e2d484… Apr 17, 2018
.vscode Add 'packages/web-component-tester/' from commit 'e5e980593fba8e2d484… Apr 17, 2018
bin Remove unused callback argument to wct.cli.run and wct.cli.startSauce… Jun 13, 2018
browser wct-browser-legacy integration tests (#692) Sep 10, 2018
custom_typings Use native Node promisify, to avoid issues with Node 10 (#527) Jun 20, 2018
data [web-component-tester] Support wct-mocha and don't require explicit "… Sep 18, 2018
runner Updated web-component-tester to support wct-mocha/wct-mocha.js instea… Oct 15, 2018
tasks Add 'packages/web-component-tester/' from commit 'e5e980593fba8e2d484… Apr 17, 2018
test Updated package locks and goldens in preparation for cli and build re… Nov 12, 2018
.gitignore Reporter retry-failures-reporter.ts is now much more well-behaved and… Oct 9, 2018
.npmignore Add 'packages/web-component-tester/' from commit 'e5e980593fba8e2d484… Apr 17, 2018
CHANGELOG.md Prepare releases of CLI (prerelease) and WCT (official release) (#760) Oct 25, 2018
LICENSE Add 'packages/web-component-tester/' from commit 'e5e980593fba8e2d484… Apr 17, 2018
README.md [web-component-tester] Support wct-mocha and don't require explicit "… Sep 18, 2018
a11ySuiteExample.png Add 'packages/web-component-tester/' from commit 'e5e980593fba8e2d484… Apr 17, 2018
bower.json Add 'packages/web-component-tester/' from commit 'e5e980593fba8e2d484… Apr 17, 2018
browser-js-header.txt Add 'packages/web-component-tester/' from commit 'e5e980593fba8e2d484… Apr 17, 2018
browser.js wct-browser-legacy integration tests (#692) Sep 10, 2018
browser.js.map wct-browser-legacy integration tests (#692) Sep 10, 2018
gulpfile.js Brought in cleankill as well to resolve the 'two cleankills === fail-… Jun 7, 2018
mocha.opts Standardize mocha scripts (#267) Apr 28, 2018
package-lock.json Updated CHANGELOG and package files for release of browser-capabiliti… Nov 15, 2018
package.json Updated package locks and goldens in preparation for cli and build re… Nov 12, 2018
runner.js Add 'packages/web-component-tester/' from commit 'e5e980593fba8e2d484… Apr 17, 2018
tsconfig.json Apply the no-any lint rule to every repo except WCT (#177) Apr 20, 2018
tslint.json Apply the no-any lint rule to every repo except WCT (#177) Apr 20, 2018


NPM version Build Status Gitter

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

Note that it is critical that you include ../web-component-tester/browser.js in your test suites. browser.js contains all of WCT's client logic (and loads bundled libraries like mocha and chai). You can also load it from the absolute URL /components/web-component-tester/browser.js.

.js Suites

Alternatively, you can write tests in separate .js sources. For example, test/awesome-tests.js:

suite('AwesomeLib', function() {
  test('is awesome', function() {

Special Features


test-fixture can be used to reset DOM state between test runs.

<test-fixture id="simple">
 suite('classList', () => {
   let div;
   setup(() => {
     div = fixture('simple');
   test('foo', () => {
   test('bar', () => {

a11ySuite(fixureId, ignoredTests, beforeEach)

Parameter Type Descrption
fixtureId String ID of the fixture to instantiate and test
ignoredTests Array (optional) Tests to ignore.
Test names are found here as calls to axs.AuditRules.addRule()
beforeEach Function (optional) Called before each test is run

a11ySuite provides an simple way to run accessibility-developer-tools' high quality accessibility audits when given a test-fixture. The a11ySuite will show all the audit results via the standard Mocha test output.

<test-fixture id="NoLabel">
    <paper-radio-button id="radio-1"></paper-radio-button>


Accessibility Suite Test Run

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 override this by specifying particular files (or globs of files) via wct path/to/files.

Web Server

If you prefer not to use WCT's command line tool, you can also run WCT tests directly in a browser via a web server of your choosing.

Make sure that WCT's browser.js is accessible by your web server, and have your tests load browser.js.

The recommended way to fetch these is 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-lite.js"></script>
    <script src="../../web-component-tester/browser.js"></script>
    <script src="../awesome.js"></script>

When you use wct on the command line, it is generating an index like this for you based on the suites you ask it to load.


The wct command line tool will pick up custom configuration from a wct.conf.json file located in the root of your project. Or, you can specify your own file via the --config-file command line option. Example: --config-file my.wct.conf.js If you define your own configuration file, make sure you also provide the correct root if needed. 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.

It should export the custom configuration:

  "verbose": true,
  "plugins": {
    "local": {
      "browsers": ["chrome", "firefox"]

See runner/config.ts 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.json.


Note that by specifying a plugin's configuration, you are letting WCT know that it should load that plugin. If you wish to provide default configuration for a plugin, but not enable it, you can have it default to disabled:

Requesting that plugin via --plugin on the command line (or overriding the plugin's configuration to disabled: false) will cause the plugin to kick in.


The sauce plugin runs your tests on Sauce.

To use the sauce plugin you need to include credentials. To do this, either set the SAUCE_USERNAME and SAUCE_ACCESS_KEY environment variables, or set the username and accessKey fields in the plugins.sauce section of your wct.conf.json.

You can configure the browsers that Sauce will run by setting the browsers array in the plugin configuration. The options are the same as the ones documented on the Sauce Wiki here. For example:

  "plugins": {
    "sauce": {
      "browsers": [{
          "browserName": "microsoftedge",
          "platform": "Windows 10",
          "version": ""
        }, {
          "browserName": "internet explorer",
          "platform": "Windows 8.1",
          "version": "11"
          "browserName": "safari",
          "platform": "OS X 10.11",
          "version": "9"

Variant dependencies

Sometimes you want to run your project's tests against different versions of your dependencies. For example, suppose there was a significant change in paper-button version v1.5 and you want to confirm that your code works with v1.4 and v1.5.

WCT will serve from the bower_components directory in your project's root directory as siblings of your project's root directory. So if you depend on paper-button, you can import it with the url ../paper-button/paper-button.html.

For each directory that WCT detects with a name like bower_components-${variantName}, it will also run your tests separately against that variant of your dependencies. So you could use the directory environment variable option with bower to set up a bower_components-button-v1.4 directory while developing. WCT would notice that directory and run your tests in two different variations, one where ../paper-button/paper-button.html gets v1.4, the other where it gets v1.5.

This is implemented by starting one test server per variant, and one copy of each launched browser per test server.

Nitty Gritty


By default, WCT will defer tests until WebComponentsReady 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/mocha.run for you. Just write your tests, and you're set.


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

Custom Environments

If you would rather not load WCT's shared environment, or want to have WCT load additional libraries, you can override the list of scripts loaded. There are two ways of doing this:

Inside your test code (before browser.js is loaded):

  WCT = {
    environmentScripts: [
      // Mocha and Stacky are required dependencies
      // Include anything else that you like!

Alternatively, you can specify these options via the clientOptions key in wct.conf.json.

A reference of the default configuration can be found at browser/config.ts.


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

var gulp = require('gulp');
require('web-component-tester').gulp.init(gulp, [dependencies]);

Exposes gulp test:local and gulp test:remote, which depend on the optional dependencies.


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.ts.

Plugin Authoring

A plugin is a node module that can hook into various steps of WCT's flow. It 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.json 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.

Node support

WCT supports node versions 8 and up.

WCT 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. WCT will attempt to identify which package provides the client-side code by checking for compatible packages in the following order of preference: wct-mocha, wct-browser-legacy and web-component-tester. If you want to specify which package provides WCT client-side code, use the --wct-package-name flag or wctPackageName option in wct.conf.json with the npm package name.