WebDriver client for JavaScript

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


✅	✅	✅

Getting started

1. Install the package

npm install w3c-webdriver

2. Install a browser driver for WebDriver protocoll

Browser	Driver package
	chromedriver
	geckodriver

	iedriver

|

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

npm install 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	✅

Navigation

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

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;

(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

See: WebDriver spec

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

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;

(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

See: WebDriver spec

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

See: WebDriver spec

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

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;

(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

See: WebDriver spec

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

See: WebDriver spec

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

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;

(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

See: WebDriver spec

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

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;

(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

See: WebDriver spec

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

See: WebDriver spec

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

See: WebDriver spec

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

See: WebDriver spec

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

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;

(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

See: WebDriver spec

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

See: WebDriver spec

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

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;

(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!

Name		Name	Last commit message	Last commit date
Latest commit History 67 Commits
src		src
test-app		test-app
test		test
.all-contributorsrc		.all-contributorsrc
.babelrc		.babelrc
.editorconfig		.editorconfig
.eslintignore		.eslintignore
.eslintrc		.eslintrc
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
appveyor.yml		appveyor.yml
package-lock.json		package-lock.json
package.json		package.json

License

4qu3l3c4r4/W3C_WebDriver

Folders and files

Latest commit

History

Repository files navigation

WebDriver client for JavaScript

Getting started

1. Install the package

2. Install a browser driver for WebDriver protocoll

3. Start the driver as described in the docs

4. Control the browser through WebDriver protocoll

🚧 Work in progress...

Sessions

Navigation

Command Contexts

Elements

Element Retrieval

Element State

Element Interaction

Document Handling

Cookies

Actions

User Prompts

Screen Capture

API

newSession

status

Session

Session.delete

Session.go

Session.getTitle

Session.findElement

Session.findElements

Session.getTimeout

Session.setTimeout

Session.getPageSource

Session.executeScript

Session.executeAsyncScript

Session.getAllCookies

Session.addCookie

Session.takeScreenshot

Element

Element.sendKeys

Element.click

Element.getText

Element.getCss

Contributors

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Contributors 3

Languages

Packages