CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

—

Pending
Overview
Eval results
Files

configuration.mddocs/

Configuration

Web Component Tester provides a comprehensive configuration system supporting file-based, programmatic, and command-line configuration with plugin support and environment-specific settings.

Capabilities

Configuration Merging

Merge configuration objects with deep merging support for nested options.

/**
 * Merge configuration options with deep merging for nested objects
 * @param options - Base configuration object
 * @param overrides - Configuration overrides to merge
 * @returns Merged configuration object
 */
function merge(options: Config, overrides: Config): Config;

Usage Examples:

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

const baseConfig = {
  verbose: false,
  plugins: {
    local: { browsers: ['chrome'] }
  }
};

const overrides = {
  verbose: true,
  plugins: {
    local: { browsers: ['chrome', 'firefox'] },
    sauce: { username: 'test-user' }
  }
};

const finalConfig = wct.config.merge(baseConfig, overrides);
// Result: {
//   verbose: true,
//   plugins: {
//     local: { browsers: ['chrome', 'firefox'] },
//     sauce: { username: 'test-user' }
//   }
// }

Configuration Expansion

Expand and normalize configuration options with default values and plugin loading.

/**
 * Expand configuration with defaults and plugin-specific settings
 * @param context - Test execution context
 * @returns Promise that resolves when expansion is complete
 */
function expand(context: Context): Promise<void>;

Configuration Validation

Validate configuration options and ensure all required settings are present.

/**
 * Validate configuration options and check for required settings
 * @param options - Configuration object to validate
 * @returns Promise that resolves if valid, rejects with error if invalid
 */
function validate(options: Config): Promise<void>;

Argument Parsing

Parse command line arguments into configuration objects.

/**
 * Initial argument parsing for configuration discovery
 * @param args - Command line arguments array
 * @returns Partial configuration object
 */
function preparseArgs(args: string[]): Partial<Config>;

/**
 * Full argument parsing with plugin support
 * @param context - Test execution context
 * @param args - Command line arguments array
 * @returns Promise that resolves when parsing is complete
 */
function parseArgs(context: Context, args: string[]): Promise<void>;

Configuration Files

wct.conf.json Format

The main configuration file format with comprehensive options:

{
  "suites": ["test/**/*.html", "test/**/*.js"],
  "root": "./",
  "verbose": false,
  "quiet": false,
  "expanded": false,
  "testTimeout": 90000,
  "persistent": false,
  "extraScripts": [],
  "wctPackageName": "web-component-tester",
  "clientOptions": {
    "root": null,
    "verbose": false,
    "environmentScripts": [
      "stacky/browser.js",
      "mocha/mocha.js",
      "chai/chai.js"
    ],
    "environmentImports": [],
    "waitForFrameworks": true,
    "numConcurrentSuites": 1,
    "trackConsoleError": true,
    "mochaOptions": {
      "timeout": 10000,
      "ui": "bdd"
    }
  },
  "plugins": {
    "local": {
      "disabled": false,
      "browsers": ["chrome", "firefox"],
      "browserOptions": {
        "chrome": ["--headless", "--disable-gpu"],
        "firefox": ["-headless"]
      }
    },
    "sauce": {
      "disabled": true,
      "username": "${SAUCE_USERNAME}",
      "accessKey": "${SAUCE_ACCESS_KEY}",
      "tunnelId": "${SAUCE_TUNNEL_ID}",
      "browsers": [
        {
          "browserName": "chrome",
          "platform": "Windows 10",
          "version": "latest"
        },
        {
          "browserName": "firefox", 
          "platform": "macOS 10.15",
          "version": "latest"
        }
      ]
    }
  },
  "browserOptions": {
    "name": "WCT Test Run",
    "tags": ["web-components", "polymer"],
    "build": "${BUILD_NUMBER}"
  }
}

Global Configuration

User-specific global configuration at ~/wct.conf.json:

{
  "plugins": {
    "sauce": {
      "username": "your-global-username",
      "accessKey": "your-global-access-key"
    }
  }
}

Configuration File Discovery

WCT searches for configuration files in this order:

  1. File specified by --config-file argument
  2. wct.conf.json in current directory
  3. wct.conf.js in current directory (Node.js module)
  4. ~/wct.conf.json (global user configuration)

Usage Examples:

// wct.conf.js (JavaScript configuration)
module.exports = {
  suites: ['test/**/*.html'],
  plugins: {
    local: {
      browsers: process.env.CI ? ['chrome'] : ['chrome', 'firefox']
    }
  }
};

Configuration Interface

Main Configuration Object

Complete configuration interface with all available options:

interface Config {
  /** Test file patterns to run */
  suites?: string[];
  /** Output stream for results */
  output?: NodeJS.WritableStream;
  /** Enable TTY-specific formatting */
  ttyOutput?: boolean;
  /** Enable verbose logging */
  verbose?: boolean;
  /** Suppress all output */
  quiet?: boolean;
  /** Show expanded test details */
  expanded?: boolean;
  /** Root directory for tests */
  root?: string;
  /** Test timeout in milliseconds */
  testTimeout?: number;
  /** Keep browsers open after tests */
  persistent?: boolean;
  /** Additional scripts to load */
  extraScripts?: string[];
  /** Package name for WCT client code */
  wctPackageName?: string;
  /** Browser-side configuration */
  clientOptions?: ClientOptions;
  /** Active browser definitions */
  activeBrowsers?: BrowserDef[];
  /** Plugin configurations */
  plugins?: {[pluginName: string]: PluginOptions};
  /** Browser-specific options */
  browserOptions?: BrowserOptions;
  /** Skip cleanup after tests */
  skipCleanup?: boolean;
  /** Register custom hooks */
  registerHooks?: (context: Context) => void;
  /** Webserver configuration (internal) */
  webserver?: WebServerOptions;
}

