npm:run-headless-chromium

README

Starts Chromium or Google Chrome in headless mode (using Xvfb) and forwards the output from JavaScript console to stdout.

Xvfb only works on Linux and OS X; Windows is not supported.

Usage

./run-headless-chromium.js [options]

All [options] are directly passed to Chromium. All console messages are forwarded to the standard output of this process. Every message generated by console.log, console.warn, etc. is printed with a newline character at the end, unless the message ends with \x03\b. This is a special character sequence interpreted as "not end of newline".

In addition to the JavaScript messages, errors from Chromium are also printed in the console. This behavior can be controlled by two environment variables:

LOG_CR_VERBOSITY - Only print messages from Chromium with this verbosity level.
Allowed values: Any permutation of INFO|WARNING|ERROR|ERROR_REPORT|FATAL|VERBOSE|UNKNOWN, defaults to ERROR|ERROR_REPORT|FATAL. Use LOG_CR_VERBOSITY=. to show all messages.
LOG_CR_HIDE_PATTERN - Exclude messages matching this pattern (case-insensitive).
Allowed values: Any regular expression (ECMAScript/JavaScript syntax), defaults to kwallet.
CHROMIUM_EXE_PATH - Set the path to the Chromium / Google Chrome executable.

Any webpage that is loaded using run-headless-chromium can close Chromium and exit the process by sending the magic string console.log("All tests completed!");. Insert an integer at the end of the string to change the exit code of this program from 0 to some other integer within the 0 - 255 range.

Example

Headless Chromium is ideal for unit testing, e.g. with Jasmine:

Jasmine 1.3

<script src="jasmine/lib/jasmine-core/jasmine.js"></script>
<script src="jasmine/src/console/ConsoleReporter.js"></script>
<script>
var jasmineEnv = jasmine.getEnv();

var consoleReporter = new jasmine.ConsoleReporter(
    function print(message) {
        // Append magic bytes to signal that the line has not ended yet.
        // This is needed because ConsoleReporter will add the trailing newlines
        // if desired, i.e. it expects console.log to behave as print, not println.
        console.log(message + '\x03\b');
    },
    function onComplete(runner) {
        // 0 = success, 1 = failure
        var exitCode = runner.results().failedCount > 0 ? 1 : 0;
        // Magic string to signal completion of the tests
        console.info('All tests completed!' + exitCode);
    },
    // showColors (whether to generate colorful output)
    true
);

jasmineEnv.addReporter(consoleReporter);
jasmineEnv.execute();
</script>

Jasmine 2.0

<script src="jasmine/lib/jasmine-core/jasmine.js"></script>
<script src="jasmine/lib/console/console.js"></script>
<script>
var jasmineEnv = jasmine.getEnv();

var consoleReporter = new jasmine.ConsoleReporter({
    print: function print(message) {
        console.log(message + '\x03\b');
    },
    onComplete: function onComplete(isSuccess) {
        var exitCode = isSuccess ? 0 : 1;
        console.info('All tests completed!' + exitCode);
    },
    showColors: true
});

jasmineEnv.addReporter(consoleReporter);
jasmineEnv.execute();
</script>

Node.js

The following example shows how to start run-headless-chromium from Node.js, and terminate the process in a graceful way. Note that the page from the example does not call console.info('All tests completed!0'), so the browser would stay around indefinitely if we do not explicitly kill it.

// spawn has the same API as child_process.spawn, minus the command argument.
// See the "spawn" method at https://nodejs.org/api/child_process.html
var spawnHeadlessChromium = require('run-headless-chromium').spawn;

var proc = spawnHeadlessChromium([
    // Flags forwarded to Chromium:
    'https://example.com/some_page_that_does_not_print_exit_message',
], {
    stdio: 'inherit',
});
proc.on('close', function() {
    clearTimeout(delayedExit);
    console.log('Headless Chromium exited!');
});
var delayedExit = setTimeout(function() {
    console.log('Chrome did not exit within a few seconds, sending SIGINT...');
    // Graceful exit - allow run-headless-chromium to exit Chrome and Xvfb.
    proc.kill('SIGINT');
    // If you do proc.kill(); then Chrome and Xvfb may still hang around.
}, 5000);

License

MIT

Usage no npm install needed!