or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-interactions.mdbidi-protocol.mdbrowser-automation.mdbrowser-options.mddriver-management.mdelement-location.mderror-handling.mdindex.mdwait-conditions.md
tile.json

tessl/npm-selenium-webdriver

The official WebDriver JavaScript bindings from the Selenium project for automated browser testing and web scraping

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/selenium-webdriver@4.35.x

To install, run

npx @tessl/cli install tessl/npm-selenium-webdriver@4.35.0

index.mddocs/

Selenium WebDriver

Selenium WebDriver provides the official JavaScript bindings for the Selenium project, enabling automated browser testing and web scraping. It offers a comprehensive API for controlling web browsers (Chrome, Firefox, Safari, Edge, IE) programmatically, including navigation, element interaction, form submission, and screenshot capture. The library supports modern JavaScript features with async/await syntax, provides built-in wait conditions and timeouts for reliable test execution, and includes driver management utilities for seamless browser automation setup.

Package Information

  • Package Name: selenium-webdriver
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install selenium-webdriver

Core Imports

const { Builder, By, Key, until } = require('selenium-webdriver');

ES modules:

import { Builder, By, Key, until } from 'selenium-webdriver';

Basic Usage

const { Builder, By, Key, until } = require('selenium-webdriver');

async function example() {
  // Create a new WebDriver instance
  let driver = await new Builder().forBrowser('chrome').build();
  
  try {
    // Navigate to a website
    await driver.get('https://www.example.com');
    
    // Find an element and interact with it
    let searchBox = await driver.findElement(By.name('q'));
    await searchBox.sendKeys('selenium webdriver', Key.RETURN);
    
    // Wait for results to load and take a screenshot
    await driver.wait(until.titleContains('selenium'), 5000);
    await driver.takeScreenshot();
    
  } finally {
    // Always quit the driver
    await driver.quit();
  }
}

Architecture

Selenium WebDriver is built around several key components:

  • Builder Pattern: Builder class provides a fluent interface for configuring and creating WebDriver instances
  • WebDriver Interface: WebDriver class is the main entry point for browser automation operations
  • Element Location: By class provides strategies for locating elements on web pages
  • Browser-Specific Drivers: Specialized driver classes for each browser (Chrome, Firefox, Safari, Edge, IE)
  • Wait Conditions: until module provides conditions for reliable waiting in dynamic web applications
  • BiDi Protocol: Modern bidirectional communication for advanced browser automation features
  • Action Chains: Complex user interactions through mouse and keyboard action sequences

Capabilities

Driver Management

Core WebDriver creation and configuration, including browser selection, capabilities, and service management.

class Builder {
  constructor();
  forBrowser(name: string, version?: string, platform?: string): Builder;
  withCapabilities(capabilities: Capabilities): Builder;
  usingServer(url: string): Builder;
  setChromeOptions(options: chrome.Options): Builder;
  setFirefoxOptions(options: firefox.Options): Builder;
  build(): ThenableWebDriver;
}

Driver Management

Element Location

Strategies for finding elements on web pages using various locator types (ID, CSS, XPath, etc.).

class By {
  static id(id: string): By;
  static css(selector: string): By;
  static xpath(xpath: string): By;
  static name(name: string): By;
  static className(name: string): By;
  static linkText(text: string): By;
  static partialLinkText(text: string): By;
  static tagName(name: string): By;
}

Element Location

Browser Automation

Core browser control operations including navigation, element interaction, and JavaScript execution.

class WebDriver {
  get(url: string): Promise<void>;
  getCurrentUrl(): Promise<string>;
  getTitle(): Promise<string>;
  findElement(locator: By): Promise<WebElement>;
  findElements(locator: By): Promise<WebElement[]>;
  executeScript(script: string | Function, ...args: any[]): Promise<any>;
  takeScreenshot(): Promise<string>;
  actions(options?: object): Actions;
  quit(): Promise<void>;
}

class WebElement {
  click(): Promise<void>;
  sendKeys(...keys: (string | number)[]): Promise<void>;
  getText(): Promise<string>;
  getAttribute(name: string): Promise<string>;
  isDisplayed(): Promise<boolean>;
  isEnabled(): Promise<boolean>;
  isSelected(): Promise<boolean>;
}

Browser Automation

Wait Conditions

Intelligent waiting mechanisms for handling dynamic web applications and timing-sensitive operations.

function titleIs(title: string): Condition<boolean>;
function titleContains(substr: string): Condition<boolean>;
function elementLocated(locator: By): Condition<WebElement>;
function elementIsVisible(elementOrLocator: WebElement | By): Condition<WebElement>;
function elementIsClickable(elementOrLocator: WebElement | By): Condition<WebElement>;
function elementTextContains(elementOrLocator: WebElement | By, text: string): Condition<boolean>;

Wait Conditions

Browser-Specific Options

Configuration options and capabilities specific to each supported browser.

// Chrome
class chrome.Options extends Capabilities {
  addArguments(...args: string[]): chrome.Options;
  addExtensions(...paths: string[]): chrome.Options;
  setChromeBinaryPath(path: string): chrome.Options;
  setMobileEmulation(config: object): chrome.Options;
}

