Package Exports

w3c-webdriver

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (w3c-webdriver) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

WebDriver client for JavaScript

Zero dependency minimal JavaScript bindings that conform to the W3C WebDriver standard, which specifies a remote control protocol for web browsers.

Tested on major browsers


✅	✅		✅	✅

Tested on most popular Node.js versions

6	7	8
✅	✅	✅

Getting started

1. Install the package

npm install w3c-webdriver

yarn add w3c-webdriver

2. Install a browser driver for WebDriver protocoll

Browser	Driver package
	chromedriver
	geckodriver

	iedriver
	phantomjs-prebuilt

For example in case of Google Chrome or its headless version you can do.

npm install chromedriver

yarn add chromedriver

Also you can manage the drivers using webdriver-manager

3. Start the driver as described in the docs

4. Control the browser through WebDriver protocoll

import webdriver from 'w3c-webdriver';

let session;

const start = async () => {
  session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
          browserName: 'Chrome'
      }
  });
  await session.go('http://localhost:8080');
  const input = await session.findElement('css', '[name="first-name"]');
  await a.sendKeys('Hello World');
};

start()
 .catch(err => console.log(err.stack))
 .then(() => session.delete());

🚧 Work in progress...

Method	URI Template	Command	Implementation
POST	/session	New Session	✅
DELETE	/session/{session id}	Delete Session	✅
GET	/status	Status	✅
GET	/session/{session id}/timeouts	Get Timeouts	✅
POST	/session/{session id}/timeouts	Set Timeouts	✅
POST	/session/{session id}/url	Go	✅
GET	/session/{session id}/url	Get Current URL
POST	/session/{session id}/back	Back
POST	/session/{session id}/forward	Forward
POST	/session/{session id}/refresh	Refresh
GET	/session/{session id}/title	Get Title	✅
GET	/session/{session id}/window	Get Window Handle
DELETE	/session/{session id}/window	Close Window
POST	/session/{session id}/window	Switch To Window
GET	/session/{session id}/window/handles	Get Window Handles
POST	/session/{session id}/frame	Switch To Frame
POST	/session/{session id}/frame/parent	Switch To Parent Frame
GET	/session/{session id}/window/rect	Get Window Rect
POST	/session/{session id}/window/rect	Set Window Rect
POST	/session/{session id}/window/maximize	Maximize Window
POST	/session/{session id}/window/minimize	Minimize Window
POST	/session/{session id}/window/fullscreen	Fullscreen Window
GET	/session/{session id}/element/active	Get Active Element
POST	/session/{session id}/element	Find Element	✅
POST	/session/{session id}/elements	Find Elements
POST	/session/{session id}/element/{element id}/element	Find Element From Element
POST	/session/{session id}/element/{element id}/elements	Find Elements From Element
GET	/session/{session id}/element/{element id}/selected	Is Element Selected
GET	/session/{session id}/element/{element id}/attribute/{name}	Get Element Attribute
GET	/session/{session id}/element/{element id}/property/{name}	Get Element Property
GET	/session/{session id}/element/{element id}/css/{property name}	Get Element CSS Value	✅
GET	/session/{session id}/element/{element id}/text	Get Element Text	✅
GET	/session/{session id}/element/{element id}/name	Get Element Tag Name
GET	/session/{session id}/element/{element id}/rect	Get Element Rect
GET	/session/{session id}/element/{element id}/enabled	Is Element Enabled
POST	/session/{session id}/element/{element id}/click	Element Click	✅
POST	/session/{session id}/element/{element id}/clear	Element Clear
POST	/session/{session id}/element/{element id}/value	Element Send Keys	✅
GET	/session/{session id}/source	Get Page Source
POST	/session/{session id}/execute/sync	Execute Script	✅
POST	/session/{session id}/execute/async	Execute Async Script
GET	/session/{session id}/cookie	Get All Cookies
GET	/session/{session id}/cookie/{name}	Get Named Cookie
POST	/session/{session id}/cookie	Add Cookie
DELETE	/session/{session id}/cookie/{name}	Delete Cookie
DELETE	/session/{session id)/cookie	Delete All Cookies
POST	/session/{session id}/actions	Perform Actions
DELETE	/session/{session id}/actions	Release Actions
POST	/session/{session id}/alert/dismiss	Dismiss Alert
POST	/session/{session id}/alert/accept	Accept Alert
GET	/session/{session id}/alert/text	Get Alert Text
POST	/session/{session id}/alert/text	Send Alert Text
GET	/session/{session id}/screenshot	Take Screenshot
GET	/session/{session id}/element/{element id}/screenshot	Take Element Screenshot

