Browser Sessions

/**
 * Create a WebDriver instance with configurable async pattern
 * @param configUrl - Server URL, config object, or connection parameters
 * @param driverType - 'async', 'promise', or 'promiseChain'
 */
function remote(configUrl?: string | object, driverType?: string): Webdriver;

/**
 * Create a promise-based WebDriver instance (no chaining)
 * @param configUrl - Server configuration
 */
function promiseRemote(configUrl?: string | object): PromiseWebdriver;

/**
 * Create a promise chain WebDriver instance
 * @param configUrl - Server configuration
 */
function promiseChainRemote(configUrl?: string | object): PromiseChainWebdriver;

/**
 * Create an async callback-based WebDriver instance
 * @param configUrl - Server configuration
 */
function asyncRemote(configUrl?: string | object): Webdriver;

const wd = require('wd');

// Connect to local Selenium server (default: http://127.0.0.1:4444/wd/hub)
const browser = wd.remote();

// Connect with explicit configuration
const browser = wd.remote({
  hostname: 'selenium.example.com',
  port: 4444,
  user: 'username',
  pwd: 'access-key'
});

// Connect to Sauce Labs
const browser = wd.remote('https://username:access-key@ondemand.saucelabs.com/wd/hub');

// Force promise chain pattern
const browser = wd.remote('promiseChain');

/**
 * Initialize a new browser session with desired capabilities
 * @param desired - Browser capabilities object
 * @param cb - Callback receiving (err, sessionId, capabilities)
 */
init(desired: DesiredCapabilities, cb?: callback): void;

/**
 * Attach to an existing session by ID
 * @param sessionId - Existing session identifier
 * @param cb - Callback receiving (err)
 */
attach(sessionId: string, cb?: callback): void;

/**
 * Detach from current session without closing browser
 * @param cb - Callback receiving (err)
 */
detach(cb?: callback): void;

/**
 * Close browser and terminate session
 * @param cb - Callback receiving (err)
 */
quit(cb?: callback): void;

/**
 * Get current session ID
 * @param cb - Callback receiving (err, sessionId)
 */
getSessionId(cb?: callback): string;

interface DesiredCapabilities {
  browserName?: string;          // 'chrome', 'firefox', 'safari', 'internet explorer'
  version?: string;              // Browser version
  platform?: string;             // 'WINDOWS', 'MAC', 'LINUX', 'ANY'
  javascriptEnabled?: boolean;    // Enable JavaScript (default: true)
  acceptSslCerts?: boolean;      // Accept SSL certificates
  pageLoadStrategy?: string;     // 'normal', 'eager', 'none'
  proxy?: ProxyConfig;           // Proxy configuration
  [key: string]: any;           // Additional platform-specific capabilities
}

interface ProxyConfig {
  proxyType: string;            // 'direct', 'manual', 'pac', 'autodetect', 'system'
  httpProxy?: string;           // HTTP proxy server
  sslProxy?: string;            // SSL proxy server
  noProxy?: string[];           // Hosts to bypass proxy
}

// Initialize Chrome browser
browser.init({
  browserName: 'chrome',
  chromeOptions: {
    args: ['--headless', '--no-sandbox']
  }
}, function(err, sessionId, capabilities) {
  if (err) throw err;
  console.log('Session started:', sessionId);
  // Browser is ready for automation
});

// Initialize with mobile emulation
browser.init({
  browserName: 'chrome',
  chromeOptions: {
    mobileEmulation: {
      deviceName: 'iPhone X'
    }
  }
});

// Initialize Firefox with profile
browser.init({
  browserName: 'firefox',
  'moz:firefoxOptions': {
    args: ['-headless'],
    prefs: {
      'dom.webnotifications.enabled': false
    }
  }
});

/**
 * Get server status information
 * @param cb - Callback receiving (err, status)
 */
status(cb?: callback): object;

/**
 * Get all active sessions on the server
 * @param cb - Callback receiving (err, sessions)
 */
sessions(cb?: callback): object[];

/**
 * Get current session capabilities
 * @param cb - Callback receiving (err, capabilities)
 */
sessionCapabilities(cb?: callback): object;

/**
 * Get alternative session capabilities format
 * @param cb - Callback receiving (err, capabilities)
 */
altSessionCapabilities(cb?: callback): object;

// Check server status
browser.status(function(err, status) {
  console.log('WebDriver server status:', status);
  console.log('Ready:', status.ready);
  console.log('Message:', status.message);
});

// Get session capabilities
browser.sessionCapabilities(function(err, caps) {
  console.log('Browser name:', caps.browserName);
  console.log('Browser version:', caps.version);
  console.log('Platform:', caps.platform);
});

/**
 * Update Sauce Labs job information
 * @param jsonData - Job metadata to update
 * @param cb - Callback receiving (err)
 */
sauceJobUpdate(jsonData: object, cb?: callback): void;

/**
 * Set Sauce Labs job pass/fail status
 * @param hasPassed - Whether the test passed
 * @param cb - Callback receiving (err)
 */
sauceJobStatus(hasPassed: boolean, cb?: callback): void;

// Update Sauce Labs job with custom data
browser.sauceJobUpdate({
  name: 'My Test Suite',
  tags: ['smoke', 'login'],
  'custom-data': {
    release: '1.2.3',
    commit: 'abc123'
  }
});

// Mark test as passed/failed
browser.sauceJobStatus(true); // Test passed

// Common error patterns
browser.init(desiredCaps, function(err, sessionId) {
  if (err) {
    if (err.code === 'ECONNREFUSED') {
      console.error('Cannot connect to WebDriver server');
    } else if (err.seleniumError && err.seleniumError.type === 'SessionNotCreatedException') {
      console.error('Failed to create session:', err.message);
    } else {
      console.error('Initialization error:', err);
    }
    return;
  }
  
  // Session created successfully
  console.log('Session ID:', sessionId);
});