Protocol Commands

/**
 * WebDriver session operations
 * @param options - Session configuration options
 * @returns Promise resolving with session data
 */
browser.session(options?: SessionOptions): Promise<SessionData>;

/**
 * Get active WebDriver sessions
 * @returns Promise resolving with array of session info
 */
browser.sessions(): Promise<SessionInfo[]>;

/**
 * Get WebDriver server status
 * @returns Promise resolving with server status
 */
browser.status(): Promise<ServerStatus>;

/**
 * Quit WebDriver session
 * @returns Promise resolving when session terminated
 */
browser.quit(): Promise<void>;

/**
 * Session configuration options
 */
interface SessionOptions {
  desiredCapabilities?: Capabilities;
  requiredCapabilities?: Capabilities;
}

/**
 * Session data interface
 */
interface SessionData {
  sessionId: string;
  capabilities: Capabilities;
}

/**
 * Session information interface
 */
interface SessionInfo {
  id: string;
  capabilities: Capabilities;
}

/**
 * Server status interface
 */
interface ServerStatus {
  ready: boolean;
  message: string;
  uptime?: number;
}

// Check server status
browser.status().then(status => {
  console.log('WebDriver server ready:', status.ready);
});

// Get active sessions
browser.sessions().then(sessions => {
  console.log('Active sessions:', sessions.length);
});

/**
 * Navigate to URL using WebDriver protocol
 * @param url - URL to navigate to
 * @returns Promise resolving when navigation completes
 */
browser.navigateTo(url: string): Promise<void>;

/**
 * Get current page URL
 * @returns Promise resolving with current URL
 */
browser.getCurrentUrl(): Promise<string>;

/**
 * Navigate back in browser history
 * @returns Promise resolving when navigation completes
 */
browser.back(): Promise<void>;

/**
 * Navigate forward in browser history
 * @returns Promise resolving when navigation completes
 */
browser.forward(): Promise<void>;

/**
 * Refresh current page
 * @returns Promise resolving when page reloads
 */
browser.refresh(): Promise<void>;

// Protocol-level navigation
browser
  .navigateTo('https://example.com')
  .getCurrentUrl()
  .then(url => console.log('Current URL:', url))
  .back()
  .forward()
  .refresh();

/**
 * Get current window handle
 * @returns Promise resolving with window handle
 */
browser.windowHandle(): Promise<string>;

/**
 * Get all window handles
 * @returns Promise resolving with array of window handles
 */
browser.windowHandles(): Promise<string[]>;

/**
 * Switch to window by handle
 * @param handle - Window handle to switch to
 * @returns Promise resolving when switch completes
 */
browser.switchToWindow(handle: string): Promise<void>;

/**
 * Close current window
 * @returns Promise resolving when window closed
 */
browser.closeWindow(): Promise<void>;

/**
 * Open new browser window
 * @param type - Window type ('tab' or 'window')
 * @returns Promise resolving with new window handle
 */
browser.openNewWindow(type?: 'tab' | 'window'): Promise<string>;

/**
 * Switch to frame by ID or index
 * @param id - Frame ID, index, or element
 * @returns Promise resolving when frame switched
 */
browser.frame(id: string | number | WebElement): Promise<void>;

/**
 * Switch to parent frame
 * @returns Promise resolving when switched to parent
 */
browser.frameParent(): Promise<void>;

/**
 * Get/set window position
 * @param x - X coordinate (optional)
 * @param y - Y coordinate (optional)
 * @returns Promise resolving with position or void
 */
browser.windowPosition(x?: number, y?: number): Promise<{x: number, y: number} | void>;

/**
 * Get/set window size
 * @param width - Window width (optional)
 * @param height - Window height (optional)
 * @returns Promise resolving with size or void
 */
browser.windowSize(width?: number, height?: number): Promise<{width: number, height: number} | void>;

/**
 * Get/set window rectangle
 * @param rect - Rectangle properties (optional)
 * @returns Promise resolving with rectangle or void
 */
browser.windowRect(rect?: WindowRect): Promise<WindowRect | void>;

/**
 * Maximize browser window
 * @returns Promise resolving when window maximized
 */
browser.windowMaximize(): Promise<void>;

/**
 * Minimize browser window
 * @returns Promise resolving when window minimized
 */
