headless-test

Runs tests in a headless browser (Chrome-only via Puppeteer for now). Useful to test Web Components, polyfills, or anything else that needs real browser APIs.

Uses Mocha and provides the Chai assertion library.

Usage

Install headless-test via your favourite package manager.

Command-Line or CI

Run and pass a number of files (including tests) which will be loaded in-order as ESM:

headless-test your-code.js your-tests.js

This will exit with non-zero if the Mocha tests fail. Easy!

Note that your-tests.js should look like a totally normal Mocha test file:

// no imports required for Mocha or Chai, they'll be available globally
suite('check stuff', () => {
  test('does a thing', async () => {
    // ...
    await 'foo';
    assert(true, 'this passes');
  });
});

You can also specifiy -b to switch Mocha to BDD mode, or see --help for other options.

This works by hosting a webserver in the current directory (with dhost) so you can load other dependencies.

Extras

CSS can also be included in the page for tests. For example:

headless-test your-code.js your-css.css your-tests.js

API

You can also use headless-test programatically. The most common use case is to pass a URL (e.g., if you're already running a dev server) and specify load to load specific resources as ESM into the test environment.

const headlessTest = require('headless-test');
 
const p = headlessTest('http://localhost:8080', {
  load: ['your-code.js', 'your-tests.js'],
  driver: {
    // options passed to `mocha.setup`
    ui: 'tdd',
  },
});
 
p.then(() => /* something */);

Instead of passing a URL, you can also pass a http.Server to read its URL (e.g., if you're running a dev server in the same process).

Virtual Resources

You can also specify virtual script files, if your tests aren't able to be found on your local web server. They'll still be run in the same origin, but won't be able to import each other. For example:

const p = headlessTest('http://localhost:1234', {
  load: [
    {code: 'console.info("hello"); suite("tests", () => { /* stuff */ });'},
    {code: testCode},
  ],
});

If you're not loading any real script files, it's valid to pass null for the URL.

Notes

Don't use this for integration tests. You should be running Mocha locally for that, and having it start Puppeteer to click on things.

Dependencies

This package has a few direct dependencies, although those dependencies have a huge number of transitive dependencies. Here's the short list:

• mocha is the default test driver
• chai provides an assertion library to your tests
• puppeteer includes headless Chromium

Included for the CLI only:

• dhost provides a never-caching static web server for files
• mri parses command-line arguments
• chalk to make things pretty, because it's included by transitive deps anyway ¯‍\‍_‍(‍ツ‍)‍_‍/‍¯