or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

browser-sessions.mdconfiguration.mdelement-location.mdindex.mdjavascript-execution.mdmobile-testing.mdnavigation.mdtouch-actions.mduser-input.mdwaiting.mdwindow-management.md
tile.json

tessl/npm-wd

WebDriver/Selenium 2 Node.js client for browser automation and testing

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/wd@1.14.x

To install, run

npx @tessl/cli install tessl/npm-wd@1.14.0

index.mddocs/

WD WebDriver Client

WD is a comprehensive WebDriver/Selenium 2 Node.js client library that provides automated browser testing and web scraping capabilities. It offers multiple programming paradigms including pure async callbacks, Q promises with chaining, and promise-based APIs, supporting all major browsers through the JsonWire Protocol and W3C WebDriver standards.

Package Information

  • Package Name: wd
  • Package Type: npm
  • Language: JavaScript (Node.js)
  • Installation: npm install wd

Core Imports

// Choose your preferred API style
const wd = require('wd');

// Pure async callbacks (default)
const browser = wd.remote();

// Q promises without chaining
const browser = wd.promiseRemote();

// Q promises with chaining (most popular)
const browser = wd.promiseChainRemote();

// Or explicitly specify type
const browser = wd.remote('promiseChain');

ES6 modules:

import wd from 'wd';
const browser = wd.promiseChainRemote();

Basic Usage

Promise Chain Style (Recommended)

const wd = require('wd');
const browser = wd.promiseChainRemote();

browser
  .init({browserName: 'chrome'})
  .get('http://example.com')
  .title()
  .then(title => console.log('Page title:', title))
  .elementById('submit-button')
  .click()
  .sleep(1000)
  .quit();

Pure Async Style

const wd = require('wd');
const browser = wd.remote();

browser.init({browserName: 'chrome'}, function(err) {
  if (err) throw err;
  browser.get('http://example.com', function(err) {
    if (err) throw err;
    browser.title(function(err, title) {
      console.log('Page title:', title);
      browser.quit();
    });
  });
});

Promise Style (No Chaining)

const wd = require('wd');
const browser = wd.promiseRemote();

async function example() {
  await browser.init({browserName: 'chrome'});
  await browser.get('http://example.com');
  const title = await browser.title();
  console.log('Page title:', title);
  await browser.quit();
}

Architecture

WD is built around several key components:

  • WebDriver Core: Main browser automation engine implementing JsonWire Protocol
  • Element API: Rich element interaction and inspection capabilities
  • Actions System: Touch gestures, mouse actions, and W3C Actions support
  • Promise Wrappers: Multiple async patterns (callbacks, promises, promise chains)
  • Mobile Support: Full Appium integration for iOS and Android testing
  • Extension System: Custom method addition and configuration capabilities

Capabilities

Browser Sessions

Core session management for initializing, configuring, and terminating browser instances. Supports local Selenium servers and cloud services like Sauce Labs.

// Factory functions for different async patterns
function remote(configUrl?: string | object, driverType?: string): Webdriver;
function promiseRemote(configUrl?: string | object): PromiseWebdriver;
function promiseChainRemote(configUrl?: string | object): PromiseChainWebdriver;
function asyncRemote(configUrl?: string | object): Webdriver;

Browser Sessions

Navigation & Page Interaction

Navigation commands for browsing web pages, managing browser history, and retrieving page information.

// Core navigation methods
get(url: string, cb?: callback): void;
refresh(cb?: callback): void;
back(cb?: callback): void;
forward(cb?: callback): void;
url(cb?: callback): void;
title(cb?: callback): void;
source(cb?: callback): void;

Navigation

Element Location & Interaction

Comprehensive element finding, interaction, and inspection capabilities with multiple selector strategies.

// Element finding methods
element(using: string, value: string, cb?: callback): Element;
elements(using: string, value: string, cb?: callback): Element[];
elementById(id: string, cb?: callback): Element;
elementByClassName(className: string, cb?: callback): Element;
elementByCss(selector: string, cb?: callback): Element;
elementByXPath(xpath: string, cb?: callback): Element;

Element Location

User Input & Actions

Mouse interactions, keyboard input, touch gestures, and W3C Actions for complex user interactions.