browser.minimizeWindow(): Promise<void>;

/**
 * Set window to fullscreen
 * @returns Promise resolving when fullscreen set
 */
browser.fullscreenWindow(): Promise<void>;

/**
 * Window rectangle interface
 */
interface WindowRect {
  x: number;
  y: number;
  width: number;
  height: number;
}

// Window management
browser
  .windowHandle()
  .then(handle => console.log('Current window:', handle))
  .openNewWindow('tab')
  .then(newHandle => {
    console.log('New window:', newHandle);
    return browser.switchToWindow(newHandle);
  })
  .windowMaximize()
  .windowRect({x: 100, y: 100, width: 1024, height: 768});

// Frame handling
browser
  .frame('content-frame')
  .findElement('#frame-content')
  .frameParent();

/**
 * Find element using WebDriver protocol
 * @param strategy - Locate strategy
 * @param selector - Element selector
 * @returns Promise resolving with element
 */
browser.element(strategy: LocateStrategy, selector: string): Promise<WebElement>;

/**
 * Find elements using WebDriver protocol
 * @param strategy - Locate strategy
 * @param selector - Elements selector
 * @returns Promise resolving with elements array
 */
browser.elements(strategy: LocateStrategy, selector: string): Promise<WebElement[]>;

/**
 * Get currently active element
 * @returns Promise resolving with active element
 */
browser.elementActive(): Promise<WebElement>;

/**
 * Click element by WebDriver ID
 * @param id - WebDriver element ID
 * @returns Promise resolving when click completes
 */
browser.elementIdClick(id: string): Promise<void>;

/**
 * Get element text by WebDriver ID
 * @param id - WebDriver element ID
 * @returns Promise resolving with element text
 */
browser.elementIdText(id: string): Promise<string>;

/**
 * Get/set element value by WebDriver ID
 * @param id - WebDriver element ID
 * @param value - Value to set (optional)
 * @returns Promise resolving with value or void
 */
browser.elementIdValue(id: string, value?: string): Promise<string | void>;

/**
 * Get element attribute by WebDriver ID
 * @param id - WebDriver element ID
 * @param name - Attribute name
 * @returns Promise resolving with attribute value
 */
browser.elementIdAttribute(id: string, name: string): Promise<string>;

/**
 * Get element property by WebDriver ID
 * @param id - WebDriver element ID
 * @param name - Property name
 * @returns Promise resolving with property value
 */
browser.elementIdProperty(id: string, name: string): Promise<any>;

/**
 * Get CSS property by WebDriver ID
 * @param id - WebDriver element ID
 * @param name - CSS property name
 * @returns Promise resolving with property value
 */
browser.elementIdCssProperty(id: string, name: string): Promise<string>;

/**
 * Check if element is selected by WebDriver ID
 * @param id - WebDriver element ID
 * @returns Promise resolving with selected boolean
 */
browser.elementIdSelected(id: string): Promise<boolean>;

/**
 * Check if element is enabled by WebDriver ID
 * @param id - WebDriver element ID
 * @returns Promise resolving with enabled boolean
 */
browser.elementIdEnabled(id: string): Promise<boolean>;

/**
 * Check if element is displayed by WebDriver ID
 * @param id - WebDriver element ID
 * @returns Promise resolving with displayed boolean
 */
browser.elementIdDisplayed(id: string): Promise<boolean>;

/**
 * Get element location by WebDriver ID
 * @param id - WebDriver element ID
 * @returns Promise resolving with location coordinates
 */
browser.elementIdLocation(id: string): Promise<{x: number, y: number}>;

/**
 * Get element viewport location by WebDriver ID
 * @param id - WebDriver element ID
 * @returns Promise resolving with viewport coordinates
 */
browser.elementIdLocationInView(id: string): Promise<{x: number, y: number}>;

/**
 * Get element size by WebDriver ID
 * @param id - WebDriver element ID
 * @returns Promise resolving with element dimensions
 */
browser.elementIdSize(id: string): Promise<{width: number, height: number}>;

/**
 * Clear element by WebDriver ID
 * @param id - WebDriver element ID
 * @returns Promise resolving when element cleared
 */
browser.elementIdClear(id: string): Promise<void>;