// Firefox
class firefox.Options extends Capabilities {
  setBinary(binary: string): firefox.Options;
  setProfile(profile: firefox.Profile): firefox.Options;
  addArguments(...args: string[]): firefox.Options;
  setPreference(key: string, value: any): firefox.Options;
}

Browser-Specific Options

Advanced Interactions

Complex user interactions including action chains, file uploads, and form handling.

class Actions {
  constructor(driver: WebDriver);
  click(element?: WebElement): Actions;
  doubleClick(element?: WebElement): Actions;
  dragAndDrop(source: WebElement, target: WebElement): Actions;
  keyDown(key: string, element?: WebElement): Actions;
  keyUp(key: string, element?: WebElement): Actions;
  move(options: object): Actions;
  perform(): Promise<void>;
}

class Select {
  constructor(element: WebElement);
  selectByIndex(index: number): Promise<void>;
  selectByValue(value: string): Promise<void>;
  selectByVisibleText(text: string): Promise<void>;
  getOptions(): Promise<WebElement[]>;
}

Advanced Interactions

Error Handling

Comprehensive error hierarchy for robust error handling in WebDriver automation.

class WebDriverError extends Error {}
class NoSuchElementError extends WebDriverError {}
class ElementNotInteractableError extends WebDriverError {}
class TimeoutError extends WebDriverError {}
class StaleElementReferenceError extends WebDriverError {}
class InvalidSelectorError extends WebDriverError {}

Error Handling

BiDi Protocol

Modern bidirectional communication protocol for advanced browser automation and monitoring.

class BrowsingContext {
  create(type: string, options?: object): Promise<BrowsingContext>;
  navigate(url: string, wait?: string): Promise<NavigateResult>;
  captureScreenshot(options?: object): Promise<string>;
  locateElement(locator: Locator): Promise<WebElement>;
  printPage(options?: object): Promise<PrintResult>;
}

class LogInspector {
  constructor(driver: WebDriver);
  onLog(callback: (logEntry: object) => void): Promise<void>;
}

BiDi Protocol

Types

interface Capabilities {
  get(key: string): any;
  set(key: string, value: any): void;
  has(key: string): boolean;
  merge(other: Capabilities): Capabilities;
}

interface Condition<T> {
  description(): string;
}

interface ThenableWebDriver extends WebDriver {
  then<TResult1, TResult2>(
    onfulfilled?: ((value: WebDriver) => TResult1 | PromiseLike<TResult1>) | null,
    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
  ): Promise<TResult1 | TResult2>;
}

interface Session {
  getId(): string;
  getCapabilities(): Capabilities;
}

interface Rectangle {
  x: number;
  y: number;
  width: number;
  height: number;
}

interface WebElementCondition extends Condition<WebElement> {}

interface WebElementPromise extends Promise<WebElement>, WebElement {}

interface FileDetector {
  handleFile(driver: WebDriver, path: string): Promise<string>;
}

interface RelativeBy extends By {
  above(locator: By | WebElement): RelativeBy;
  below(locator: By | WebElement): RelativeBy;
  toLeftOf(locator: By | WebElement): RelativeBy;
  toRightOf(locator: By | WebElement): RelativeBy;
  near(locator: By | WebElement): RelativeBy;
}

interface Executor {
  execute(command: Command): Promise<any>;
}

interface ScriptManager {
  addPreloadScript(script: string): Promise<string>;
  removePreloadScript(script: string): Promise<void>;
}

interface NetworkManager {
  addIntercept(phases: string[], urlPatterns?: string[]): Promise<string>;
  removeIntercept(intercept: string): Promise<void>;
  continueRequest(request: string, body?: object): Promise<void>;
}

const Key = {
  RETURN: '\\uE006',
  ENTER: '\\uE007',
  TAB: '\\uE004',
  ESCAPE: '\\uE00C',
  SPACE: '\\uE00D',
  ARROW_UP: '\\uE013',
  ARROW_DOWN: '\\uE015',
  ARROW_LEFT: '\\uE012',
  ARROW_RIGHT: '\\uE014'
};

const Browser = {
  CHROME: 'chrome',
  FIREFOX: 'firefox',
  SAFARI: 'safari',  
  EDGE: 'MicrosoftEdge',
  INTERNET_EXPLORER: 'internet explorer'
};

const Button = {
  LEFT: 0,
  MIDDLE: 1, 
  RIGHT: 2
};

const Origin = {
  VIEWPORT: 'viewport',
  POINTER: 'pointer'
};

const Capability = {
  BROWSER_NAME: 'browserName',
  BROWSER_VERSION: 'browserVersion',
  PLATFORM_NAME: 'platformName',
  ACCEPT_INSECURE_CERTS: 'acceptInsecureCerts',
  PAGE_LOAD_STRATEGY: 'pageLoadStrategy',
  PROXY: 'proxy',
  SET_WINDOW_RECT: 'setWindowRect',
  TIMEOUTS: 'timeouts',
  UNHANDLED_PROMPT_BEHAVIOR: 'unhandledPromptBehavior'
};