0
# Build Tools
1

2
Web Component Tester provides native integration with Gulp and Grunt build systems for seamless testing workflow integration, allowing you to incorporate web component testing directly into your build pipeline.
3

4
## Capabilities
5

6
### Gulp Integration
7

8
Initialize Gulp tasks for web component testing with support for local and remote testing.
9

10
```typescript { .api }
11
/**
12
 * Initialize Gulp tasks for web component testing
13
 * @param gulp - Gulp instance
14
 * @param dependencies - Optional array of task dependencies
15
 */
16
function init(gulp: Gulp, dependencies?: string[]): void;
17
```
18

19
**Available Tasks:**
20
- `wct:local` - Run tests on local browsers
21
- `wct:sauce` - Run tests on Sauce Labs
22
- `test` - Alias for `wct:local`
23
- `test:local` - Alias for `wct:local`
24
- `test:remote` - Alias for `wct:sauce`
25
- `wct` - Alias for `wct:local`
26

27
**Usage Examples:**
28

29
```javascript
30
// gulpfile.js
31
const gulp = require('gulp');
32
require('web-component-tester').gulp.init(gulp);
33

34
// Run with: gulp test
35
// Available tasks: wct:local, wct:sauce, test, test:local, test:remote
36
```
37

38
```javascript
39
// gulpfile.js with dependencies
40
const gulp = require('gulp');
41
const wct = require('web-component-tester');
42

43
// Custom build tasks
44
gulp.task('build:components', () => {
45
  return gulp.src('src/**/*.js')
46
    .pipe(/* build pipeline */)
47
    .pipe(gulp.dest('dist/'));
48
});
49

50
gulp.task('build:styles', () => {
51
  return gulp.src('src/**/*.css')
52
    .pipe(/* style processing */)
53
    .pipe(gulp.dest('dist/'));
54
});
55

56
// Initialize WCT with dependencies
57
wct.gulp.init(gulp, ['build:components', 'build:styles']);
58

59
// Now 'wct:local' will run build tasks first
60
```
61

62
```javascript
63
// Advanced Gulp integration
64
const gulp = require('gulp');
65
const wct = require('web-component-tester');
66

67
// Custom WCT configuration
68
gulp.task('test:custom', () => {
69
  return wct.test({
70
    suites: ['test/unit/**/*.html'],
71
    plugins: {
72
      local: {
73
        browsers: ['chrome', 'firefox']
74
      }
75
    }
76
  });
77
});
78

79
// Integration with other tasks
80
gulp.task('ci', gulp.series(['build', 'lint', 'test:custom']));
81
```
82

83
### Grunt Integration
84

85
Register Grunt multi-task for web component testing with flexible configuration options.
86

87
```javascript { .api }
88
/**
89
 * Register 'wct-test' Grunt multi-task for web component testing
90
 * This function is exported from 'web-component-tester/tasks/test.js'
91
 * @param grunt - Grunt instance
92
 */
93
module.exports = function(grunt) {
94
  grunt.registerMultiTask('wct-test', 'Runs tests via web-component-tester', function() {
95
    // Implementation uses this.options() for configuration and this.async() for completion
96
  });
97
};
98
```
99

100
**Usage Examples:**
101

102
```javascript
103
// gruntfile.js
104
module.exports = function(grunt) {
105
  grunt.initConfig({
106
    'wct-test': {
107
      local: {
108
        options: {
109
          plugins: {
110
            local: {},
111
            sauce: false
112
          },
113
          verbose: true
114
        }
115
      },
116
      remote: {
117
        options: {
118
          plugins: {
119
            sauce: {},
120
            local: false
121
          },
122
          verbose: false
123
        }
124
      },
125
      chrome: {
126
        options: {
127
          plugins: {
128
            local: {
129
              browsers: ['chrome']
130
            }
131
          }
132
        }
133
      },
134
      ci: {
135
        options: {
136
          suites: ['test/unit/**/*.html'],
137
          plugins: {
138
            local: {
139
              browsers: ['chrome'],
140
              browserOptions: {
141
                chrome: ['--headless', '--disable-gpu']
142
              }
143
            }
144
          }
145
        }
146
      }
147
    }
148
  });
149

150
  // Load the task from the task file
151
  grunt.loadTasks('node_modules/web-component-tester/tasks');
152
  
153
  // Available tasks: wct-test:local, wct-test:remote, wct-test:chrome, wct-test:ci
154
};
155
```
156