// Input methods
keys(keys: string | string[], cb?: callback): void;
click(button?: number, cb?: callback): void;
doubleclick(cb?: callback): void;
moveTo(element?: Element, xOffset?: number, yOffset?: number, cb?: callback): void;

User Input

Waiting & Synchronization

Powerful waiting mechanisms with built-in asserters for handling dynamic content and asynchronous operations.

// Waiting methods
waitFor(asserter: Asserter, timeout?: number, pollFreq?: number, cb?: callback): void;
waitForElement(using: string, value: string, timeout?: number, cb?: callback): Element;
waitForVisible(using: string, value: string, timeout?: number, pollFreq?: number, cb?: callback): Element;

Waiting

JavaScript Execution

Execute JavaScript code in the browser context with safe evaluation and error handling.

// JavaScript execution methods
execute(code: string | function, args?: any[], cb?: callback): any;
safeExecute(code: string | function, args?: any[], cb?: callback): any;
executeAsync(code: string | function, args?: any[], cb?: callback): any;
eval(code: string, cb?: callback): any;

JavaScript Execution

Window & Frame Management

Multi-window and frame handling for complex web applications.

// Window management methods
windowHandles(cb?: callback): string[];
window(windowHandle: string, cb?: callback): void;
close(cb?: callback): void;
frame(frameRef: string | number | null, cb?: callback): void;

Window Management

Mobile Testing

Comprehensive mobile testing support through Appium integration with device-specific actions and capabilities.

// Mobile device actions
shakeDevice(cb?: callback): void;
lockDevice(seconds?: number, cb?: callback): void;
rotateDevice(x: number, y: number, z: number, cb?: callback): void;
getCurrentActivity(cb?: callback): string;

Mobile Testing

Touch Actions & Gestures

Advanced touch gesture support using TouchAction and MultiAction builders for mobile and touch-enabled devices.

// Touch action classes
class TouchAction {
  constructor(driver: Webdriver);
  tap(opts?: {element?: Element, x?: number, y?: number}): TouchAction;
  press(opts?: {element?: Element, x?: number, y?: number}): TouchAction;
  moveTo(opts?: {element?: Element, x?: number, y?: number}): TouchAction;
  release(): TouchAction;
  wait(ms: number): TouchAction;
  perform(cb?: callback): void;
}

Touch Actions

Configuration & Extension

HTTP configuration, timeout settings, and custom method addition for extending the library.

// Configuration methods
configureHttp(opts: {timeout?: number, retries?: number, retryDelay?: number}): void;
addAsyncMethod(name: string, method: function): void;
addPromiseMethod(name: string, method: function): void;

Configuration

Types & Interfaces

// Core classes
class Webdriver extends EventEmitter {
  constructor(configUrl: string | object);
  // Methods defined in capabilities above
}

class Element {
  constructor(value: string, browser: Webdriver);
  value: string;
  browser: Webdriver;
  // Element-specific methods
}

// Promise wrapper classes
class PromiseWebdriver extends Webdriver {
  // All methods return promises instead of using callbacks
}

class PromiseChainWebdriver extends Webdriver {
  // All methods return chainable promises
}

// Configuration types
interface DesiredCapabilities {
  browserName?: string;
  version?: string;
  platform?: string;
  javascriptEnabled?: boolean;
  acceptSslCerts?: boolean;
  [key: string]: any;
}

interface HttpConfig {
  timeout?: number;
  retries?: number;
  retryDelay?: number;
  baseUrl?: string;
  proxy?: string;
}

Utilities

// Utility objects and functions
const SPECIAL_KEYS: {
  NULL: string;
  Tab: string;
  Enter: string;
  Shift: string;
  Control: string;
  Alt: string;
  Escape: string;
  Space: string;
  // ... more special keys
};

const asserters: {
  nonEmptyText: Asserter;
  textInclude(content: string): Asserter;
  isDisplayed: Asserter;
  isNotDisplayed: Asserter;
  jsCondition(jsExpr: string, safe?: boolean): Asserter;
};

// Base asserter class
class Asserter {
  constructor(assertFunction: (target: any, callback: function) => void);
}