0
# Configuration
1

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

4
## Capabilities
5

6
### Configuration Merging
7

8
Merge configuration objects with deep merging support for nested options.
9

10
```typescript { .api }
11
/**
12
 * Merge configuration options with deep merging for nested objects
13
 * @param options - Base configuration object
14
 * @param overrides - Configuration overrides to merge
15
 * @returns Merged configuration object
16
 */
17
function merge(options: Config, overrides: Config): Config;
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
const wct = require('web-component-tester');
24

25
const baseConfig = {
26
  verbose: false,
27
  plugins: {
28
    local: { browsers: ['chrome'] }
29
  }
30
};
31

32
const overrides = {
33
  verbose: true,
34
  plugins: {
35
    local: { browsers: ['chrome', 'firefox'] },
36
    sauce: { username: 'test-user' }
37
  }
38
};
39

40
const finalConfig = wct.config.merge(baseConfig, overrides);
41
// Result: {
42
//   verbose: true,
43
//   plugins: {
44
//     local: { browsers: ['chrome', 'firefox'] },
45
//     sauce: { username: 'test-user' }
46
//   }
47
// }
48
```
49

50
### Configuration Expansion
51

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

54
```typescript { .api }
55
/**
56
 * Expand configuration with defaults and plugin-specific settings
57
 * @param context - Test execution context
58
 * @returns Promise that resolves when expansion is complete
59
 */
60
function expand(context: Context): Promise<void>;
61
```
62

63
### Configuration Validation
64

65
Validate configuration options and ensure all required settings are present.
66

67
```typescript { .api }
68
/**
69
 * Validate configuration options and check for required settings
70
 * @param options - Configuration object to validate
71
 * @returns Promise that resolves if valid, rejects with error if invalid
72
 */
73
function validate(options: Config): Promise<void>;
74
```
75

76
### Argument Parsing
77

78
Parse command line arguments into configuration objects.
79

