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

Build Tools

Name: tessl/npm-web-component-tester
Author: tessl

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.

Capabilities

Gulp Integration

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

/**
 * Initialize Gulp tasks for web component testing
 * @param gulp - Gulp instance
 * @param dependencies - Optional array of task dependencies
 */
function init(gulp: Gulp, dependencies?: string[]): void;

Available Tasks:

wct:local - Run tests on local browsers
wct:sauce - Run tests on Sauce Labs
test - Alias for wct:local
test:local - Alias for wct:local
test:remote - Alias for wct:sauce
wct - Alias for wct:local

Usage Examples:

// gulpfile.js
const gulp = require('gulp');
require('web-component-tester').gulp.init(gulp);

// Run with: gulp test
// Available tasks: wct:local, wct:sauce, test, test:local, test:remote

// gulpfile.js with dependencies
const gulp = require('gulp');
const wct = require('web-component-tester');

// Custom build tasks
gulp.task('build:components', () => {
  return gulp.src('src/**/*.js')
    .pipe(/* build pipeline */)
    .pipe(gulp.dest('dist/'));
});

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

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

// Now 'wct:local' will run build tasks first

// Advanced Gulp integration
const gulp = require('gulp');
const wct = require('web-component-tester');

// Custom WCT configuration
gulp.task('test:custom', () => {
  return wct.test({
    suites: ['test/unit/**/*.html'],
    plugins: {
      local: {
        browsers: ['chrome', 'firefox']
      }
    }
  });
});

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

Grunt Integration

/**
 * Register 'wct-test' Grunt multi-task for web component testing
 * This function is exported from 'web-component-tester/tasks/test.js'
 * @param grunt - Grunt instance
 */
module.exports = function(grunt) {
  grunt.registerMultiTask('wct-test', 'Runs tests via web-component-tester', function() {
    // Implementation uses this.options() for configuration and this.async() for completion
  });
};

Usage Examples:

// gruntfile.js
module.exports = function(grunt) {
  grunt.initConfig({
    'wct-test': {
      local: {
        options: {
          plugins: {
            local: {},
            sauce: false
          },
          verbose: true
        }
      },
      remote: {
        options: {
          plugins: {
            sauce: {},
            local: false
          },
          verbose: false
        }
      },
      chrome: {
        options: {
          plugins: {
            local: {
              browsers: ['chrome']
            }
          }
        }
      },
      ci: {
        options: {
          suites: ['test/unit/**/*.html'],
          plugins: {
            local: {
              browsers: ['chrome'],
              browserOptions: {
                chrome: ['--headless', '--disable-gpu']
              }
            }
          }
        }
      }
    }
  });

  // Load the task from the task file
  grunt.loadTasks('node_modules/web-component-tester/tasks');
  
  // Available tasks: wct-test:local, wct-test:remote, wct-test:chrome, wct-test:ci
};

// Grunt with build pipeline
module.exports = function(grunt) {
  grunt.initConfig({
    // Build tasks
    babel: {
      options: {
        presets: ['@babel/preset-env']
      },
      dist: {
        files: [{
          expand: true,
          cwd: 'src/',
          src: ['**/*.js'],
          dest: 'dist/',
          ext: '.js'
        }]
      }
    },
    
    // WCT configuration
    'wct-test': {
      options: {
        root: 'dist/',
        suites: ['test/**/*.html']
      },
      local: {
        options: {
          plugins: {
            local: {
              browsers: ['chrome', 'firefox']
            }
          }
        }
      },
      sauce: {
        options: {
          plugins: {
            sauce: {
              browsers: [
                { browserName: 'chrome', platform: 'Windows 10' },
                { browserName: 'firefox', platform: 'macOS 10.15' }
              ]
            }
          }
        }
      }
    }
  });

  grunt.loadNpmTasks('grunt-babel');
  grunt.loadNpmTasks('web-component-tester');
  
  // Register combined tasks
  grunt.registerTask('test', ['babel', 'wct-test:local']);
  grunt.registerTask('test:sauce', ['babel', 'wct-test:sauce']);
  grunt.registerTask('ci', ['babel', 'wct-test:local']);
};

Task Configuration Options

Grunt Task Options

All configuration options from the main Config interface are supported:

interface GruntTaskOptions extends Config {
  /** Enable remote testing (Sauce Labs) */
  remote?: boolean;
  /** Target-specific browser list */
  browsers?: string[];
  /** Custom plugin configurations */
  plugins?: {[pluginName: string]: any};
}

Example Configurations:

// Multiple browser testing
'wct-test': {
  'multi-browser': {
    options: {
      plugins: {
        local: {
          browsers: ['chrome', 'firefox', 'safari']
        }
      }
    }
  }
}