/**
 * Double-click element by WebDriver ID
 * @param id - WebDriver element ID
 * @returns Promise resolving when double-click completes
 */
browser.elementIdDoubleClick(id: string): Promise<void>;

/**
 * Compare elements by WebDriver ID
 * @param id1 - First element ID
 * @param id2 - Second element ID
 * @returns Promise resolving with equality boolean
 */
browser.elementIdEquals(id1: string, id2: string): Promise<boolean>;

/**
 * Get element tag name by WebDriver ID
 * @param id - WebDriver element ID
 * @returns Promise resolving with tag name
 */
browser.elementIdName(id: string): Promise<string>;

// Protocol-level element operations
browser
  .element('css selector', '#submit-button')
  .then(element => {
    console.log('Element ID:', element.ELEMENT);
    return browser.elementIdClick(element.ELEMENT);
  });

// Get element properties using protocol
browser
  .elements('css selector', '.menu-item')
  .then(elements => {
    elements.forEach((el, index) => {
      browser.elementIdText(el.ELEMENT).then(text => {
        console.log(`Menu item ${index}:`, text);
      });
    });
  });

/**
 * Move mouse to coordinates or element
 * @param element - Element to move to (optional)
 * @param xOffset - X offset from element center
 * @param yOffset - Y offset from element center
 * @returns Promise resolving when mouse moved
 */
browser.moveTo(element?: WebElement, xOffset?: number, yOffset?: number): Promise<void>;

/**
 * Click mouse button
 * @param button - Mouse button (0=left, 1=middle, 2=right)
 * @returns Promise resolving when click completes
 */
browser.mouseButtonClick(button: 0 | 1 | 2): Promise<void>;

/**
 * Press mouse button down
 * @param button - Mouse button (0=left, 1=middle, 2=right)
 * @returns Promise resolving when button pressed
 */
browser.mouseButtonDown(button: 0 | 1 | 2): Promise<void>;

/**
 * Release mouse button
 * @param button - Mouse button (0=left, 1=middle, 2=right)
 * @returns Promise resolving when button released
 */
browser.mouseButtonUp(button: 0 | 1 | 2): Promise<void>;

/**
 * Release all mouse buttons
 * @returns Promise resolving when buttons released
 */
browser.releaseMouseButton(): Promise<void>;

/**
 * Send keys to active element
 * @param keys - Keys to send (string or array)
 * @returns Promise resolving when keys sent
 */
browser.keys(keys: string | string[]): Promise<void>;

// Protocol-level mouse operations
browser
  .element('css selector', '#draggable')
  .then(element => {
    return browser
      .moveTo(element)
      .mouseButtonDown(0) // Left button down
      .moveTo(null, 100, 50) // Move 100px right, 50px down
      .mouseButtonUp(0); // Release left button
  });

// Protocol-level keyboard operations
browser
  .elementActive()
  .then(() => {
    return browser.keys(['Hello', ' ', 'World', '\uE007']); // Enter key
  });

/**
 * Accept JavaScript alert dialog
 * @returns Promise resolving when alert accepted
 */
browser.acceptAlert(): Promise<void>;

/**
 * Dismiss JavaScript alert dialog
 * @returns Promise resolving when alert dismissed
 */
browser.dismissAlert(): Promise<void>;

/**
 * Get JavaScript alert dialog text
 * @returns Promise resolving with alert text
 */
browser.getAlertText(): Promise<string>;

/**
 * Set JavaScript alert dialog text (for prompt dialogs)
 * @param text - Text to set in alert
 * @returns Promise resolving when text set
 */
browser.setAlertText(text: string): Promise<void>;

// Handle alert dialogs
browser
  .click('#show-alert-button')
  .getAlertText()
  .then(alertText => {
    console.log('Alert message:', alertText);
    return browser.acceptAlert();
  });

// Handle prompt dialogs
browser
  .click('#show-prompt-button')
  .setAlertText('User input')
  .acceptAlert();

/**
 * Cookie protocol operations
 * @param method - HTTP method for cookie operation
 * @param cookie - Cookie data (for set operations)
 * @returns Promise resolving with cookie data or void
 */
