or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

browser-environment.mdbuild-tools.mdcli.mdconfiguration.mdindex.mdplugin-system.mdtest-runner.md
tile.json

tessl/npm-web-component-tester

A comprehensive testing framework specifically designed for web components with browser-based testing environment, Mocha/Chai/Sinon integration, and support for both local and remote testing via Sauce Labs.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/web-component-tester@6.9.x

To install, run

npx @tessl/cli install tessl/npm-web-component-tester@6.9.0

index.mddocs/

Web Component Tester

Web Component Tester makes testing your web components a breeze! It provides a comprehensive testing framework specifically designed for web components, offering a browser-based testing environment preconfigured with essential testing libraries including Mocha for test framework, Chai for assertions, Sinon for mocking, and test-fixture for DOM fixture management.

Package Information

  • Package Name: web-component-tester
  • Package Type: npm
  • Language: TypeScript/JavaScript
  • Installation: npm install -g web-component-tester or npm install --save-dev web-component-tester

Core Imports

Node.js API

const wct = require('web-component-tester');

ES6 modules:

import { cli, config, gulp, steps, test } from 'web-component-tester';

Browser API

The browser client is automatically loaded via browser.js:

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

Basic Usage

Command Line

# Install globally
npm install -g web-component-tester

# Run tests in current directory
wct

# Run specific test files
wct test/my-element-test.html test/other-test.js

# Run with specific browsers
wct --local chrome --local firefox

HTML Test Suite

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <script src="../../webcomponentsjs/webcomponents-lite.js"></script>
  <script src="../../web-component-tester/browser.js"></script>
  <link rel="import" href="../my-element.html">
</head>
<body>
  <test-fixture id="basic">
    <template>
      <my-element></my-element>
    </template>
  </test-fixture>
  
  <script>
    suite('<my-element>', function() {
      let element;
      
      setup(function() {
        element = fixture('basic');
      });
      
      test('is instantiated', function() {
        assert.equal(element.is, 'my-element');
      });
    });
  </script>
</body>
</html>

JavaScript Test Suite

suite('MyLibrary', function() {
  test('has expected API', function() {
    assert.isFunction(MyLibrary.doSomething);
    assert.isObject(MyLibrary.config);
  });
  
  test('handles async operations', function(done) {
    MyLibrary.asyncOperation().then(function(result) {
      assert.equal(result.status, 'success');
      done();
    });
  });
});

Architecture

Web Component Tester is built around several key components:

  • Command Line Interface: Global wct command for running tests from terminal
  • Node.js Runner: Programmatic API for test execution and configuration
  • Browser Environment: Client-side testing runtime with pre-loaded libraries
  • Plugin System: Extensible architecture supporting local and remote testing
  • Configuration System: Flexible configuration via files, command line, and programmatic API
  • Build Tool Integration: Native support for Gulp and Grunt workflows

Capabilities

Command Line Interface

Primary interface for running tests with support for various browsers, configuration options, and CI/CD integration.

function run(env: any, args: string[], output: NodeJS.WritableStream): Promise<void>;
function runSauceTunnel(env: any, args: string[], output: NodeJS.WritableStream): Promise<void>;

Command Line Interface

Test Runner API

Programmatic API for running test suites with full configuration control and event-based progress tracking.

function test(options: Config | Context): Promise<void>;

interface Config {
  suites?: string[];
  verbose?: boolean;
  root?: string;
  testTimeout?: number;
  persistent?: boolean;
  activeBrowsers?: BrowserDef[];
  plugins?: {[key: string]: any};
}

Test Runner

Browser Testing Environment

Client-side testing environment with pre-loaded testing libraries and web component-specific utilities.

interface WCT {
  loadSuites(files: string[]): void;
  share: any;
  _config: Config;
}

// Global helper functions
function flush(callback: () => void): void;
function testImmediate(name: string, testFn: Function): void;
function safeStep(callback: (error?: any) => void, stepFn: () => void): void;

Browser Environment

Configuration System

Comprehensive configuration system supporting file-based, programmatic, and command-line configuration with plugin support.

interface Config {
  suites?: string[];
  output?: NodeJS.WritableStream;
  ttyOutput?: boolean;
  verbose?: boolean;
  quiet?: boolean;
  root?: string;
  testTimeout?: number;
  persistent?: boolean;
  clientOptions?: {
    root?: string;
    verbose?: boolean;
    environmentScripts?: string[];
  };
}

function merge(options: Config, overrides: Config): Config;
function expand(context: Context): Promise<void>;
function validate(options: Config): Promise<void>;

Configuration

Build Tool Integration

Native integration with Gulp and Grunt build systems for seamless testing workflow integration.

// Gulp integration
function init(gulp: Gulp, dependencies?: string[]): void;

// Grunt integration
function registerMultiTask(grunt: any): void;

Build Tools

Plugin System

Extensible plugin architecture for adding custom functionality, browser support, and testing environments.

interface Plugin {
  execute(context: Context): Promise<void>;
  cliConfig: any;
}

class Context extends EventEmitter {
  emitHook(name: string): Promise<void>;
  plugins(): Promise<Plugin[]>;
}

Plugin System

Test Execution Steps

Core test execution pipeline functions that orchestrate the testing process from setup to cleanup.

function setupOverrides(context: Context): Promise<void>;
function loadPlugins(context: Context): Promise<Plugin[]>;
function configure(context: Context): Promise<void>;
function prepare(context: Context): Promise<void>;
function runTests(context: Context): Promise<void>;
function cancelTests(context: Context): void;

Types

type Browser = string | {browserName: string, platform: string};

interface BrowserDef extends Browser {
  id?: number;
  variant?: string;
}

interface Context extends EventEmitter {
  options: Config;
  
  // Hook methods
  hook(name: string, handler: Handler): void;
  hookLate(name: string, handler: Handler): void;
  emitHook(name: string): Promise<void>;
  
  // Plugin methods
  plugins(): Promise<Plugin[]>;
  enabledPlugins(): string[];
  pluginOptions(name: string): any;
}

type Handler = 
  ((...args: any[]) => Promise<any>) |
  ((done: (err?: any) => void) => void) |
  ((arg1: any, done: (err?: any) => void) => void) |
  ((arg1: any, arg2: any, done: (err?: any) => void) => void) |
  ((arg1: any, arg2: any, arg3: any, done: (err?: any) => void) => void);

interface ValidationResult<T> {
  isValid: boolean;
  data: T; 
  errors: ValidationError[];
}

interface TestStats {
  passed: number;
  pending: number;
  failed: number;
  total: number;
}

interface Plugin {
  name: string;
  packageName: string;
  cliConfig: any;
  metadata: any;
  execute(context: Context): Promise<void>;
}

interface MutationEl {
  onMutation(mutationEl: this, cb: () => void): void;
}