Browser Capabilities

/**
 * W3C WebDriver capabilities structure
 */
interface W3CCapabilities {
  /** Required capabilities that must be satisfied */
  alwaysMatch?: WebdriverIO.Capabilities;
  /** Array of alternative capability sets, at least one must be satisfied */
  firstMatch?: WebdriverIO.Capabilities[];
}

/**
 * Core WebDriver capabilities
 */
interface Capabilities {
  /** Browser name (chrome, firefox, safari, MicrosoftEdge, etc.) */
  browserName?: string;
  /** Browser version */
  browserVersion?: string;
  /** Operating system platform */
  platformName?: string;
  /** Accept insecure/self-signed certificates */
  acceptInsecureCerts?: boolean;
  /** Page load strategy: none, eager, or normal */
  pageLoadStrategy?: PageLoadingStrategy;
  /** Proxy configuration */
  proxy?: ProxyObject;
  /** Window resizing/repositioning support */
  setWindowRect?: boolean;
  /** Session timeout configuration */
  timeouts?: Timeouts;
  /** Strict file upload interactability */
  strictFileInteractability?: boolean;
  /** Unhandled prompt behavior */
  unhandledPromptBehavior?: string;
  /** WebSocket URL for bidirectional communication */
  webSocketUrl?: boolean;
}

interface ChromeOptions {
  /** Chrome binary path */
  binary?: string;
  /** Command-line arguments */
  args?: string[];
  /** Chrome extensions as base64 strings */
  extensions?: string[];
  /** Local state preferences */
  localState?: Record<string, any>;
  /** User preferences */
  prefs?: Record<string, any>;
  /** Detach browser from driver */
  detach?: boolean;
  /** Debug port */
  debuggerAddress?: string;
  /** Exclude switches */
  excludeSwitches?: string[];
  /** Minidump path */
  minidumpPath?: string;
  /** Mobile emulation */
  mobileEmulation?: {
    deviceName?: string;
    deviceMetrics?: {
      width: number;
      height: number;
      pixelRatio: number;
    };
    userAgent?: string;
  };
  /** Performance logging */
  perfLoggingPrefs?: {
    enableNetwork?: boolean;
    enablePage?: boolean;
    enableTimeline?: boolean;
    tracingCategories?: string;
    bufferUsageReportingInterval?: number;
  };
  /** Window types */
  windowTypes?: string[];
}

interface FirefoxOptions {
  /** Firefox binary path */
  binary?: string;
  /** Command-line arguments */
  args?: string[];
  /** Firefox profile object or path */
  profile?: string | FirefoxProfile;
  /** Logging configuration */
  log?: FirefoxLogObject;
  /** User preferences */
  prefs?: Record<string, any>;
  /** Environment variables */
  env?: Record<string, string>;
}

interface FirefoxLogObject {
  level?: 'trace' | 'debug' | 'config' | 'info' | 'warn' | 'error' | 'fatal';
}

interface AppiumAndroidCapabilities {
  /** Android package name */
  'appium:appPackage'?: string;
  /** Android activity name */
  'appium:appActivity'?: string;
  /** Wait for activity */
  'appium:appWaitActivity'?: string;
  /** Device name */
  'appium:deviceName'?: string;
  /** Platform version */
  'appium:platformVersion'?: string;
  /** Automation name */
  'appium:automationName'?: 'UiAutomator2' | 'Espresso';
  /** App path or URL */
  'appium:app'?: string;
  /** No reset */
  'appium:noReset'?: boolean;
  /** Full reset */
  'appium:fullReset'?: boolean;
  /** Auto-grant permissions */
  'appium:autoGrantPermissions'?: boolean;
  /** System port */
  'appium:systemPort'?: number;
  /** Chrome driver executable path */
  'appium:chromedriverExecutable'?: string;
}