API

newSession

See: WebDriver spec

This function creates a new WebDriver session.

Parameters

url string WebDriver server URL
options object configuration object for creating the session

Examples

import webdriver from 'w3c-webdriver';

let session;

const start = async () => {
  session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
          browserName: 'Chrome'
      }
  });
};

start()
 .catch(err => console.log(err.stack))
 .then(() => session.delete());

Returns Promise<Session> session

status

See: WebDriver spec

This function queries the WebDriver server's current status.

Parameters

url string WebDriver server URL

Examples

import webdriver from 'w3c-webdriver';

const start = async () => {
  const status = await webdriver.status('http://localhost:4444');
  // status = {
  //   build: { version: '1.2.0' },
  //   os: { name: 'mac', version: 'unknown', arch: '64bit' }
  // }
};

start().catch(err => console.log(err.stack));

Returns Promise<Object> status

Session

This object represents a WebDriver session.

Type: Object

Properties

delete Session.delete Delete the session.
go Session.go Navigate to a new URL.
getTitle Session.getTitle Get the current page title.
findElement Session.findElement Search for an element on the page, starting from the document root.

Session.delete

See: WebDriver spec

Delete the session.

Examples

import webdriver from 'w3c-webdriver';

let session;

const start = async () => {
  session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
          browserName: 'Chrome'
      }
  });
};

start()
 .catch(err => console.log(err.stack))
 .then(() => session.delete());

Returns Promise

Session.go

See: WebDriver spec

Navigate to a new URL.

Parameters

targetUrl string The URL to navigate to.

Examples

import webdriver from 'w3c-webdriver';

let session;

const start = async () => {
  session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
          browserName: 'Chrome'
      }
  });
  await session.go('http://localhost:8080');
};

start()
 .catch(err => console.log(err.stack))
 .then(() => session.delete());

Returns Promise

Session.getTitle

See: WebDriver spec

Get the current page title.

Examples

import webdriver from 'w3c-webdriver';

let session;

const start = async () => {
  session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
          browserName: 'Chrome'
      }
  });
  await session.go('http://localhost:8080');
  const title = await session.getTitle();
  // title = 'web page title'
};

start()
 .catch(err => console.log(err.stack))
 .then(() => session.delete());

Returns Promise<string> The current page title.

Session.findElement

See: WebDriver spec

Search for an element on the page, starting from the document root.

Parameters

strategy string Locator strategy ("css selector", "link text", "partial link text", "tag name", "xpath").
selector string Selector string.

Examples

import webdriver from 'w3c-webdriver';

let session;

const start = async () => {
  session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
          browserName: 'Chrome'
      }
  });
  await session.go('http://localhost:8080');
  const element = await session.findElement('css', 'h2');
  // element = <webdriver element>
};

start()
 .catch(err => console.log(err.stack))
 .then(() => session.delete());

Returns Promise<Element>

Session.getTimeout

See: WebDriver spec

Gets timeout durations associated with the current session.

Examples

import webdriver from 'w3c-webdriver';

let session;

const start = async () => {
  session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
          browserName: 'Chrome'
      }
  });
  const timeout = await session.getTimeout();
  // timeout = {
  //   script: 30000,
  //   pageLoad: 60000,
  //   implicit: 40000
  // }
};

start()
 .catch(err => console.log(err.stack))
 .then(() => session.delete());

Returns Promise<object> Timeout durations associated with the current session in milliseconds.

Session.setTimeout

See: WebDriver spec

Configure the amount of time that a particular type of operation can execute for before they are aborted and a |Timeout| error is returned to the client.

