or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

advanced-interactions.md bidi-protocol.md browser-automation.md browser-options.md driver-management.md element-location.md error-handling.md index.md wait-conditions.md

tile.json

Driver Management

Comprehensive WebDriver creation and configuration system supporting all major browsers with flexible options for local and remote execution.

Capabilities

Builder Class

The Builder class provides a fluent interface for configuring and creating WebDriver instances with browser-specific options.

/**
 * Creates new WebDriver instances with flexible configuration
 */
class Builder {
  constructor();
  
  /** Configure target browser */
  forBrowser(name: string, version?: string, platform?: string): Builder;
  
  /** Set desired capabilities */
  withCapabilities(capabilities: Capabilities | object): Builder;
  
  /** Set individual capability */
  setCapability(key: string, value: any): Builder;
  
  /** Configure remote WebDriver server URL */
  usingServer(url: string): Builder;
  
  /** Set proxy configuration for WebDriver connections */
  usingWebDriverProxy(proxy: string): Builder;
  
  /** Set HTTP agent for requests */
  usingHttpAgent(agent: object): Builder;
  
  /** Set proxy configuration */
  setProxy(config: object): Builder;
  
  /** Set logging preferences */
  setLoggingPrefs(prefs: object): Builder;
  
  /** Set alert handling behavior */
  setAlertBehavior(behavior: string): Builder;
  
  /** Ignore environment variable overrides */
  disableEnvironmentOverrides(): Builder;
  
  /** Create configured WebDriver instance */
  build(): ThenableWebDriver;
}

Usage Examples:

const { Builder, Capabilities } = require('selenium-webdriver');

// Basic browser selection
let driver = await new Builder()
  .forBrowser('chrome')
  .build();

// With version and platform
let driver = await new Builder()
  .forBrowser('firefox', '100.0', 'LINUX')
  .build();

// Using capabilities
let caps = new Capabilities();
caps.setBrowserName('chrome');
caps.setBrowserVersion('latest');

let driver = await new Builder()
  .withCapabilities(caps)
  .build();

// Remote WebDriver
let driver = await new Builder()
  .forBrowser('chrome')
  .usingServer('http://selenium-hub:4444/wd/hub')
  .build();

Capabilities Class

Configuration object for specifying browser capabilities and options.

/**
 * Browser capabilities configuration
 */
class Capabilities {
  constructor(other?: Capabilities | object);
  
  /** Get capability value */
  get(key: string): any;
  
  /** Set capability value */
  set(key: string, value: any): void;
  
  /** Check if capability exists */
  has(key: string): boolean;
  
  /** Delete capability */
  delete(key: string): boolean;
  
  /** Merge with other capabilities */
  merge(other: Capabilities): Capabilities;
  
  /** Set browser name */
  setBrowserName(name: string): void;
  
  /** Get browser name */
  getBrowserName(): string;
  
  /** Set browser version */
  setBrowserVersion(version: string): void;
  
  /** Get browser version */
  getBrowserVersion(): string;
  
  /** Set platform */
  setPlatform(platform: string): void;
  
  /** Get platform */
  getPlatform(): string;
  
  /** Set proxy configuration */
  setProxy(proxy: object): void;
  
  /** Get proxy configuration */
  getProxy(): object;
  
  /** Set logging preferences */
  setLoggingPrefs(prefs: object): void;
  
  /** Get logging preferences */
  getLoggingPrefs(): object;
  
  /** Set alert behavior */
  setAlertBehavior(behavior: string): void;
}

Usage Examples:

const { Capabilities, Browser, Platform } = require('selenium-webdriver');

// Create capabilities
let caps = new Capabilities();
caps.setBrowserName(Browser.CHROME);
caps.setBrowserVersion('latest');
caps.setPlatform(Platform.WINDOWS);

// Merge capabilities
let chromeOptions = new Capabilities();
chromeOptions.set('chromeOptions', {
  args: ['--headless', '--no-sandbox']
});

caps.merge(chromeOptions);

// Custom capabilities
caps.set('acceptInsecureCerts', true);
caps.set('timeouts', {
  implicit: 30000,
  pageLoad: 60000,
  script: 30000
});

Browser Constants

Standard browser name constants for consistent browser identification.

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

Platform Constants

Platform identification constants for cross-platform testing.

const Platform = {
  WINDOWS: 'WINDOWS',
  MAC: 'MAC',
  LINUX: 'LINUX',
  UNIX: 'UNIX',
  ANDROID: 'ANDROID',
  ANY: 'ANY'
};

Capability Keys

Standard capability key constants for WebDriver configuration.

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

Environment Variables

WebDriver supports configuration through environment variables for flexible deployment.

SELENIUM_BROWSER: Define target browser as browser[:version][:platform]
SELENIUM_REMOTE_URL: Remote WebDriver server URL
SELENIUM_SERVER_JAR: Path to standalone Selenium server JAR

Usage Examples:

# Use Firefox with specific version
export SELENIUM_BROWSER=firefox:100.0:LINUX

# Use remote WebDriver server
export SELENIUM_REMOTE_URL=http://selenium-hub:4444/wd/hub

# Use local Selenium server
export SELENIUM_SERVER_JAR=/path/to/selenium-server-standalone.jar

ThenableWebDriver

Special WebDriver implementation that allows direct command chaining without explicit promise handling.

/**
 * Thenable WebDriver allows direct command execution
 */
interface ThenableWebDriver extends WebDriver {
  /** Promise then method for awaiting driver creation */
  then<TResult1, TResult2>(
    onfulfilled?: ((value: WebDriver) => TResult1 | PromiseLike<TResult1>) | null,
    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
  ): Promise<TResult1 | TResult2>;
  
  /** Promise catch method */
  catch<TResult>(
    onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null
  ): Promise<WebDriver | TResult>;
}

Usage Examples:

// Traditional promise handling
let driver = await new Builder().forBrowser('chrome').build();
await driver.get('https://example.com');

// Direct command chaining (thenable)
let driver = new Builder().forBrowser('chrome').build();
driver.get('https://example.com');  // No await needed
driver.findElement(By.id('search')); // Commands can be chained

Service Management

WebDriver services manage browser driver processes (chromedriver, geckodriver, etc.).

/**
 * Base service builder for browser drivers
 */
class ServiceBuilder {
  constructor(executable?: string);
  
  /** Set driver executable path */
  setExecutable(executable: string): ServiceBuilder;
  
  /** Set service port */
  setPort(port: number): ServiceBuilder;
  
  /** Add command line arguments */
  addArguments(...args: string[]): ServiceBuilder;
  
  /** Set environment variables */
  setEnvironment(env: object): ServiceBuilder;
  
  /** Enable verbose logging */
  enableVerboseLogging(): ServiceBuilder;
  
  /** Set log file path */
  setLogFile(path: string): ServiceBuilder;
  
  /** Build service instance */
  build(): object;
}

Usage Examples:

const { Builder } = require('selenium-webdriver');
const chrome = require('selenium-webdriver/chrome');

// Configure Chrome service
let service = new chrome.ServiceBuilder()
  .setPort(9515)
  .enableVerboseLogging()
  .setLogFile('/tmp/chromedriver.log')
  .build();

let driver = await new Builder()
  .forBrowser('chrome')
  .setChromeService(service)
  .build();

Version

Tile

Files