JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 3
  • Score
    100M100P100Q63398F
  • License MIT

W3C WebDriver client

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

npm version Build status All Contributors Dependency Status semantic-release

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

Tested on major browsers

Chrome FireFox Safari Internet Explorer PhantomJS
✅ ✅ ✅ ✅

Tested on most popular Node.js versions

6 7 8
✅ ✅ ✅

Getting started

1. Install the package

npm install w3c-webdriver

or

yarn add w3c-webdriver

2. Install a browser driver for WebDriver protocoll

Browser Driver package
Chrome chromedriver
FireFox geckodriver
Safari
Internet Explorer iedriver
PhantomJS phantomjs-prebuilt

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

npm install chromedriver

or

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';

(async () => {
  try {
    session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
        browserName: 'Chrome'
      }
    });
    await session.go('http://localhost:8080');
    const input = await session.findElement('css selector', '[name="first-name"]');
    await a.sendKeys('Hello World');
  } catch (err) {
    console.log(err.stack);
  } finally {
    session.delete();
  }
})();

🚧 Work in progress...

Sessions

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 ✅
Method URI Template Command Implementation
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 ✅

Command Contexts

Method URI Template Command Implementation
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

Elements

Method URI Template Command Implementation
GET /session/{session id}/element/active Get Active Element

Element Retrieval

Method URI Template Command Implementation
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

Element State

Method URI Template Command Implementation
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

Element Interaction

Method URI Template Command Implementation
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 ✅

Document Handling

Method URI Template Command Implementation
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 ✅

Cookies

Method URI Template Command Implementation
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

Actions

Method URI Template Command Implementation
POST /session/{session id}/actions Perform Actions
DELETE /session/{session id}/actions Release Actions

User Prompts

Method URI Template Command Implementation
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

Screen Capture

Method URI Template Command Implementation
GET /session/{session id}/screenshot Take Screenshot ✅
GET /session/{session id}/element/{element id}/screenshot Take Element Screenshot

API

newSession

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;

(async () => {
  try {
    session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
        browserName: 'Chrome'
      }
    });
  } catch (err) {
    console.log(err.stack);
  } finally {
    session.delete();
  }
})();

Returns Promise<Session> session

status

This function queries the WebDriver server's current status.

Parameters

  • url string WebDriver server URL

Examples

import webdriver from 'w3c-webdriver';

(async () => {
  try {
    const status = await webdriver.status('http://localhost:4444');
    // status = {
    //   build: { version: '1.2.0' },
    //   os: { name: 'mac', version: 'unknown', arch: '64bit' }
    // }
  } catch (err) {
    console.log(err.stack);
  } finally {
    session.delete();
  }
})();

Returns Promise<Object> status

Session

This object represents a WebDriver session.

Type: Object

Properties

Session.delete

Delete the session.

Examples

import webdriver from 'w3c-webdriver';

let session;

(async () => {
  try {
    session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
        browserName: 'Chrome'
      }
    });
  } catch (err) {
    console.log(err.stack);
  } finally {
    session.delete();
  }
})();

Returns Promise

Session.go

Navigate to a new URL.

Parameters

  • targetUrl string The URL to navigate to.

Examples

import webdriver from 'w3c-webdriver';

let session;

(async () => {
  try {
    session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
        browserName: 'Chrome'
      }
    });
    await session.go('http://localhost:8080');
  } catch (err) {
    console.log(err.stack);
  } finally {
    session.delete();
  }
})();

Returns Promise

Session.getTitle

Get the current page title.

Examples

import webdriver from 'w3c-webdriver';

let session;

(async () => {
  try {
    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'
  } catch (err) {
    console.log(err.stack);
  } finally {
    session.delete();
  }
})();

Returns Promise<string> The current page title.

Session.findElement

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;

(async () => {
  try {
    session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
        browserName: 'Chrome'
      }
    });
    await session.go('http://localhost:8080');
    const element = await session.findElement('css selector', 'h2');
    // element = <webdriver element>
  } catch (err) {
    console.log(err.stack);
  } finally {
    session.delete();
  }
})();

Returns Promise<Element>

Session.findElements

Search for multiple elements on the page, starting from the identified element. The located elements will be returned as a WebElement JSON objects. The table below lists the locator strategies that each server should support. Elements should be returned in the order located in the DOM.

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;

(async () => {
  try {
    session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
        browserName: 'Chrome'
      }
    });
    await session.go('http://localhost:8080');
    const elements = await session.findElements('css selector', 'h2');
    // elements = [<webdriver element>]
  } catch (err) {
    console.log(err.stack);
  } finally {
    session.delete();
  }
})();

Returns Promise<array<Element>>

Session.getTimeout

Gets timeout durations associated with the current session.

Examples

import webdriver from 'w3c-webdriver';

let session;

(async () => {
  try {
    session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
        browserName: 'Chrome'
      }
    });
    const timeout = await session.getTimeout();
    // timeout = {
    //   script: 30000,
    //   pageLoad: 60000,
    //   implicit: 40000
    // }
  } catch (err) {
    console.log(err.stack);
  } finally {
    session.delete();
  }
})();

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

Session.setTimeout

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;

(async () => {
  try {
    session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
        browserName: 'Chrome'
      }
    });
    await session.setTimeout({
      script: 30000,
      pageLoad: 60000,
      implicit: 40000
    });
  } catch (err) {
    console.log(err.stack);
  } finally {
    session.delete();
  }
})();

Returns Promise

Session.getPageSource

Returns a string serialization of the DOM of the current browsing context active document.

Examples

import webdriver from 'w3c-webdriver';

let session;

