node package manager
It’s your turn. Help us improve JavaScript. Take the 2017 JavaScript Ecosystem Survey »



Build Status

The aim of Selene is to provide a WebDriver API with a strong focus on developer experience (DX).

Unlike other webdriver libraries, Selene uses the official Selenium JavaScript bindings. This has the big advantage that you don't need a Selenium server in order to control browsers on your local machine. This does not only make things much easier to set up but also makes things considerably faster as it saves a lot of roundtrips.

While being very powerful, the official API sometimes feels a little alien to JavaScript developers as it is very closely modeled after its Java ancestor.


var selene = require('selene');
var se = selene();
se.fill({ q: 'selene npm' });'[jsaction=sf.lck]');



Selene adds the concept of locators, filters and conditions on top of the WebDriver API.


By default Selene supports the following locators:

// CSS selectors 
// XPath expressions 
se.find({ xpath: '//main' });
// Client-side functions 
se.find('ul').find({ js: function (el) {
  return el.firstChild;

You can add custom locators via the addLocator() method.


When locating elements Selene also provides a way to filter the results. By default the following filters are supported:

se.find('.button', { visible: true });
se.find('.button', { text: 'click me' });
se.find('.button', { text: /click/ });

You can add custom filters via the addFilter() method.


You can use Selene to wait for certain conditions to be met. The following conditions are supported by default:

se.wait({ url: '/welcome' }, 2000);
se.wait({ title: /Selene/ }, 2000);
se.wait(() => se.find('.foo').find('.bar'), 2000);
se.wait({ stale: se.find('body') }, 2000);

You can add custom conditions via the addCondition() method.


The top-level selene() function is a factory for Selene instances which are thin wrappers around Selenium WebDriver objects.


In addition to the WebDriver API, Selene instances provide the following methods:


goto(url) – Navigates to the given URL. Relative paths will be resolved against the configured base URL. Returns this for chaining.


Returns a SeElementPromise for the first matching DOM element.

find(locator, [filter], [timeout])

  • locator: The locator to use
  • filter: An optional filter
  • timeout: Optional timeout in milliseconds to wait for the element


Returns a promise for an Array of all matching DOM elements. Takes the same arguments as find().


Shorthand for finding and clicking on an element.

click(locator, [filter], [timeout])


Returns a promise for a boolean value indicating whether the specified element exists.

exists(locator, [filter])


Wraps the Selenium WebDriver wait method to support custom conditions.

wait(condition, [timeout], [message])

  • condition: The condition to wait for
  • timeout: Optional timeout in milliseconds to wait
  • message: Optional error message in case of a timeout


Reloads the page until the given condition is met. Takes the same arguments as wait().


Fills multiple input elements at once. The input elements are looked up using a CSS attribute selector. By default Selene expects each element to have a unique name attribute. Optionally a custom attribute can be specified. Returns this for chaining.

fill([attribute], values)

  • attribute: Attribute name to use in CSS selectors. Defaults to name
  • values: The values to be filled in
  user: 'John',
  email: ''
// shortcut for: 


Fetches available log entries for a given type since the last call to this method, or from the start of the session.


  • type: The log type to fetch. Can be browser, client, driver, performance or server.
// activate logging 
var se = selene({
  logging: {
    browser: 'severe',
    driver: 'debug'
// fetch browser logs 
se.getLogEntries('browser').then(entries => {
  console.log( => e.message));


Registers a custom locator.


  • fn A function that takes an arbitrary query object as argument and returns { description: String, by: ( | Function) } if it wants to handle the given query.

The following example adds a locator that uses jQuery to locate elements:

se.addLocator(query => {
  // Handle only objects that have a `jQuery` property 
  if (typeof query === 'object' && 'jQuery' in query) {
    const selector = query.$;
    return {
      description: `$(${selector})`, // description used in error messages 
      by: driver => driver.executeScript(jQuery, selector)
  // This function gets executed inside the browser: 
  function jQuery(selector) {
    if (!window.$) throw new Error('jQuery not found in global scope');
    return window.$(selector);
// Use it like this: 
se.find({jQuery: 'div:animated' });


Registers a custom filter.


  • fn A function that takes an arbitrary filter object as argument and returns { description: String, test: Function) } if it wants to handle the given filter.

The following example adds a min-width filter:

se.addFilter(filter => {
  if (filter.minWidth) {
    return {
      description: `width >= ${filter.minWidth}px`,
      test(el) {
        return el.getSize().then(size => size.width >= filter.minWidth);
// Use it like this: 
se.find('img', { minWidth: 200 });


Registers a custom condition.


  • fn A function that takes an arbitrary until object as argument and returns a webdriver.until.Contition if it wants to handle the given object.


Registers a plugin.



SeElement extends Selenium's WebElement and adds the following methods:


attr(name) – Returns a promise for the value of the attribute with the specified name. Alias for getAttribute(name)


css(prop) – Returns the runtime CSS style of the given property. Alias for getCssValue(prop)


find(locator, [filter], [timeout]) – Scoped version of se.find() that only takes the element's descendants into account.


findAll(selector, [filter], [timeout]) – Scoped version of se.findAll() that only takes the element's descendants into account.


fill([attribute], values) – Scoped version of se.fill() that only takes the element's descendants into account.


parent() – Returns a SeElementPromise for the element's parent node.


type(text) – Sends keystrokes to the element to type the given text.


press(sequence) – Sends a sequence of key combinations to the element.

The given sequence is split at spaces into chords. Each chord is then split at + or - into keys. If a key is not found in the list of supported key names all the characters will be pressed at once.'ctrl+a ctrl+x'); // sequence of 2 chords'ctrl-alt-delete'); // minus signs work too'alt++ alt-+ ALT-+'); // synonym'qwertz'); // press all at once'h e l l o SPACE w o r l d'); // hello world 


dragDrop(target) – Drags the element to the given target.

The target can either be a SeElement or {x: number, y: number} or a promise for either of both.


SeElementPromise mixes both SeElement and an A+ compatible promise interface. This allows calls to the SeElement API before the underlying element promise has been fulfilled.


Option Description
base Base URL against which all relative paths are resolved.
auth Credentials for HTTP basic authentication.
var se = selene({
  base: '',
  auth: {
    user: 'user',
    pass: 'secret'
se.goto('/').click('a[href="/welcome"]').wait({ url: '/welcome' });

The following options map 1:1 to the underlying WebDriver settings. For the meaning of each option please refer to the linked Selenium docs.

Option Description
alerts Sets how alert popups should be handled. Can be either "accept", "dismiss" or "ignore". Defaults to "dismiss".
nativeEvents Whether native events should be used.
proxyURL URL of the proxy to use for the WebDriver's HTTP connections.
remoteURL URL of a remote WebDriver server to use. As an alternative to this method, you may also set the SELENIUM_REMOTE_URL environment variable.
scrollTo How elements should be scrolled into view for interaction. Can either be "top" or "bottom".
logging Set the log level of different log types. Valid types are: browser, client, driver, performance or server. Valid levels are: off, severe, warning, info, fine, finer, finest, debug or all.
capabilities The desired capabilities when requesting a new session.
envOverrides Whether to allow the configuration to be overwritten by environment variables. Defaults to true.
browser The desired target browser. You may also specify a browser by setting the SELENIUM_BROWSER environment variable to browser[:[version][:platform]]. Defaults to firefox

Additionally you can provide browser-specific options under the keys chrome, opera, safari, ie, edge or firefox.


All objects created by Selene inherit from their official counterparts, hence checks like se instanceof webdriver.WebDriver will still pass and you can use Selene as drop-in replacement inside your existing code.

Test runners

Selene does not come with its own test runner nor is it bound to a specific assertion framework. You can use whatever tool you want for that. The following example uses Mocha and unexpected-webdriver.

var selene = require('selene');
var expect = require('unexpected');
describe('Google', function () {
  this.timeout(60000); // don't timeout too quickly 
  it('should go to the selene npm page', function () {
    var se = selene();
    se.fill({ q: 'selene npm' });'[jsaction=sf.lck]');
    se.wait({ url: '' });
    var name = se.find('.package-name');
    return expect(name, 'to contain text', 'selene');