gemini-core

Utility which contains common modules for gemini and hermione.

Table of Contents

• SetsBuilder
• Options
  • Sets
• BrowserPool
• events
  • AsyncEmitter
  • utils
• promiseUtils
• BrowserAgent
• Errors
  • CancelledError

SetsBuilder

Creates mapping of test files with browsers in which they should be run and vice versa.

Example of usage:

const SetsBuilder = require('gemini-core').SetsBuilder;
const sets = {
    desktop: {
        files: ['desktop/tests/**.js'],
        browsers: ['bro1']
    },
    touch-phone: {
        files: ['touch-phone/tests'],
        browsers: ['bro2']
    }
};

SetsBuilder
    .create(sets, {defaultDir: 'default/path'}) // creates setsBuilder using specified tests and options
    .useSets(['desktop']) // use only the specified sets
    .useBrowsers(['bro1']) // use only specified browsers
    .useFiles(['desktop/tests/test.js']) // use only specified files if sets
                                      //and files to use are not specified
    .build('/root', globOpts) // builds a collection of sets with paths expanded according
                                  // to the project root and glob options
    .then((setCollection) => {
        setCollection.groupByFile(); // groups all browsers of test-sets by file:
                                    // {'desktop/tests/test.js': ['bro1']}
        setCollection.groupByBrowser(); // groups all files of test-sets by browser:
                                       // {'bro': ['desktop/tests/test.js']}
    })
    .done();

Options

Returns an object with some options.

const options = require('gemini-core').config.options;

Sets

const sets = options.sets; // returns a section for configparser with two options – files and browsers.
                           // Default value is an empty set - all: {files: []}

BrowserPool

Example:

const BrowserPool = require('gemini-core').BrowserPool;

// Some browser realization
class Browser {
    constructor(id) {
        this.id = 'bro'; // required field
        this.sessionId = null; // required field
    }

    launch() {
        return doLaunch()
            .then((sessionId) => this.sessionId = sessionId);
    }

    // required method
    reset() {
        return doSomeReset();
    }

    quit() {
        return doQuit();
    }
}

const BrowserManager = {
    create: (id) => new Browser(id),

    start: (browser) => browser.launch(),
    onStart: (browser) => emitter.emitAndWait('sessionStart', browser),

    onQuit: (browser) => emitter.emitAndWait('sessionEnd', browser),
    quit: (browser) => browser.quit()
};

const config = {
    forBrowser: (id) => {
        return {
            parallelLimit: 1, // maximum number of specific browser sessions executed in parallel
            sessionUseLimit: 2 // maxiumu number of session reuse (test per session, for example)
        };
    },

    getBrowserIds: () => config.getBrowserIds(),

    system: {
        parallelLimit: 10 // maximum number of browser sessions at all
    }
};

const pool = BrowserPool.create(BrowserManager, {
    logNamespace: 'gemini', // prefix for logger. log = require('debug')(`${logNamespace}:pool:...`)
    config
});

return pool.getBrowser('bro')
    .then((bro) => {
        ...
        return pool.freeBrowser(bro);
    });

events

AsyncEmitter

Node.js event emitter with promises support.

Node.js builtin EventEmmiter class executes all handlers synchronously without waiting for completion of any async operations that may happen inside.

AsyncEmitter is the subclass of EventEmmiter which adds ability to return a promise from event handler and wait until it resolved. Just use emitAndWait instead of emit:

const AsyncEmitter = require('gemini-core').AsyncEmitter;
const emitter = new AsyncEmitter();
emitter.on('event', function() {
    return Promise.delay(1000);
});

emmiter.emitAndWait('event')
    .then(function() {
        console.log('All handlers finished'); // Would be called after 1 second
    });

emitAndWait returns promise.

utils

passthroughEvent(from, to, event)

Passes event from from to to. event can be an array of events.

promiseUtils

waitForResults(promises)

Waits for all promises in array to be resolved or rejected. If any promise is rejected - rejects with the first rejection error, otherwise resolves.

BrowserAgent

Example:

const BrowserAgent = require('gemini-core').BrowserAgent;
const BrowserPool = require('gemini-core').BrowserPool;
const pool = BrowserPool.create(/*BrowserManager, config*/);
const browserAgent = BrowserAgent.create('bro-id', pool);

return browserAgent.getBrowser()
    .then((bro) => {
        ...
        return browserAgent.freeBrowser(bro/*, {force: true}*/);
    });

Errors

CancelledError

This error will be thrown on browser pool cancel:

const BrowserPool = require('gemini-core').BrowserPool;
const CancelledError = require('gemini-core').errors.CancelledError;
...
pool.getBrowser('bro')
    .then((bro) => ...)
    .catch((e) => {
        if (e instanceof CancelledError) {
            console.log('cancelled')
        }
    });

pool.cancel();