(async () => {
  try {
    session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
        browserName: 'Chrome'
      }
    });
    await session.go('http://localhost:8080');
    const source = await session.getPageSource();
    // source = '<!DOCTYPE html><head><title>...'
  } catch (err) {
    console.log(err.stack);
  } finally {
    session.delete();
  }
})();

Returns Promise<string> The current page source.

Session.executeScript

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;

(async () => {
  try {
    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!'
  } catch (err) {
    console.log(err.stack);
  } finally {
    session.delete();
  }
})();

Returns Promise<any> The script result.

Session.executeAsyncScript

causes JavaScript to execute as an anonymous function. Unlike the Execute Script command, the result of the function is ignored. Instead an additional argument is provided as the final argument to the function. This is a function that, when called, returns its first argument as the response.

Parameters

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

Examples

import webdriver from 'w3c-webdriver';

let session;

(async () => {
  try {
    session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
        browserName: 'Chrome'
      }
    });
    await session.go('http://localhost:8080');
    const script = `
      const [a, b, callback] = arguments;
      setTimeout(() => callback(a * b), 1000);
    `;
    const message = await session.executeAsyncScript(script, [5, 3]);
    // message = 15
  } catch (err) {
    console.log(err.stack);
  } finally {
    session.delete();
  }
})();

Returns Promise<any> The script result.

Session.getAllCookies

Returns all cookies associated with the address of the current browsing context’s active document.

Examples

import webdriver from 'w3c-webdriver';

let session;

(async () => {
  try {
    session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
        browserName: 'Chrome'
      }
    });
    await session.go('http://localhost:8080');
    const cookies = await session.getAllCookies();
    // cookies = [
    //   {
    //     name: 'cookie name',
    //     value: 'cookie value',
    //     path: '/',
    //     domain: 'localhost',
    //     secure: false,
    //     httpOnly: true
    //   }
    // ]
  } catch (err) {
    console.log(err.stack);
  } finally {
    session.delete();
  }
})();

Returns Promise<array<object>> A list of cookies.

Session.addCookie

Adds a single cookie to the cookie store associated with the active document’s address.

Parameters

  • cookie object An object defining the cookie to add.
    • cookie.name string The name of the cookie.
    • cookie.value string The cookie value.
    • cookie.path string? The cookie path. Defaults to "/" if omitted when adding a cookie.
    • cookie.domain string? The domain the cookie is visible to. Defaults to the current browsing context’s document’s URL domain if omitted when adding a cookie.
    • cookie.secure string? Whether the cookie is a secure cookie. Defaults to false if omitted when adding a cookie.
    • cookie.httpOnly string? Whether the cookie is an HTTP only cookie. Defaults to false if omitted when adding a cookie.
    • cookie.expiry string? When the cookie expires, specified in seconds since Unix Epoch. Defaults to 20 years into the future if omitted when adding a cookie.

Examples

import webdriver from 'w3c-webdriver';

let session;

(async () => {
  try {
    session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
        browserName: 'Chrome'
      }
    });
    await session.go('http://localhost:8080');
    await session.addCookie({ name: 'test cookie', value: 'test value' });
  } catch (err) {
    console.log(err.stack);
  } finally {
    session.delete();
  }
})();

Returns Promise

Session.takeScreenshot

The Take Screenshot command takes a screenshot of the top-level browsing context’s viewport.

Examples

import webdriver from 'w3c-webdriver';

let session;

(async () => {
  try {
    session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
        browserName: 'Chrome'
      }
    });
    await session.go('http://localhost:8080');
    const screenshot = await session.takeScreenshot();
    // screenshot = Buffer containing PNG
  } catch (err) {
    console.log(err.stack);
  } finally {
    session.delete();
  }
})();

Returns Promise<Buffer> The screenshot as a PNG.

Element

This object represents a WebDriver element.

Type: Object

Properties

Element.sendKeys

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;

(async () => {
  try {
    session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
        browserName: 'Chrome'
      }
    });
    await session.go('http://localhost:8080');
    const input = await session.findElement('css selector', '[name="first-name"]');
    await a.sendKeys('Hello World');
  } catch (err) {
    console.log(err.stack);
  } finally {
    session.delete();
  }
})();

Returns Promise

Element.click

Click on an element.

Examples

import webdriver from 'w3c-webdriver';

let session;

(async () => {
  try {
    session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
        browserName: 'Chrome'
      }
    });
    await session.go('http://localhost:8080');
    const submitButton = await session.findElement('css selector', 'button[type="submit"]');
    await submitButton.click();
  } catch (err) {
    console.log(err.stack);
  } finally {
    session.delete();
  }
})();

Returns Promise

Element.getText

Returns the visible text for the element.

Examples

import webdriver from 'w3c-webdriver';

let session;

(async () => {
  try {
    session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
        browserName: 'Chrome'
      }
    });
    await session.go('http://localhost:8080');
    const result = await session.findElement('css selector', '#result');
    const text = await result.getText();
    // test = <result>
  } catch (err) {
    console.log(err.stack);
  } finally {
    session.delete();
  }
})();

Returns Promise<string> Visible text for the element.

Element.getCss

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;

(async () => {
  try {
    session = await webdriver.newSession('http://localhost:4444', {
      desiredCapabilities: {
        browserName: 'Chrome'
      }
    });
    await session.go('http://localhost:8080');
    const button = await session.findElement('css selector', '#red-button');
    const backgroundColor = await button.getCss('background-color');
    // backgroundColor = 'rgba(255, 0, 0, 1)'
  } catch (err) {
    console.log(err.stack);
  } finally {
    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!