Parameters

timeouts object Timout configuration object with values in milliseconds.
- timeouts.script number Session script timeout - Determines when to interrupt a script that is being evaluated.
- timeouts.pageLoad number Session page load timeout - Provides the timeout limit used to interrupt navigation of the browsing context.
- timeouts.implicit number Session implicit wait timeout -Gives the timeout of when to abort locating an element.

Examples

import webdriver from 'w3c-webdriver';

let session;

const start = async () => {
  session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
          browserName: 'Chrome'
      }
  });
  await session.setTimeout({
    script: 30000,
    pageLoad: 60000,
    implicit: 40000
  });
};

start()
 .catch(err => console.log(err.stack))
 .then(() => session.delete());

Returns Promise

Session.executeScript

See: WebDriver spec

Inject a snippet of JavaScript into the page for execution in the context of the currently selected frame. The executed script is assumed to be synchronous and the result of evaluating the script is returned to the client.

Parameters

script string The script to execute.
args array The script arguments.

Examples

import webdriver from 'w3c-webdriver';

let session;

const start = async () => {
  session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
          browserName: 'Chrome'
      }
  });
  await session.go('http://localhost:8080');
  const script = 'const [from] = arguments; return `Hello from ${from}!`;';
  const message = await session.executeScript(script, ['WebDriver']);
  // message = 'Hello from WebDriver!'
};

start()
 .catch(err => console.log(err.stack))
 .then(() => session.delete());

Returns Promise<any> The script result.

Element

This object represents a WebDriver element.

Type: Object

Properties

sendKeys Element.sendKeys Send a sequence of key strokes to an element.
click Element.click Click on an element.
getText Element.getText Returns the visible text for the element.
getCss Element.getCss Returns the computed value of the given CSS property for the element.

Element.sendKeys

See: WebDriver spec

Send a sequence of key strokes to an element.

Parameters

text string The sequence of keys to type.

Examples

import webdriver from 'w3c-webdriver';

let session;

const start = async () => {
  session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
          browserName: 'Chrome'
      }
  });
  await session.go('http://localhost:8080');
  const input = await session.findElement('css', '[name="first-name"]');
  await a.sendKeys('Hello World');
};

start()
 .catch(err => console.log(err.stack))
 .then(() => session.delete());

Returns Promise

Element.click

See: WebDriver spec

Click on an element.

Examples

import webdriver from 'w3c-webdriver';

let session;

const start = async () => {
  session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
          browserName: 'Chrome'
      }
  });
  await session.go('http://localhost:8080');
  const submitButton = await session.findElement('css', 'button[type="submit"]');
  await submitButton.click();
};

start()
 .catch(err => console.log(err.stack))
 .then(() => session.delete());

Returns Promise

Element.getText

See: WebDriver spec

Returns the visible text for the element.

Examples

import webdriver from 'w3c-webdriver';

let session;

const start = async () => {
  session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
          browserName: 'Chrome'
      }
  });
  await session.go('http://localhost:8080');
  const result = await session.findElement('css', '#result');
  const text = await result.getText();
  // test = <result>
};

start()
 .catch(err => console.log(err.stack))
 .then(() => session.delete());

Returns Promise<string> Visible text for the element.

Element.getCss

See: WebDriver spec

Returns the computed value of the given CSS property for the element.

Parameters

propertyName string CSS property.

Examples

import webdriver from 'w3c-webdriver';

let session;

const start = async () => {
  session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
          browserName: 'Chrome'
      }
  });
  await session.go('http://localhost:8080');
  const button = await session.findElement('css', '#red-button');
  const backgroundColor = await button.getCss('background-color');
  // backgroundColor = 'rgba(255, 0, 0, 1)'
};

start()
 .catch(err => console.log(err.stack))
 .then(() => session.delete());

Returns Promise<string> Computed CSS property value for the element.

Contributors

Thanks goes to these wonderful people :

_{Igor Muchychka}	_{Gabor Szalay}	_{Adam Graf}	_{Roland Orosz}

This project follows the all-contributors specification. Contributions of any kind welcome!