Programmatic API (experimental)

With the help of gemini/api module you can use Gemini programmatically in your scripts or build tools plugins.

First step is to create Gemini instance with a config:

var Gemini = require('gemini/api');

var gemini = new Gemini({
    projectRoot: '/path/to/project',
    gridUrl: 'http://example.com/grid',
    rootUrl: 'http://test.com'
    ...
});

Accessing the config options

You can get values of options via gemini.config property:

var Gemini = require('gemini/api'),
    gemini = new Gemini('/path/to/config');

console.log(gemini.config.rootUrl);

Reading the tests

gemini.readTests(paths, options) — read all of the tests from specified paths into one suite collection.

Options:

Returns promise which resolves to a SuiteCollection object.

Here is the example that prints all top level suite names:

var Gemini = require('gemini/api'),
    gemini = new Gemini('/path/to/config');

gemini.readTests()
    .done(function(collection) {
        collection.topLevelSuites().forEach(function(suite) {
            console.log(suite.name);
        });
    });

Suite Collection

You can create SuiteCollection object by using gemini.SuiteCollection constructor. Also SuiteCollection object is returned by gemini.readTests method.

SuiteCollection API:

suite can be a real suite object, or suite full name

opts are optional: * opts.browser — browser to disable suite in * opts.state — disable only specified state

Example on how to run only certain states in certain browsers:

var collection = gemini.readTests(paths),
    suite = findSomeSuite(collection);

collection
  .disableAll()
  .enable(suite, {state: 'some-state', browser: 'ie9'})
  .enable(suite, {state: 'other-state', browser: 'firefox'});

return gemini.test(collection);

Suite

Suite objects have the following properties:

State

Suite objects have the following properties:

Methods:

Updating reference screenshots

Use gemini.update(paths, options) method. By default, this command will update reference images that have diff and generate new reference images for new tests.

paths is the array of file paths or directories to run the suites from or SuiteCollection instance.

Options:

Returns promise that resolve to a stats object with following keys:

Rejects promise if critical error occurred.

Running tests

Use gemini.test(paths, options) method.

paths is the array of file paths or directories to run the tests from or SuiteCollection instance.

Options:

Returns promise that resolve to a stats object with following keys:

Rejects promise if critical error occurred.

Halting

gemini.halt(error, [timeout=60000ms]);

Method for abnormal termination of the test run in case of a terminal error. If process fails to gracefully shutdown in timeout milliseconds, it would be forcibly terminated (unless timeout is explicitly set to 0).

Utilites

Events

gemini instance emits some events, which can be used by external scripts or plugins.

See the details about available events.

Plugin example with the listening on the events:

module.exports = (gemini, options) => {
    gemini.on(gemini.events.START_RUNNER, () => {
        return setUp(gemini.config, options.param); // config can be mutated
    });

    gemini.on(gemini.events.END_RUNNER, () => {
        return tearDown();
    });
};