0
# Web Component Tester
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: web-component-tester
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install -g web-component-tester` or `npm install --save-dev web-component-tester`
10
11
## Core Imports
12
13
### Node.js API
14
15
```javascript
16
const wct = require('web-component-tester');
17
```
18
19
ES6 modules:
20
21
```javascript
22
import { cli, config, gulp, steps, test } from 'web-component-tester';
23
```
24
25
### Browser API
26
27
The browser client is automatically loaded via `browser.js`:
28
29
```html
30
<script src="../web-component-tester/browser.js"></script>
31
```
32
33
## Basic Usage
34
35
### Command Line
36
37
```bash
38
# Install globally
39
npm install -g web-component-tester
40
41
# Run tests in current directory
42
wct
43
44
# Run specific test files
45
wct test/my-element-test.html test/other-test.js
46
47
# Run with specific browsers
48
wct --local chrome --local firefox
49
```
50
51
### HTML Test Suite
52
53
```html
54
<!doctype html>
55
<html>
56
<head>
57
<meta charset="utf-8">
58
<script src="../../webcomponentsjs/webcomponents-lite.js"></script>
59
<script src="../../web-component-tester/browser.js"></script>
60
<link rel="import" href="../my-element.html">
61
</head>
62
<body>
63
<test-fixture id="basic">
64
<template>
65
<my-element></my-element>
66
</template>
67
</test-fixture>
68
69
<script>
70
suite('<my-element>', function() {
71
let element;
72
73
setup(function() {
74
element = fixture('basic');
75
});
76
77
test('is instantiated', function() {
78
assert.equal(element.is, 'my-element');
79
});
80
});
81
</script>
82
</body>
83
</html>
84
```
85
86
### JavaScript Test Suite
87
88
```javascript
89
suite('MyLibrary', function() {
90
test('has expected API', function() {
91
assert.isFunction(MyLibrary.doSomething);
92
assert.isObject(MyLibrary.config);
93
});
94
95
test('handles async operations', function(done) {
96
MyLibrary.asyncOperation().then(function(result) {
97
assert.equal(result.status, 'success');
98
done();
99
});
100
});
101
});
102
```
103
104
## Architecture
105
106
Web Component Tester is built around several key components:
107
108
- **Command Line Interface**: Global `wct` command for running tests from terminal
109
- **Node.js Runner**: Programmatic API for test execution and configuration
110
- **Browser Environment**: Client-side testing runtime with pre-loaded libraries
111
- **Plugin System**: Extensible architecture supporting local and remote testing
112
- **Configuration System**: Flexible configuration via files, command line, and programmatic API
113
- **Build Tool Integration**: Native support for Gulp and Grunt workflows
114
115
## Capabilities
116
117
### Command Line Interface
118
119
Primary interface for running tests with support for various browsers, configuration options, and CI/CD integration.
120
121
```javascript { .api }
122
function run(env: any, args: string[], output: NodeJS.WritableStream): Promise<void>;
123
function runSauceTunnel(env: any, args: string[], output: NodeJS.WritableStream): Promise<void>;
124
```
125
126
[Command Line Interface](./cli.md)
127
128
### Test Runner API
129
130
Programmatic API for running test suites with full configuration control and event-based progress tracking.
131
132
```typescript { .api }
133
function test(options: Config | Context): Promise<void>;
134
135
interface Config {
136
suites?: string[];
137
verbose?: boolean;
138
root?: string;
139
testTimeout?: number;
140
persistent?: boolean;
141
activeBrowsers?: BrowserDef[];
142
plugins?: {[key: string]: any};
143
}
144
```
145
146
[Test Runner](./test-runner.md)
147
148
### Browser Testing Environment
149
150
Client-side testing environment with pre-loaded testing libraries and web component-specific utilities.
151
152
```javascript { .api }
153
interface WCT {
154
loadSuites(files: string[]): void;
155
share: any;
156
_config: Config;
157
}
158
159
// Global helper functions
160
function flush(callback: () => void): void;
161
function testImmediate(name: string, testFn: Function): void;
162
function safeStep(callback: (error?: any) => void, stepFn: () => void): void;
163
```
164
165
[Browser Environment](./browser-environment.md)
166
167
### Configuration System
168
169
Comprehensive configuration system supporting file-based, programmatic, and command-line configuration with plugin support.
170
171
```typescript { .api }
172
interface Config {
173
suites?: string[];
174
output?: NodeJS.WritableStream;
175
ttyOutput?: boolean;
176
verbose?: boolean;
177
quiet?: boolean;
178
root?: string;
179
testTimeout?: number;
180
persistent?: boolean;
181
clientOptions?: {
182
root?: string;
183
verbose?: boolean;
184
environmentScripts?: string[];
185
};
186
}
187
188
function merge(options: Config, overrides: Config): Config;
189
function expand(context: Context): Promise<void>;
190
function validate(options: Config): Promise<void>;
191
```
192
193
[Configuration](./configuration.md)
194
195
### Build Tool Integration
196
197
Native integration with Gulp and Grunt build systems for seamless testing workflow integration.
198
199
```javascript { .api }
200
// Gulp integration
201
function init(gulp: Gulp, dependencies?: string[]): void;
202
203
// Grunt integration
204
function registerMultiTask(grunt: any): void;
205
```
206
207
[Build Tools](./build-tools.md)
208
209
### Plugin System
210
211
Extensible plugin architecture for adding custom functionality, browser support, and testing environments.
212
213
```typescript { .api }
214
interface Plugin {
215
execute(context: Context): Promise<void>;
216
cliConfig: any;
217
}
218
219
class Context extends EventEmitter {
220
emitHook(name: string): Promise<void>;
221
plugins(): Promise<Plugin[]>;
222
}
223
```
224
225
[Plugin System](./plugin-system.md)
226
227
### Test Execution Steps
228
229
Core test execution pipeline functions that orchestrate the testing process from setup to cleanup.
230
231
```typescript { .api }
232
function setupOverrides(context: Context): Promise<void>;
233
function loadPlugins(context: Context): Promise<Plugin[]>;
234
function configure(context: Context): Promise<void>;
235
function prepare(context: Context): Promise<void>;
236
function runTests(context: Context): Promise<void>;
237
function cancelTests(context: Context): void;
238
```
239
240
## Types
241
242
```typescript { .api }
243
type Browser = string | {browserName: string, platform: string};
244
245
interface BrowserDef extends Browser {
246
id?: number;
247
variant?: string;
248
}
249
250
interface Context extends EventEmitter {
251
options: Config;
252
253
// Hook methods
254
hook(name: string, handler: Handler): void;
255
hookLate(name: string, handler: Handler): void;
256
emitHook(name: string): Promise<void>;
257
258
// Plugin methods
259
plugins(): Promise<Plugin[]>;
260
enabledPlugins(): string[];
261
pluginOptions(name: string): any;
262
}
263
264
type Handler =
265
((...args: any[]) => Promise<any>) |
266
((done: (err?: any) => void) => void) |
267
((arg1: any, done: (err?: any) => void) => void) |
268
((arg1: any, arg2: any, done: (err?: any) => void) => void) |
269
((arg1: any, arg2: any, arg3: any, done: (err?: any) => void) => void);
270
271
interface ValidationResult<T> {
272
isValid: boolean;
273
data: T;
274
errors: ValidationError[];
275
}
276
277
interface TestStats {
278
passed: number;
279
pending: number;
280
failed: number;
281
total: number;
282
}
283
284
interface Plugin {
285
name: string;
286
packageName: string;
287
cliConfig: any;
288
metadata: any;
289
execute(context: Context): Promise<void>;
290
}
291
292
interface MutationEl {
293
onMutation(mutationEl: this, cb: () => void): void;
294
}
295
```