Client Options

Browser-side configuration options:

interface ClientOptions {
  /** Root URL for client scripts */
  root?: string;
  /** Enable debug logging in browser */
  verbose?: boolean;
  /** Scripts to load before WCT starts */
  environmentScripts?: string[];
  /** HTML imports to load */
  environmentImports?: string[];
  /** Wait for web component frameworks */
  waitForFrameworks?: boolean;
  /** Custom wait function */
  waitFor?: Function;
  /** Concurrent suite limit */
  numConcurrentSuites?: number;
  /** Track console.error as failure */
  trackConsoleError?: boolean;
  /** Mocha setup options */
  mochaOptions?: MochaSetupOptions;
}

Plugin Options

Plugin-specific configuration interface:

interface PluginOptions {
  /** Disable this plugin */
  disabled?: boolean;
  /** Plugin-specific configuration */
  [key: string]: any;
}

interface LocalPluginOptions extends PluginOptions {
  /** Browsers to run locally */
  browsers?: string[];
  /** Browser-specific command line options */
  browserOptions?: {[browserName: string]: string[]};
  /** Skip Selenium installation */
  skipSeleniumInstall?: boolean;
}

interface SaucePluginOptions extends PluginOptions {
  /** Sauce Labs username */
  username?: string;
  /** Sauce Labs access key */
  accessKey?: string;
  /** Existing tunnel ID */
  tunnelId?: string;
  /** Browser configurations for Sauce Labs */
  browsers?: SauceBrowserDef[];
  /** Build identifier */
  build?: string;
  /** Test tags */
  tags?: string[];
}

Browser Configuration

Browser-specific configuration options:

interface BrowserOptions {
  /** Test run name */
  name?: string;
  /** Build identifier */
  build?: string;
  /** Test tags */
  tags?: string[];
  /** Custom data */
  customData?: any;
  /** Selenium capabilities */
  [capability: string]: any;
}

interface SauceBrowserDef {
  /** Browser name */
  browserName: string;
  /** Platform/OS */
  platform?: string;
  /** Browser version */
  version?: string;
  /** Device name (mobile) */
  deviceName?: string;
  /** Additional capabilities */
  [key: string]: any;
}

Environment Variables

Sauce Labs

SAUCE_USERNAME          # Sauce Labs username
SAUCE_ACCESS_KEY        # Sauce Labs access key
SAUCE_TUNNEL_ID         # Existing tunnel to use

General

CI                      # Disable TTY output in CI
WCT_PACKAGE_NAME        # Override client package name
BUILD_NUMBER            # Build identifier for reporting

Advanced Configuration

Custom Client Environment

// wct.conf.js
module.exports = {
  clientOptions: {
    environmentScripts: [
      // Load custom assertion library
      'node_modules/custom-assertions/browser.js',
      // Add test utilities
      'test/test-utils.js'
    ],
    mochaOptions: {
      timeout: 30000,
      ui: 'tdd',
      reporter: 'spec'
    }
  }
};

Multi-Environment Setup

// wct.conf.js
const isCI = process.env.CI;
const isSauce = process.env.SAUCE_USERNAME;

module.exports = {
  suites: ['test/**/*.html'],
  verbose: !isCI,
  
  plugins: {
    local: {
      disabled: isSauce,
      browsers: isCI ? ['chrome'] : ['chrome', 'firefox', 'safari']
    },
    sauce: {
      disabled: !isSauce,
      browsers: [
        { browserName: 'chrome', platform: 'Windows 10' },
        { browserName: 'firefox', platform: 'Windows 10' },
        { browserName: 'safari', platform: 'macOS 10.15' },
        { browserName: 'MicrosoftEdge', platform: 'Windows 10' }
      ]
    }
  }
};

Variant Dependency Testing

// wct.conf.js
module.exports = {
  suites: ['test/**/*.html'],
  
  // Test against multiple dependency versions
  variants: {
    'polymer-1': {
      bower: {
        dependencies: {
          'polymer': 'Polymer/polymer#^1.0.0'
        }
      }
    },
    'polymer-2': {
      bower: {
        dependencies: {
          'polymer': 'Polymer/polymer#^2.0.0'
        }
      }
    }
  }
};

Types

interface WebServerOptions {
  port?: number;
  hostname?: string;
  _servers?: Array<{
    url: string;
    variant: string;
  }>;
}

interface MochaSetupOptions {
  ui?: 'bdd' | 'tdd' | 'exports';
  timeout?: number;
  slow?: number;
  bail?: boolean;
  grep?: string | RegExp;
  reporter?: string;
}

Install with Tessl CLI

npx tessl i tessl/npm-web-component-tester

docs

browser-environment.md

build-tools.md

cli.md

configuration.md

index.md

plugin-system.md

test-runner.md

tile.json