Run-headless NPM

run-headless

The easiest way of running code in a modern headless browser environment.

Install

$ npm install --global run-headless

Usage

Usage: run-headless [options]
       rh [options]

Options:

      --html          Literal HTML to execute (default: minimal skeleton)
      --js            Literal JavaScript to execute (default: stdin)
      --url           URL to load (overrides --html)
  -c, --close-var     Close global function (default: `__close__`)
  -o, --coverage-var  Coverage global variable (default: `__coverage__`)
  -d, --out-dir       Coverage output directory (default: `.nyc_output`)
  -f, --out-file      Coverage output file (default: `<uuid>.json`)
  -h, --help          Output usage information
  -v, --version       Output version number

Examples

$ echo "console.log('hello world')" | run-headless
hello world

$ run-headless --js "console.log('hello world')"
hello world

$ cat index.js | run-headless
$ rollup index.js | run-headless
$ browserify index.js | run-headless
$ nyc instrument index.js | run-headless && nyc report

$ run-headless --html "<script>console.log('hello world');</script>"
$ run-headless --html "$(cat index.html)" --js "$(cat index.js)"

$ run-headless --url "http://localhost:3000/tests"
$ run-headless --url "https://google.com" --js "console.log(document.title)"

CI

Headless browsers are well suited to running in CI environments. Configurations vary, but this .travis.yml file should get you going with Travis:

sudo: required
language: node_js
addons:
 chrome: stable
node_js:
  - node
  - '8'

Browser Testing

You can use any test runner you like that works in a browser and outputs to the console. Just make sure to run window.__close__() (or your custom closeVar) when all tests have completed.

// test.js

const test = require('tape');

test('should pass', t => {
    t.pass('yay!');
    t.end();
});

test.onFinish(window.__close__);

$ browserify test.js | run-headless | tap-diff

  should pass
    ✔  yay!

passed: 1  failed: 0  of 1 tests  (763ms)

All of 1 tests passed!

API

`run(options): Runner`

options {Object} See usage.
- html {String}
- js {String}
- closeVar {String}
- coverageVar {String}
- outDir {String}
- outFile {String}

The following example starts up a static file server with express, bundles test scripts with rollup, executes them in a headless browser, and prints the output to the console. (Assumes that your rollup config is generating a bundle with nyc-compatible instrumented code).

// test.js

const run = require('run-headless');
const express = require('express');
const rollup = require('rollup');

const server = express
    .use(express.static(__dirname))
    .listen(3000, async () => {
        const bundle = await rollup.rollup({ ... });
        const { code } = await bundle.generate({ ... });

        await run({
            url: 'http://localhost:3000/tests.html',
            js: code
        });

        server.close();
    });

$ nyc node test.js
... test output ...
... coverage output ...

Runner Methods

`.then()` and `.catch()`

Runner is a thenable and awaitable Promise object. It resolves when the browser is closed.

Runner Properties

`.browser` `{Browser}`

A puppeteer Browser instance.

`.page` `{Page}`

A puppeteer Page instance.

Contribute

Standards for this project, including tests, code coverage, and semantics are enforced with a build tool. Pull requests must include passing tests with 100% code coverage and no linting errors.