browser.cookie(method: 'GET'): Promise<Cookie[]>;
browser.cookie(method: 'POST', cookie: Cookie): Promise<void>;
browser.cookie(method: 'DELETE'): Promise<void>;
browser.cookie(method: 'DELETE', cookie: {name: string}): Promise<void>;

// Protocol-level cookie operations
browser
  .cookie('POST', {
    name: 'session_id',
    value: 'abc123',
    domain: 'example.com'
  })
  .cookie('GET')
  .then(cookies => {
    console.log('All cookies:', cookies);
  })
  .cookie('DELETE', {name: 'session_id'});

/**
 * Set WebDriver timeouts
 * @param type - Timeout type
 * @param ms - Timeout in milliseconds
 * @returns Promise resolving when timeout set
 */
browser.timeouts(type: TimeoutType, ms: number): Promise<void>;
browser.timeouts(timeouts: TimeoutConfig): Promise<void>;

/**
 * Set async script timeout
 * @param ms - Timeout in milliseconds
 * @returns Promise resolving when timeout set
 */
browser.timeoutsAsyncScript(ms: number): Promise<void>;

/**
 * Set implicit wait timeout
 * @param ms - Timeout in milliseconds
 * @returns Promise resolving when timeout set
 */
browser.timeoutsImplicitWait(ms: number): Promise<void>;

/**
 * Timeout type options
 */
type TimeoutType = 'script' | 'implicit' | 'pageLoad';

/**
 * Timeout configuration interface
 */
interface TimeoutConfig {
  script?: number;
  implicit?: number;
  pageLoad?: number;
}

// Configure timeouts
browser
  .timeouts('implicit', 10000) // 10 second implicit wait
  .timeoutsAsyncScript(30000)  // 30 second script timeout
  .timeouts({
    script: 30000,
    implicit: 10000,
    pageLoad: 60000
  });

/**
 * Take page screenshot
 * @returns Promise resolving with base64 screenshot data
 */
browser.screenshot(): Promise<string>;

/**
 * Get page HTML source
 * @returns Promise resolving with HTML source
 */
browser.source(): Promise<string>;

/**
 * Get page title
 * @returns Promise resolving with page title
 */
browser.title(): Promise<string>;

/**
 * Get/set current URL
 * @param url - URL to navigate to (optional)
 * @returns Promise resolving with URL or void
 */
browser.url(url?: string): Promise<string | void>;

// Protocol content operations
browser
  .url('https://example.com')
  .title()
  .then(title => console.log('Page title:', title))
  .source()
  .then(html => console.log('HTML length:', html.length))
  .screenshot()
  .then(base64Data => {
    // Save screenshot data
    require('fs').writeFileSync('screenshot.png', base64Data, 'base64');
  });

/**
 * Get available mobile contexts
 * @returns Promise resolving with context names
 */
browser.contexts(): Promise<string[]>;

/**
 * Get current mobile context
 * @returns Promise resolving with current context
 */
browser.currentContext(): Promise<string>;

/**
 * Set mobile context
 * @param context - Context name ('NATIVE_APP', 'WEBVIEW_1', etc.)
 * @returns Promise resolving when context set
 */
browser.setContext(context: string): Promise<void>;

/**
 * Get device orientation
 * @returns Promise resolving with orientation
 */
browser.getOrientation(): Promise<'PORTRAIT' | 'LANDSCAPE'>;

/**
 * Set device orientation
 * @param orientation - Device orientation
 * @returns Promise resolving when orientation set
 */
browser.setOrientation(orientation: 'PORTRAIT' | 'LANDSCAPE'): Promise<void>;

/**
 * Get GPS coordinates
 * @returns Promise resolving with location
 */
browser.getGeolocation(): Promise<{latitude: number, longitude: number}>;

/**
 * Set GPS coordinates
 * @param location - GPS coordinates
 * @returns Promise resolving when location set
 */
browser.setGeolocation(location: {latitude: number, longitude: number}): Promise<void>;

// Mobile protocol operations
if (browser.isMobile()) {
  browser
    .contexts()
    .then(contexts => {
      console.log('Available contexts:', contexts);
      if (contexts.includes('WEBVIEW_1')) {
        return browser.setContext('WEBVIEW_1');
      }
    })
    .setOrientation('LANDSCAPE')
    .setGeolocation({latitude: 37.7749, longitude: -122.4194});
}