❤
npm
Sign UpSign In

run-headless

2.0.1 • Public • Published

run-headless

NPM version Downloads Build Status Coverage Status

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.

Test

$ npm test

Acknowledgements

MIT © Shannon Moeller

Readme

Keywords

Package Sidebar

Install

npm i run-headless

Repository

github.com/shannonmoeller/run-headless

Homepage

github.com/shannonmoeller/run-headless#readme

Weekly Downloads

5

Version

2.0.1

License

MIT

Last publish

Collaborators

  • shannonmoeller
Try on RunKit
Report malware