// Headless testing for CI
'wct-test': {
  ci: {
    options: {
      plugins: {
        local: {
          browsers: ['chrome'],
          browserOptions: {
            chrome: [
              '--headless',
              '--disable-gpu',
              '--no-sandbox',
              '--disable-dev-shm-usage'
            ]
          }
        }
      }
    }
  }
}

// Sauce Labs configuration
'wct-test': {
  sauce: {
    options: {
      plugins: {
        sauce: {
          username: process.env.SAUCE_USERNAME,
          accessKey: process.env.SAUCE_ACCESS_KEY,
          browsers: [
            {
              browserName: 'chrome',
              platform: 'Windows 10',
              version: 'latest'
            },
            {
              browserName: 'firefox',
              platform: 'Windows 10', 
              version: 'latest'
            }
          ]
        }
      }
    }
  }
}

Integration Patterns

Continuous Integration

// gulpfile.js for CI
const gulp = require('gulp');
const wct = require('web-component-tester');
const isCI = process.env.CI;

gulp.task('test:unit', () => {
  return wct.test({
    suites: ['test/unit/**/*.html'],
    plugins: {
      local: {
        browsers: isCI ? ['chrome'] : ['chrome', 'firefox'],
        browserOptions: isCI ? {
          chrome: ['--headless', '--disable-gpu']
        } : {}
      }
    }
  });
});

gulp.task('test:integration', () => {
  return wct.test({
    suites: ['test/integration/**/*.html'],
    testTimeout: 60000,
    plugins: {
      local: {
        browsers: ['chrome'],
        browserOptions: {
          chrome: ['--headless']
        }
      }
    }
  });
});

gulp.task('test', gulp.parallel(['test:unit', 'test:integration']));

Watch Mode Integration

// gulpfile.js with watch
const gulp = require('gulp');
const wct = require('web-component-tester');

gulp.task('test:watch', () => {
  gulp.watch(['src/**/*.js', 'test/**/*.html'], () => {
    return wct.test({
      suites: ['test/**/*.html'],
      persistent: true, // Keep browsers open
      plugins: {
        local: {
          browsers: ['chrome']
        }
      }
    });
  });
});

Multi-Stage Pipeline

// gulpfile.js with stages
const gulp = require('gulp');
const wct = require('web-component-tester');

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

gulp.task('test:unit', () => {
  return wct.test({
    suites: ['test/unit/**/*.html']
  });
});

gulp.task('test:integration', () => {
  return wct.test({
    suites: ['test/integration/**/*.html'],
    testTimeout: 30000
  });
});

gulp.task('test:e2e', () => {
  return wct.test({
    suites: ['test/e2e/**/*.html'],
    testTimeout: 60000,
    plugins: {
      sauce: {
        browsers: [
          { browserName: 'chrome', platform: 'Windows 10' }
        ]
      }
    }
  });
});

// Run tests in sequence
gulp.task('test:all', gulp.series([
  'test:lint',
  'test:unit', 
  'test:integration',
  'test:e2e'
]));

Custom Reporting

// gulpfile.js with custom reporting
const gulp = require('gulp');
const wct = require('web-component-tester');
const fs = require('fs');

gulp.task('test:report', () => {
  const context = new wct.Context({
    suites: ['test/**/*.html']
  });
  
  const results = [];
  
  context.on('test-end', (browser, test, stats) => {
    results.push({
      browser: browser.browserName,
      test: test.title,
      state: test.state,
      duration: test.duration
    });
  });
  
  context.on('run-end', () => {
    fs.writeFileSync('test-results.json', JSON.stringify(results, null, 2));
  });
  
  return wct.test(context);
});

Package.json Integration

NPM Scripts

{
  "scripts": {
    "test": "wct",
    "test:local": "gulp test:local",
    "test:sauce": "grunt wct-test:sauce",
    "test:watch": "gulp test:watch",
    "test:ci": "wct --local chrome --skip-plugin sauce",
    "pretest": "gulp build"
  }
}

Development Workflow

{
  "scripts": {
    "dev": "gulp watch & gulp test:watch",
    "build": "gulp build",
    "test": "gulp test",
    "test:debug": "wct --persistent --verbose",
    "ci": "npm run build && npm run test:ci"
  }
}

Types

interface Gulp {
  task(name: string, fn: Function): void;
  series(tasks: Array<string | Function>): Function;
  parallel(tasks: Array<string | Function>): Function;
  watch(globs: string | string[], fn: Function): void;
}

Install with Tessl CLI

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

docs

browser-environment.md