Core API

Mocha Bindings: testium-mocha

There are two general ways of interacting with the mocha bindings. The first (and older) way is to use the browser property on the test context:

var injectBrowser = require('testium-mocha');

describe('test-suite' ,() => {
  before(injectBrowser());

  it('has a browser', function() {
    return this.browser.navigateTo('/');
  });
});

The problem is that this works very poorly with ES6 arrow functions since it depends on the implicit test context. The more ES6-friendly interface is:

const { browser } = require('testium-mocha');

describe('test-suite' ,() => {
  before(browser.beforeHook());

  it('is the browser', () => browser.loadPage('/'));
});

Warning: Testium switches out the prototype of browser to turn the browser export “magically” into a functioning object after successful initialization. Trying to call anything but beforeHook before the hook finished will not work as expected.

injectBrowser(options = {})

Returns a mocha before hook. The hook will initialize Testium (if it didn’t happen already) and apply a number of changes to the current test suite:

• Intercept errors and automatically save screenshots.
• Override the default timeouts using the mocha.timeout setting.
• Install an after hook to ensure everything is properly cleaned up.
• Inject a browser property onto the test context.
• Switch out the prototype of the browser export to point to testium.browser.

The options are forwarded to getTestium

browser

After browser.beforeHook has been executed, this object will be a proxy to testium.browser.

browser.beforeHook

This is an alias for injectBrowser.

Low-Level API: testium-core

Most of the time it won’t be necessary to interact with testium-core directly. But when implementing a new kind of browser interface or integrating with a different test framework, the information below might be helpful.

getBrowser(options)

Convenience method that calls getTestium and then returns the browser property.

getConfig()

Retrieves the config Testium will use. This can be useful for selectively disabling tests in certain browsers:

var getConfig = require('testium-core').getConfig;

describe('Feature that only works in real browsers', () => {
  if (getConfig().get('browser') === 'phantomjs') {
    return it.skip('Not supported in PhantomJS');
  }

  // Actual test code.
});

The advantage over testium.config is that getConfig() returns the value immediately without having to wait for the init to finish.

getTestium(options)

Returns a Promise of an object (testium) with the following properties:

• browser: The actual browser to interact with.
• config: An Map-like object that can be used to read and write config values.
• getInitialUrl: Function returning a URL to load before running any tests.
• getNewPageUrl: Function that generates a proxy-friendly URL.

The options allow for overriding a limited number of config options. Supported are driver, keepCookies, and reuseSession.

testium.browser

An instance of the requested driver implementation. The exact interface depends on the value of the driver setting.

Currently, the recommended driver is “wd”, see Promise Chains

The browser always has an appUrl property which contains the base url of the application under test.

testium.config

Exposes has/get/set methods to interact with the config. It will throw when someone attempts to read a config key that has no value. Accepts lodash-style property paths as keys.

testium.getInitialUrl()

Returns a URL to load before running any tests. This ensures that setCookie calls work before loading the first real page.

testium.getNewPageUrl(url, options = {})

Generates a proxy-friendly URL. Drivers use this when implementing navigateTo to get status code and header information among other things. Available options:

• query: Additional query parameters to add to the url.
• headers: Headers to inject into the request.