157
```javascript
158
// Grunt with build pipeline
159
module.exports = function(grunt) {
160
  grunt.initConfig({
161
    // Build tasks
162
    babel: {
163
      options: {
164
        presets: ['@babel/preset-env']
165
      },
166
      dist: {
167
        files: [{
168
          expand: true,
169
          cwd: 'src/',
170
          src: ['**/*.js'],
171
          dest: 'dist/',
172
          ext: '.js'
173
        }]
174
      }
175
    },
176
    
177
    // WCT configuration
178
    'wct-test': {
179
      options: {
180
        root: 'dist/',
181
        suites: ['test/**/*.html']
182
      },
183
      local: {
184
        options: {
185
          plugins: {
186
            local: {
187
              browsers: ['chrome', 'firefox']
188
            }
189
          }
190
        }
191
      },
192
      sauce: {
193
        options: {
194
          plugins: {
195
            sauce: {
196
              browsers: [
197
                { browserName: 'chrome', platform: 'Windows 10' },
198
                { browserName: 'firefox', platform: 'macOS 10.15' }
199
              ]
200
            }
201
          }
202
        }
203
      }
204
    }
205
  });
206

207
  grunt.loadNpmTasks('grunt-babel');
208
  grunt.loadNpmTasks('web-component-tester');
209
  
210
  // Register combined tasks
211
  grunt.registerTask('test', ['babel', 'wct-test:local']);
212
  grunt.registerTask('test:sauce', ['babel', 'wct-test:sauce']);
213
  grunt.registerTask('ci', ['babel', 'wct-test:local']);
214
};
215
```
216

217
## Task Configuration Options
218

219
### Grunt Task Options
220

221
All configuration options from the main Config interface are supported:
222

223
```javascript { .api }
224
interface GruntTaskOptions extends Config {
225
  /** Enable remote testing (Sauce Labs) */
226
  remote?: boolean;
227
  /** Target-specific browser list */
228
  browsers?: string[];
229
  /** Custom plugin configurations */
230
  plugins?: {[pluginName: string]: any};
231
}
232
```
233

234
**Example Configurations:**
235

236
```javascript
237
// Multiple browser testing
238
'wct-test': {
239
  'multi-browser': {
240
    options: {
241
      plugins: {
242
        local: {
243
          browsers: ['chrome', 'firefox', 'safari']
244
        }
245
      }
246
    }
247
  }
248
}
249

250
// Headless testing for CI
251
'wct-test': {
252
  ci: {
253
    options: {
254
      plugins: {
255
        local: {
256
          browsers: ['chrome'],
257
          browserOptions: {
258
            chrome: [
259
              '--headless',
260
              '--disable-gpu',
261
              '--no-sandbox',
262
              '--disable-dev-shm-usage'
263
            ]
264
          }
265
        }
266
      }
267
    }
268
  }
269
}
270

271
// Sauce Labs configuration
272
'wct-test': {
273
  sauce: {
274
    options: {
275
      plugins: {
276
        sauce: {
277
          username: process.env.SAUCE_USERNAME,
278
          accessKey: process.env.SAUCE_ACCESS_KEY,
279
          browsers: [
280
            {
281
              browserName: 'chrome',
282
              platform: 'Windows 10',
283
              version: 'latest'
284
            },
285
            {
286
              browserName: 'firefox',
287
              platform: 'Windows 10', 
288
              version: 'latest'
289
            }
290
          ]
291
        }
292
      }
293
    }
294
  }
295
}
296
```
297

298
## Integration Patterns
299

300
### Continuous Integration
301