80
```typescript { .api }
81
/**
82
 * Initial argument parsing for configuration discovery
83
 * @param args - Command line arguments array
84
 * @returns Partial configuration object
85
 */
86
function preparseArgs(args: string[]): Partial<Config>;
87

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

97
## Configuration Files
98

99
### wct.conf.json Format
100

101
The main configuration file format with comprehensive options:
102

103
```json
104
{
105
  "suites": ["test/**/*.html", "test/**/*.js"],
106
  "root": "./",
107
  "verbose": false,
108
  "quiet": false,
109
  "expanded": false,
110
  "testTimeout": 90000,
111
  "persistent": false,
112
  "extraScripts": [],
113
  "wctPackageName": "web-component-tester",
114
  "clientOptions": {
115
    "root": null,
116
    "verbose": false,
117
    "environmentScripts": [
118
      "stacky/browser.js",
119
      "mocha/mocha.js",
120
      "chai/chai.js"
121
    ],
122
    "environmentImports": [],
123
    "waitForFrameworks": true,
124
    "numConcurrentSuites": 1,
125
    "trackConsoleError": true,
126
    "mochaOptions": {
127
      "timeout": 10000,
128
      "ui": "bdd"
129
    }
130
  },
131
  "plugins": {
132
    "local": {
133
      "disabled": false,
134
      "browsers": ["chrome", "firefox"],
135
      "browserOptions": {
136
        "chrome": ["--headless", "--disable-gpu"],
137
        "firefox": ["-headless"]
138
      }
139
    },
140
    "sauce": {
141
      "disabled": true,
142
      "username": "${SAUCE_USERNAME}",
143
      "accessKey": "${SAUCE_ACCESS_KEY}",
144
      "tunnelId": "${SAUCE_TUNNEL_ID}",
145
      "browsers": [
146
        {
147
          "browserName": "chrome",
148
          "platform": "Windows 10",
149
          "version": "latest"
150
        },
151
        {
152
          "browserName": "firefox", 
153
          "platform": "macOS 10.15",
154
          "version": "latest"
155
        }
156
      ]
157
    }
158
  },
159
  "browserOptions": {
160
    "name": "WCT Test Run",
161
    "tags": ["web-components", "polymer"],
162
    "build": "${BUILD_NUMBER}"
163
  }
164
}
165
```
166

167
### Global Configuration
168

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

171
```json
172
{
173
  "plugins": {
174
    "sauce": {
175
      "username": "your-global-username",
176
      "accessKey": "your-global-access-key"
177
    }
178
  }
179
}
180
```
181

182
### Configuration File Discovery
183

184
WCT searches for configuration files in this order:
185
1. File specified by `--config-file` argument
186
2. `wct.conf.json` in current directory
187
3. `wct.conf.js` in current directory (Node.js module)
188
4. `~/wct.conf.json` (global user configuration)
189

190
**Usage Examples:**
191

192
```javascript
193
// wct.conf.js (JavaScript configuration)
194
module.exports = {
195
  suites: ['test/**/*.html'],
196
  plugins: {
197
    local: {
198
      browsers: process.env.CI ? ['chrome'] : ['chrome', 'firefox']
199
    }
200
  }
201
};
202
```
203

204
## Configuration Interface
205

206
### Main Configuration Object
207

208
Complete configuration interface with all available options:
209

210
```typescript { .api }
211
interface Config {
212
  /** Test file patterns to run */
213
  suites?: string[];
214
  /** Output stream for results */
215
  output?: NodeJS.WritableStream;
216
  /** Enable TTY-specific formatting */
217
  ttyOutput?: boolean;
218
  /** Enable verbose logging */
219
  verbose?: boolean;
220
  /** Suppress all output */
221
  quiet?: boolean;
222
  /** Show expanded test details */
223
  expanded?: boolean;
224
  /** Root directory for tests */
225
  root?: string;
226
  /** Test timeout in milliseconds */
227
  testTimeout?: number;
228
  /** Keep browsers open after tests */
229
  persistent?: boolean;
230
  /** Additional scripts to load */
231
  extraScripts?: string[];
232
  /** Package name for WCT client code */
233
  wctPackageName?: string;
234
  /** Browser-side configuration */
235
  clientOptions?: ClientOptions;
236
  /** Active browser definitions */
237
  activeBrowsers?: BrowserDef[];
238
  /** Plugin configurations */
239
  plugins?: {[pluginName: string]: PluginOptions};
240
  /** Browser-specific options */
241
  browserOptions?: BrowserOptions;
242
  /** Skip cleanup after tests */
243
  skipCleanup?: boolean;
244
  /** Register custom hooks */
245
  registerHooks?: (context: Context) => void;
246
  /** Webserver configuration (internal) */
247
  webserver?: WebServerOptions;
248
}
249
```
250

251
### Client Options
252

253
Browser-side configuration options:
254

255
```typescript { .api }
256
interface ClientOptions {
257
  /** Root URL for client scripts */
258
  root?: string;
259
  /** Enable debug logging in browser */
260
  verbose?: boolean;
261
  /** Scripts to load before WCT starts */
262
  environmentScripts?: string[];
263
  /** HTML imports to load */
264
  environmentImports?: string[];
265
  /** Wait for web component frameworks */
266
  waitForFrameworks?: boolean;
267
  /** Custom wait function */
268
  waitFor?: Function;
269
  /** Concurrent suite limit */
270
  numConcurrentSuites?: number;
271
  /** Track console.error as failure */
272
  trackConsoleError?: boolean;
273
  /** Mocha setup options */
274
  mochaOptions?: MochaSetupOptions;
275
}
276
```
277

278
### Plugin Options
279

280
Plugin-specific configuration interface:
281

282
```typescript { .api }
283
interface PluginOptions {
284
  /** Disable this plugin */
285
  disabled?: boolean;
286
  /** Plugin-specific configuration */
287
  [key: string]: any;
288
}
289

290
interface LocalPluginOptions extends PluginOptions {
291
  /** Browsers to run locally */
292
  browsers?: string[];
293
  /** Browser-specific command line options */
294
  browserOptions?: {[browserName: string]: string[]};
295
  /** Skip Selenium installation */
296
  skipSeleniumInstall?: boolean;
297
}
298

