node package manager


Build Status

friendly-webdriver ūüöē

This is a thin wrapper around the official Selenium JavaScript bindings.

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

NOTE: Since friendly-webdriver uses the official bindings under the hood 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.


var webdriver = require('friendly-webdriver');
var fwd = webdriver();
fwd.fill({ q: 'friendly-webdriver npm' });'[jsaction=sf.lck]');



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


By default FWD supports the following locators:

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

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


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

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

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


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

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

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


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


In addition to the WebDriver API, FriendlyWebDriver 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 FwdElementPromise 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 FWD 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 fwd = webdriver({
  logging: {
    browser: 'severe',
    driver: 'debug'
// fetch browser logs 
fwd.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:

fwd.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: 
fwd.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:

fwd.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: 
fwd.find('img', { minWidth: 200 });


Registers a custom condition.


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


Registers a plugin.



FwdElement 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 fwd.find() that only takes the element's descendants into account.


findAll(selector, [filter], [timeout]) ‚Äď Scoped version of fwd.findAll() that only takes the element's descendants into account.


fill([attribute], values) ‚Äď Scoped version of fwd.fill() that only takes the element's descendants into account.


parent() ‚Äď Returns a FwdElementPromise 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 FwdElement or {x: number, y: number} or a promise for either of both.


FwdElementPromise mixes both FwdElement and an A+ compatible promise interface. This allows calls to the FwdElement 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 fwd = webdriver({
  base: '',
  auth: {
    user: 'user',
    pass: 'secret'
fwd.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 FWD inherit from their official counterparts, hence checks like se instanceof webdriver.WebDriver will still pass and you can use FWD as drop-in replacement inside your existing code.

Test runners

FWD 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 webdriver = require('friendly-webdriver');
var expect = require('unexpected').clone();
describe('Google', function () {
  this.timeout(60000); // don't timeout too quickly 
  it('should go to the FWD npm page', function () {
    var se = FWD();
    fwd.fill({ q: 'friendly-webdriver npm' });'[jsaction=sf.lck]');
    fwd.wait({ url: '' });
    var name = fwd.find('.package-name');
    return expect(name, 'to contain text', 'FWD');


This project was originally released under the name Selene and was later renamed to avoid confusion with the Selene Python library and its Jselene counterpart.