302
```javascript
303
// gulpfile.js for CI
304
const gulp = require('gulp');
305
const wct = require('web-component-tester');
306
const isCI = process.env.CI;
307

308
gulp.task('test:unit', () => {
309
  return wct.test({
310
    suites: ['test/unit/**/*.html'],
311
    plugins: {
312
      local: {
313
        browsers: isCI ? ['chrome'] : ['chrome', 'firefox'],
314
        browserOptions: isCI ? {
315
          chrome: ['--headless', '--disable-gpu']
316
        } : {}
317
      }
318
    }
319
  });
320
});
321

322
gulp.task('test:integration', () => {
323
  return wct.test({
324
    suites: ['test/integration/**/*.html'],
325
    testTimeout: 60000,
326
    plugins: {
327
      local: {
328
        browsers: ['chrome'],
329
        browserOptions: {
330
          chrome: ['--headless']
331
        }
332
      }
333
    }
334
  });
335
});
336

337
gulp.task('test', gulp.parallel(['test:unit', 'test:integration']));
338
```
339

340
### Watch Mode Integration
341

342
```javascript
343
// gulpfile.js with watch
344
const gulp = require('gulp');
345
const wct = require('web-component-tester');
346

347
gulp.task('test:watch', () => {
348
  gulp.watch(['src/**/*.js', 'test/**/*.html'], () => {
349
    return wct.test({
350
      suites: ['test/**/*.html'],
351
      persistent: true, // Keep browsers open
352
      plugins: {
353
        local: {
354
          browsers: ['chrome']
355
        }
356
      }
357
    });
358
  });
359
});
360
```
361

362
### Multi-Stage Pipeline
363

364
```javascript
365
// gulpfile.js with stages
366
const gulp = require('gulp');
367
const wct = require('web-component-tester');
368

369
gulp.task('test:lint', () => {
370
  // Linting task
371
});
372

373
gulp.task('test:unit', () => {
374
  return wct.test({
375
    suites: ['test/unit/**/*.html']
376
  });
377
});
378

379
gulp.task('test:integration', () => {
380
  return wct.test({
381
    suites: ['test/integration/**/*.html'],
382
    testTimeout: 30000
383
  });
384
});
385

386
gulp.task('test:e2e', () => {
387
  return wct.test({
388
    suites: ['test/e2e/**/*.html'],
389
    testTimeout: 60000,
390
    plugins: {
391
      sauce: {
392
        browsers: [
393
          { browserName: 'chrome', platform: 'Windows 10' }
394
        ]
395
      }
396
    }
397
  });
398
});
399

400
// Run tests in sequence
401
gulp.task('test:all', gulp.series([
402
  'test:lint',
403
  'test:unit', 
404
  'test:integration',
405
  'test:e2e'
406
]));
407
```
408

409
### Custom Reporting
410

411
```javascript
412
// gulpfile.js with custom reporting
413
const gulp = require('gulp');
414
const wct = require('web-component-tester');
415
const fs = require('fs');
416

417
gulp.task('test:report', () => {
418
  const context = new wct.Context({
419
    suites: ['test/**/*.html']
420
  });
421
  
422
  const results = [];
423
  
424
  context.on('test-end', (browser, test, stats) => {
425
    results.push({
426
      browser: browser.browserName,
427
      test: test.title,
428
      state: test.state,
429
      duration: test.duration
430
    });
431
  });
432
  
433
  context.on('run-end', () => {
434
    fs.writeFileSync('test-results.json', JSON.stringify(results, null, 2));
435
  });
436
  
437
  return wct.test(context);
438
});
439
```
440

441
## Package.json Integration
442

443
### NPM Scripts
444

445
```json
446
{
447
  "scripts": {
448
    "test": "wct",
449
    "test:local": "gulp test:local",
450
    "test:sauce": "grunt wct-test:sauce",
451
    "test:watch": "gulp test:watch",
452
    "test:ci": "wct --local chrome --skip-plugin sauce",
453
    "pretest": "gulp build"
454
  }
455
}
456
```
457

458
### Development Workflow
459

460
```json
461
{
462
  "scripts": {
463
    "dev": "gulp watch & gulp test:watch",
464
    "build": "gulp build",
465
    "test": "gulp test",
466
    "test:debug": "wct --persistent --verbose",
467
    "ci": "npm run build && npm run test:ci"
468
  }
469
}
470
```
471

472
## Types
473

474
```typescript { .api }
475
interface Gulp {
476
  task(name: string, fn: Function): void;
477
  series(tasks: Array<string | Function>): Function;
478
  parallel(tasks: Array<string | Function>): Function;
479
  watch(globs: string | string[], fn: Function): void;
480
}
481
```