search

james-proxy / james-browser-launcher

Detect, launch and stop browsers
Other
23 stars 15 forks source link

readme

This project is in maintenance mode

Maintainers or forks welcome: the original James team aren't able to spend the same amount of time on this library anymore.

james-browser-launcher Build Status Get it on npm

Detect the browser versions available on your system and launch them in an isolated profile for automated testing purposes.

You can launch browsers headlessly (using Xvfb or with PhantomJS) and set the proxy configuration on the fly.

At the beginning of time, there was substack/browser-launcher, and all was well with the world. However, life happened, and the project became unmaintained. Out of the ashes, a leader emerged, and promised the citizens of npm that browser-launcher would become great again, but under a new banner: browser-launcher2. The world was once again prosperous, until we were eventually notified that the king had forsaken us (which happens, it's open source, and benderjs did a lot for the community, which is awesome!)

Anyways, due to the project's dependence on browser-launcher2, james-proxy forked the project to make some much-needed updates and fix some problems.

Differences from browser-launcher

Differences from browser-launcher2

Supported browsers

The goal for this module is to support all major browsers on every desktop platform.

At the moment, james-browser-launcher supports following browsers on Windows, Unix and OS X:

Install

npm install @james-proxy/james-browser-launcher

Example

Browser launch

var launcher = require( '@james-proxy/james-browser-launcher' );

launcher( function( err, launch ) {
    if ( err ) {
        return console.error( err );
    }

    launch( 'http://cksource.com/', 'chrome', function( err, instance ) {
        if ( err ) {
            return console.error( err );
        }

        console.log( 'Instance started with PID:', instance.pid );

        instance.on( 'stop', function( code ) {
            console.log( 'Instance stopped with exit code:', code );
        } );
    } );
} );

Outputs:

$ node example/launch.js
Instance started with PID: 12345
Instance stopped with exit code: 0

Browser launch with options

var launcher = require( '@james-proxy/james-browser-launcher' );

launcher( function( err, launch ) {
    // ...
    launch(
        'http://cksource.com/',
        {
            browser: 'chrome',
            noProxy: [ '127.0.0.1', 'localhost' ],
            options: [
                '--disable-web-security',
                '--disable-extensions'
            ]
        },
        function( err, instance ) {
            // ...
        }
    );
} );

Browser detection

var launcher = require( '../' );

launcher.detect( function( available ) {
    console.log( 'Available browsers:' );
    console.dir( available );
} );

Outputs:

$ node example/detect.js
Available browsers:
[ { name: 'chrome',
        version: '36.0.1985.125',
        type: 'chrome',
        command: 'google-chrome' },
    { name: 'chromium',
        version: '36.0.1985.125',
        type: 'chrome',
        command: 'chromium-browser' },
    { name: 'firefox',
        version: '31.0',
        type: 'firefox',
        command: 'firefox' },
    { name: 'phantomjs',
        version: '1.9.7',
        type: 'phantom',
        command: 'phantomjs' },
    { name: 'opera',
        version: '12.16',
        type: 'opera',
        command: 'opera' } ]

Detaching the launched browser process from your script

If you want the opened browser to remain open after killing your script, first, you need to set options.detached to true (see the API). By default, killing your script will kill the opened browsers.

Then, if you want your script to immediately return control to the shell, you may additionally call unref on the instance object in the callback:

var launcher = require('@james-proxy/james-browser-launcher');
launcher( function (err, launch) {
    launch( 'http://example.org/', {
        browser: 'chrome',
        detached: true
    }, function( err, instance ) {
        if ( err ) {
            return console.error( err );
        }

        instance.process.unref();
        instance.process.stdin.unref();
        instance.process.stdout.unref();
        instance.process.stderr.unref();
    } );
});

API

var launcher = require('@james-proxy/james-browser-launcher');

launcher([configPath], callback)

Detect available browsers and pass launch function to the callback.

Parameters:

launch(uri, options, callback)

Open given URI in a browser and return an instance of it.

Parameters:

launch.browsers

This property contains an array of all known and available browsers.

instance

Browser instance object.

Properties:

Events:

Methods:

launcher.detect(callback)

Detects all browsers available.

Parameters:

Each browser contains following properties:

launcher.update([configFile], callback)

Updates the browsers cache file (~/.config/james-browser-launcher/config.json is no configFile was given) and creates new profiles for found browsers.

Parameters:

Known Issues

License

MIT