299
interface SaucePluginOptions extends PluginOptions {
300
  /** Sauce Labs username */
301
  username?: string;
302
  /** Sauce Labs access key */
303
  accessKey?: string;
304
  /** Existing tunnel ID */
305
  tunnelId?: string;
306
  /** Browser configurations for Sauce Labs */
307
  browsers?: SauceBrowserDef[];
308
  /** Build identifier */
309
  build?: string;
310
  /** Test tags */
311
  tags?: string[];
312
}
313
```
314

315
### Browser Configuration
316

317
Browser-specific configuration options:
318

319
```typescript { .api }
320
interface BrowserOptions {
321
  /** Test run name */
322
  name?: string;
323
  /** Build identifier */
324
  build?: string;
325
  /** Test tags */
326
  tags?: string[];
327
  /** Custom data */
328
  customData?: any;
329
  /** Selenium capabilities */
330
  [capability: string]: any;
331
}
332

333
interface SauceBrowserDef {
334
  /** Browser name */
335
  browserName: string;
336
  /** Platform/OS */
337
  platform?: string;
338
  /** Browser version */
339
  version?: string;
340
  /** Device name (mobile) */
341
  deviceName?: string;
342
  /** Additional capabilities */
343
  [key: string]: any;
344
}
345
```
346

347
## Environment Variables
348

349
### Sauce Labs
350

351
```bash
352
SAUCE_USERNAME          # Sauce Labs username
353
SAUCE_ACCESS_KEY        # Sauce Labs access key
354
SAUCE_TUNNEL_ID         # Existing tunnel to use
355
```
356

357
### General
358

359
```bash
360
CI                      # Disable TTY output in CI
361
WCT_PACKAGE_NAME        # Override client package name
362
BUILD_NUMBER            # Build identifier for reporting
363
```
364

365
## Advanced Configuration
366

367
### Custom Client Environment
368

369
```javascript
370
// wct.conf.js
371
module.exports = {
372
  clientOptions: {
373
    environmentScripts: [
374
      // Load custom assertion library
375
      'node_modules/custom-assertions/browser.js',
376
      // Add test utilities
377
      'test/test-utils.js'
378
    ],
379
    mochaOptions: {
380
      timeout: 30000,
381
      ui: 'tdd',
382
      reporter: 'spec'
383
    }
384
  }
385
};
386
```
387

388
### Multi-Environment Setup
389

390
```javascript
391
// wct.conf.js
392
const isCI = process.env.CI;
393
const isSauce = process.env.SAUCE_USERNAME;
394

395
module.exports = {
396
  suites: ['test/**/*.html'],
397
  verbose: !isCI,
398
  
399
  plugins: {
400
    local: {
401
      disabled: isSauce,
402
      browsers: isCI ? ['chrome'] : ['chrome', 'firefox', 'safari']
403
    },
404
    sauce: {
405
      disabled: !isSauce,
406
      browsers: [
407
        { browserName: 'chrome', platform: 'Windows 10' },
408
        { browserName: 'firefox', platform: 'Windows 10' },
409
        { browserName: 'safari', platform: 'macOS 10.15' },
410
        { browserName: 'MicrosoftEdge', platform: 'Windows 10' }
411
      ]
412
    }
413
  }
414
};
415
```
416

417
### Variant Dependency Testing
418

419
```javascript
420
// wct.conf.js
421
module.exports = {
422
  suites: ['test/**/*.html'],
423
  
424
  // Test against multiple dependency versions
425
  variants: {
426
    'polymer-1': {
427
      bower: {
428
        dependencies: {
429
          'polymer': 'Polymer/polymer#^1.0.0'
430
        }
431
      }
432
    },
433
    'polymer-2': {
434
      bower: {
435
        dependencies: {
436
          'polymer': 'Polymer/polymer#^2.0.0'
437
        }
438
      }
439
    }
440
  }
441
};
442
```
443

444
## Types
445

446
```typescript { .api }
447
interface WebServerOptions {
448
  port?: number;
449
  hostname?: string;
450
  _servers?: Array<{
451
    url: string;
452
    variant: string;
453
  }>;
454
}
455

456
interface MochaSetupOptions {
457
  ui?: 'bdd' | 'tdd' | 'exports';
458
  timeout?: number;
459
  slow?: number;
460
  bail?: boolean;
461
  grep?: string | RegExp;
462
  reporter?: string;
463
}
464
```