selenium-assistant

A node module that helps using browsers with selenium

SeleniumAssistant

When you require in the selenium-assistant module an instance of this SeleniumAssistant class will be returned.

This method gives you the require API's to manage downloading of browsers, accessing required browsers and making use of SaucesLabs.

Example

Usage in Node

const seleniumAssistant = require('selenium-assistant');

const browsers = seleniumAssistant.getLocalBrowsers();
browsers.map(browser => {
  console.log(browsers.getPrettyName());
  console.log(browsers.getReleaseName());

  return browser.getSeleniumDriver()
  .then((driver) => {
    return driver.get('https://google.com/')
    .then(() => {
     return seleniumAssistant.killWebDriver(driver);
    });
  });
});

Instance Methods

this.downloadLocalBrowser(browserId, release, expirationInHours) → Promise

This downloads a browser with browser ID of 'chrome' or 'firefox' and a release type of 'stable', 'beta', 'unstable'. SeleniumAssistant will download the browser and keep a track of when it was last downloaded.

The next time a download is requested, seleniumAssistant will check if the browser is within the expirationInHours parameter and if it is, resolve the promise.

Any programs using selenium-assistant will share the same browser downloads reducing overall download time (unless setBrowserInstallDir() is called with a unique directory).

Example
return Promise.all([
  seleniumAssistant.downloadLocalBrowser('chrome', 'stable', 48),
  seleniumAssistant.downloadLocalBrowser('chrome', 'beta', 48),
  seleniumAssistant.downloadLocalBrowser('chrome', 'unstable', 48),
  seleniumAssistant.downloadLocalBrowser('firefox', 'stable', 48),
  seleniumAssistant.downloadLocalBrowser('firefox', 'beta', 48),
  seleniumAssistant.downloadLocalBrowser('firefox', 'unstable', 48),
])
.then(() => {
  console.log('Browser download complete.');
})
.catch((err) => {
  console.error('Browser download failed.');
});
Parameters
browserId String

The selenium ID of the browser you wish to download.
release String

The release channel of the browser. Can be 'stable', 'beta' or 'unstable'
expirationInHours Number (Optional) 24

This is how long until a browser download is regarded as expired and should be updated. A value of 0 will force a download.
Returns Promise

The promise resolves once the browser has been downloaded.

this.getBrowserInstallDir() → String

Returns the browser download path.

Returns String

Path of downloaded browsers

this.getLocalBrowser(browserId, release) → LocalBrowser

Most users of this library will want to make use of getLocalBrowsers to get all available browsers in the current environment.

If you need a specific browser use this method to retrieve it. Use LocalBrowser.isValid() to check if the browser is available on the current environment.

Parameters
browserId String

The selenium id of the browser you want.
release String

The release of the browser you want. Either 'stable', 'beta' or 'unstable.'
Returns LocalBrowser

A LocalBrowser instance that represents your request.

this.getLocalBrowsers() → Array.<LocalBrowser>

This method returns a list of available browsers in the current environment.

This method will throw an error if run on a platform other than OS X and Linux.

Returns Array.<LocalBrowser>

Array of browsers discovered in the current environment.

this.getSauceLabsBrowser(browserId, browserVersion, options) → SauceLabsBrowser

Get a Sauce Labs hosted browser for a particular browser ID and a particular browser version.

Example
seleniumAssistant.setSaucelabsDetails(myusername, myaccesskey);
seleniumAssistant.startSaucelabsConnect()
.then(() => {
  return seleniumAssistant.getSauceLabsBrowser('edge', 'latest');
})
.then((browserInstance) => {
  return browserInstance.getSeleniumDriver();
})
.then((driver) => {
  return driver.get('http://localhost:8080/')
  .then(() => {
    return seleniumAssistant.killWebDriver(driver);
  });
})
.then(() => {
  return seleniumAssistant.stopSaucelabsConnect();
});
Parameters
browserId String

The selenium browser ID.
browserVersion String

The Sauce Labs browser version, i.e. "latest", "latest-2", "48.0".
options Object

Any options that you wish to set on the browser that are for Sauce Labs rather than configuration of the browser.
Returns SauceLabsBrowser

A selenium-assistant web driver instance.

this.killWebDriver(driver) → Promise

Once a web driver is no longer needed, call this method to kill it.

This is a basic helper that adds a timeout to the end of killling the driver to account for shutdown time and the issues that can be caused if a new driver is launched too soon before the previous end of a driver.

Parameters
driver WebDriver

An instance of WebDriver
Returns Promise

Promise that resolves once the browser is killed.

this.printAvailableBrowserInfo(printToConsole) → String

This method prints out a table of info for all available browsers on the current environment.

Useful if you are testing on Travis and want to see what tests should be running, but be cautious to print this only at the start of your tests to avoid excessive logging.

Parameters
printToConsole Boolean (Optional) true

If you wish to prevent the table being printed to the console, you can suppress it by passing in false and simply get the string response.
Returns String

Returns table of information as a string.

this.setBrowserInstallDir(newInstallDir)

To change where browsers are downloaded to, call this method before calling downloadLocalBrowser() and getLocalBrowsers().

By default, this will install under .selenium-assistant in your home directory on OS X and Linux, or just selenium-assistant in your home directory on Windows.

Parameters
newInstallDir String

Path to download browsers to. Pass in null to use default path.

this.setSaucelabsDetails(username, accessKey)

If you wish to use Sauce Labs to host the browser instances you can do so by setting your saucelab details with this method before calling getSauceLabsBrowser().

Parameters
username String

The Sauce Labs username.
accessKey String

The Sauce Labs access key.

this.startSaucelabsConnect() → Promise

The Sauce Labs proxy allows a browser running on Sauce Labs to load a localhost site.

Calling this method will start the Sauce Labs connect proxy.

Returns Promise

Returns a promise that resolves once the proxy is set up.

this.stopSaucelabsConnect() → Promise

The Sauce Labs proxy allows a browser running on Sauce Labs to load a localhost site.

Calling this method will stop the Sauce Labs connect proxy.

Returns Promise

Returns a promise that resolves once the proxy is closed.