Server Management

/**
 * Initializes Appium's config. Starts server if appropriate and resolves the
 * server instance if so; otherwise resolves with undefined.
 * @param args - Arguments from CLI or otherwise
 * @returns Promise resolving to AppiumServer if server command, otherwise void
 */
function main<Cmd = ServerCommand>(args?: Args<Cmd>): Promise<Cmd extends ServerCommand ? AppiumServer : void>;

import { main } from "appium";

// Start server with default settings
const server = await main();

// Start server with custom configuration
const server = await main({
  port: 4725,
  address: "0.0.0.0",
  allowCors: true,
  logLevel: "debug"
});

// Run driver command instead of starting server
await main({
  subcommand: "driver",
  driver: {
    subcommand: "list"
  }
});

/**
 * Initializes Appium, but does not start the server.
 * Use this to get at the configuration schema.
 * @param args - Partial args (programmatic usage only)
 * @returns Promise resolving to initialization result
 */
function init<Cmd = ServerCommand>(args?: Args<Cmd>): Promise<InitResult<Cmd>>;

import { init, getSchema } from "appium";

// Initialize configuration
const result = await init({
  appiumHome: "/custom/appium/home"
});

// Access driver and plugin configurations
console.log(result.driverConfig.installedExtensions);
console.log(result.pluginConfig.installedExtensions);

// Get configuration schema
const schema = getSchema();

/**
 * Resolves Appium home directory path
 * @returns Promise resolving to absolute path of Appium home
 */
function resolveAppiumHome(): Promise<string>;

import { resolveAppiumHome } from "appium";

// Get current Appium home directory
const appiumHome = await resolveAppiumHome();
console.log(`Appium home: ${appiumHome}`);

interface AppiumServer {
  /** Check if server is running with HTTPS */
  isSecure(): boolean;
  /** Gracefully shut down the server */
  close(): Promise<void>;
  /** Add WebSocket handler for BiDi protocol support */
  addWebSocketHandler(path: string, handler: WebSocketServer): void;
}

interface InitResult<Cmd> {
  /** Main Appium driver instance (only for server commands) */
  appiumDriver?: AppiumDriver;
  /** Parsed configuration arguments */
  parsedArgs?: ParsedArgs;
  /** Driver configuration manager */
  driverConfig?: DriverConfig;
  /** Plugin configuration manager */
  pluginConfig?: PluginConfig;
  /** Resolved Appium home directory path */
  appiumHome?: string;
}

interface AppiumDriver {
  /** Active WebDriver sessions mapped by session ID */
  sessions: Record<string, ExternalDriver>;
  /** Pending driver instances for session creation */
  pendingDrivers: Record<string, ExternalDriver[]>;
  /** Active plugin classes mapped to their names */
  pluginClasses: Map<PluginClass, string>;
  /** Per-session plugin instances */
  sessionPlugins: Record<string, InstanceType<PluginClass>[]>;
  /** Global plugin instances for sessionless commands */
  sessionlessPlugins: InstanceType<PluginClass>[];
  /** Driver configuration manager */
  driverConfig: DriverConfig;
  /** HTTP server instance */
  server: AppiumServer;
  /** WebSocket connections for BiDi protocol */
  bidiSockets: Record<string, WebSocket[]>;
  /** BiDi proxy client connections */
  bidiProxyClients: Record<string, WebSocket>;
  /** Gracefully shutdown all sessions and server */
  shutdown(reason?: string): Promise<void>;
}

interface ServerCommand extends CliCommand {
  subcommand: "server";
}

interface Args<Cmd, SubCmd = void> {
  /** Server port number */
  port?: number;
  /** Server bind address */
  address?: string;
  /** Server base path */
  basePath?: string;
  /** Allow CORS requests */
  allowCors?: boolean;
  /** Logging level */
  logLevel?: string;
  /** Specific drivers to use */
  useDrivers?: string[];
  /** Specific plugins to use */
  usePlugins?: string[];
  /** CLI subcommand */
  subcommand?: string;
  /** Custom Appium home directory */
  appiumHome?: string;
  /** Throw errors instead of calling process.exit */
  throwInsteadOfExit?: boolean;
  [key: string]: any;
}

interface ParsedArgs extends Args<any> {
  /** Request timeout in seconds */
  requestTimeout?: number;
  /** Keep-alive timeout in seconds */
  keepAliveTimeout?: number;
  /** Default capabilities to merge with session requests */
  defaultCapabilities?: Record<string, any>;
  /** Configuration file path */
  configFile?: string;
  /** Temporary directory path */
  tmpDir?: string;
  /** Disable permissions check */
  noPermsCheck?: boolean;
  /** Show configuration and exit */
  showConfig?: boolean;
  /** Show build information and exit */
  showBuildInfo?: boolean;
  /** Show debug information and exit */
  showDebugInfo?: boolean;
  /** Enable long stack traces */
  longStacktrace?: boolean;
  /** Log filtering rules */
  logFilters?: any[];
  /** Selenium Grid node configuration */
  nodeconfig?: string;
}