interface AppiumXCUITestCapabilities {
  /** iOS bundle identifier */
  'appium:bundleId'?: string;
  /** Device name */
  'appium:deviceName'?: string;
  /** Platform version */
  'appium:platformVersion'?: string;
  /** Automation name */
  'appium:automationName'?: 'XCUITest';
  /** App path or URL */
  'appium:app'?: string;
  /** UDID for real devices */
  'appium:udid'?: string;
  /** Xcode organization team identifier */
  'appium:xcodeOrgId'?: string;
  /** Xcode signing certificate */
  'appium:xcodeSigningId'?: string;
  /** Auto-accept alerts */
  'appium:autoAcceptAlerts'?: boolean;
  /** Auto-dismiss alerts */
  'appium:autoDismissAlerts'?: boolean;
  /** WDA local port */
  'appium:wdaLocalPort'?: number;
  /** Simulator startup timeout */
  'appium:launchTimeout'?: number;
}

interface SauceLabsCapabilities {
  /** Sauce Labs username */
  'sauce:options'?: {
    username?: string;
    accessKey?: string;
    /** Build identifier */
    build?: string;
    /** Test name */
    name?: string;
    /** Tags for organizing tests */
    tags?: string[];
    /** Custom data */
    customData?: Record<string, any>;
    /** Selenium version */
    seleniumVersion?: string;
    /** Screen resolution */
    screenResolution?: string;
    /** Timezone */
    timeZone?: string;
    /** Idle timeout */
    idleTimeout?: number;
    /** Command timeout */
    commandTimeout?: number;
    /** Max duration */
    maxDuration?: number;
  };
}

interface BrowserStackCapabilities {
  /** BrowserStack options */
  'bstack:options'?: {
    /** Username */
    userName?: string;
    /** Access key */
    accessKey?: string;
    /** Project name */
    projectName?: string;
    /** Build name */
    buildName?: string;
    /** Session name */
    sessionName?: string;
    /** Debug mode */
    debug?: boolean;
    /** Network logs */
    networkLogs?: boolean;
    /** Console logs */
    consoleLogs?: 'errors' | 'warnings' | 'info' | 'verbose';
    /** Selenium version */
    seleniumVersion?: string;
    /** Mobile test */
    realMobile?: boolean;
  };
}

/**
 * Proxy configuration types
 */
type ProxyTypes = 'pac' | 'noproxy' | 'autodetect' | 'system' | 'manual';

interface ProxyObject {
  /** Proxy type */
  proxyType?: ProxyTypes;
  /** PAC file URL */
  proxyAutoconfigUrl?: string;
  /** FTP proxy settings */
  ftpProxy?: string;
  ftpProxyPort?: number;
  /** HTTP proxy settings */
  httpProxy?: string;
  httpProxyPort?: number;
  /** SSL proxy settings */
  sslProxy?: string;
  sslProxyPort?: number;
  /** SOCKS proxy settings */
  socksProxy?: string;
  socksProxyPort?: number;
  socksVersion?: string;
  socksUsername?: string;
  socksPassword?: string;
  /** Proxy bypass list */
  noProxy?: string[];
}

/**
 * WebDriver timeouts
 */
type Timeouts = Record<'script' | 'pageLoad' | 'implicit', number>;

/**
 * Logging preference levels
 */
type LoggingPreferenceType = 'OFF' | 'SEVERE' | 'WARNING' | 'INFO' | 'CONFIG' | 'FINE' | 'FINER' | 'FINEST' | 'ALL';

interface LoggingPreferences {
  /** Browser logging level */
  browser?: LoggingPreferenceType;
  /** Driver logging level */
  driver?: LoggingPreferenceType;
  /** Server logging level */
  server?: LoggingPreferenceType;
  /** Client logging level */
  client?: LoggingPreferenceType;
}

/**
 * Page loading strategies
 */
type PageLoadingStrategy = 'none' | 'eager' | 'normal';

/**
 * Standalone capability types
 */
type RequestedStandaloneCapabilities = W3CCapabilities | WebdriverIO.Capabilities;

/**
 * Multi-remote capability configuration
 */
type RequestedMultiremoteCapabilities = Record<string, RequestedStandaloneCapabilities>;

/**
 * Test runner capability types
 */
type TestrunnerCapabilities = 
  | RequestedStandaloneCapabilities
  | RequestedStandaloneCapabilities[]
  | RequestedMultiremoteCapabilities;

/**
 * Resolved capability types for worker instances
 */
type ResolvedTestrunnerCapabilities = 
  | WebdriverIO.Capabilities
  | WebdriverIO.Capabilities[]
  | Record<string, WebdriverIO.Capabilities>;