Browser Management

/**
 * Launch a new browser instance
 * @param options - Configuration options for browser launch
 * @returns Promise resolving to Browser instance
 */
function launch(options?: LaunchOptions): Promise<Browser>;

interface LaunchOptions {
  /** Run browser in headless mode. Can be true, false, "new" (new headless), or "shell" */
  headless?: boolean | "new" | "shell";
  /** Path to browser executable. If not specified, uses bundled Chromium */
  executablePath?: string;
  /** Additional command line arguments to pass to browser */
  args?: string[];
  /** Whether to ignore default arguments or specify which ones to ignore */
  ignoreDefaultArgs?: boolean | string[];
  /** Whether to handle SIGINT signal */
  handleSIGINT?: boolean;
  /** Whether to handle SIGTERM signal */
  handleSIGTERM?: boolean;
  /** Whether to handle SIGHUP signal */
  handleSIGHUP?: boolean;
  /** Maximum time to wait for browser to start (milliseconds) */
  timeout?: number;
  /** Whether to pipe browser stdout/stderr to process stdout/stderr */
  dumpio?: boolean;
  /** Environment variables to set for browser process */
  env?: Record<string, string | undefined>;
  /** Whether to auto-open DevTools panel for each tab */
  devtools?: boolean;
  /** Delay between actions in milliseconds */
  slowMo?: number;
  /** Default viewport for each page. Set to null to disable default viewport */
  defaultViewport?: Viewport | null;
  /** Whether to ignore HTTPS errors */
  ignoreHTTPSErrors?: boolean;
  /** Browser to launch ("chrome" or "firefox") */
  browser?: "chrome" | "firefox";
  /** Release channel to use (Chrome only) */
  channel?: "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev";
  /** Whether to wait for initial page to be created */
  waitForInitialPage?: boolean;
  /** Port to use for debugging. If 0, a random port is chosen */
  debuggingPort?: number;
}

import puppeteer from "puppeteer";

// Basic launch
const browser = await puppeteer.launch();

// Launch with options
const browser = await puppeteer.launch({
  headless: false,    // Run with GUI
  slowMo: 250,       // Slow down actions
  devtools: true,    // Open DevTools
  args: ["--no-sandbox", "--disable-setuid-sandbox"]
});

// Launch Firefox
const browser = await puppeteer.launch({
  browser: "firefox",
  headless: true
});

/**
 * Connect to an existing browser instance
 * @param options - Connection options
 * @returns Promise resolving to Browser instance
 */
function connect(options: ConnectOptions): Promise<Browser>;

interface ConnectOptions {
  /** WebSocket endpoint URL to connect to */
  browserWSEndpoint?: string;
  /** Browser HTTP endpoint URL */
  browserURL?: string;
  /** Whether to ignore HTTPS errors */
  ignoreHTTPSErrors?: boolean;
  /** Default viewport for new pages */
  defaultViewport?: Viewport | null;
  /** Delay between actions in milliseconds */
  slowMo?: number;
  /** Function to filter which targets to track */
  targetFilter?: (target: Target) => boolean;
  /** Transport mechanism to use */
  transport?: ConnectionTransport;
  /** Protocol to use for communication */
  protocol?: "cdp" | "webDriverBiDi";
}

// Connect via WebSocket endpoint
const browser = await puppeteer.connect({
  browserWSEndpoint: "ws://localhost:9222/devtools/browser"
});

// Connect via browser URL
const browser = await puppeteer.connect({
  browserURL: "http://localhost:9222"
});

/**
 * Browser instance managing contexts, pages, and targets
 */
class Browser {
  /** Get browser version information */
  version(): Promise<string>;
  
  /** Get browser user agent string */
  userAgent(): Promise<string>;
  
  /** Get WebSocket endpoint URL */
  wsEndpoint(): string;
  
  /** Create new page in default browser context */
  newPage(): Promise<Page>;
  
  /** Get all open pages across all contexts */
  pages(): Promise<Page[]>;
  
  /** Get all targets (pages, workers, etc.) */
  targets(): Target[];
  
  /** Get browser target */
  target(): Target;
  
  /** Wait for target matching predicate */
  waitForTarget(
    predicate: (target: Target) => boolean,
    options?: WaitForTargetOptions
  ): Promise<Target>;
  
  /** Create new browser context (incognito-like) */
  createBrowserContext(options?: BrowserContextOptions): Promise<BrowserContext>;
  
  /** Get all browser contexts */
  browserContexts(): BrowserContext[];
  
  /** Get default browser context */
  defaultBrowserContext(): BrowserContext;
  
  /** Get browser child process (null if connected remotely) */
  process(): ChildProcess | null;
  
  /** Check if browser is connected */
  isConnected(): boolean;
  
  /** Close browser and all pages */
  close(): Promise<void>;
  
  /** Disconnect from browser (without closing) */
  disconnect(): Promise<void>;
  
  /** Get all cookies from all contexts */
  cookies(): Promise<Cookie[]>;
  
  /** Set cookies for all contexts */
  setCookie(...cookies: CookieData[]): Promise<void>;
  
  /** Delete cookies from all contexts */
  deleteCookie(...cookies: Cookie[]): Promise<void>;
}

interface WaitForTargetOptions {
  /** Timeout in milliseconds */
  timeout?: number;
}

interface BrowserContextOptions {
  /** Proxy server settings */
  proxyServer?: string;
  /** Proxy bypass list */
  proxyBypassList?: string[];
  /** Proxy username */
  proxyUsername?: string;
  /** Proxy password */
  proxyPassword?: string;
}

interface CookieData {
  /** Cookie name */
  name: string;
  /** Cookie value */
  value: string;
  /** Cookie domain */
  domain?: string;
  /** Cookie path */
  path?: string;
  /** Expiration timestamp */
  expires?: number;
  /** HTTP only flag */
  httpOnly?: boolean;
  /** Secure flag */
  secure?: boolean;
  /** SameSite policy */
  sameSite?: "Strict" | "Lax" | "None";
}

const browser = await puppeteer.launch();

// Get browser info
const version = await browser.version();
const userAgent = await browser.userAgent();

// Create pages
const page1 = await browser.newPage();
const page2 = await browser.newPage();

// Get all pages
const pages = await browser.pages();
console.log(`Open pages: ${pages.length}`);

// Wait for new page
const newPage = await browser.waitForTarget(
  target => target.type() === "page"
).then(target => target.page());

// Create isolated context
const context = await browser.createBrowserContext();
const contextPage = await context.newPage();

await browser.close();

/**
 * Isolated browser context with separate state
 */
class BrowserContext {
  /** Get parent browser */
  browser(): Browser;
  
  /** Create new page in this context */
  newPage(): Promise<Page>;
  
  /** Get all pages in this context */
  pages(): Promise<Page[]>;
  
  /** Get all targets in this context */
  targets(): Target[];
  
  /** Wait for target in this context */
  waitForTarget(
    predicate: (target: Target) => boolean,
    options?: WaitForTargetOptions
  ): Promise<Target>;
  
  /** Close context and all its pages */
  close(): Promise<void>;
  
  /** Override permissions for origins */
  overridePermissions(
    origin: string,
    permissions: Permission[]
  ): Promise<void>;
  
  /** Clear permission overrides */
  clearPermissionOverrides(): Promise<void>;
  
  /** Get cookies for this context */
  cookies(): Promise<Cookie[]>;
  
  /** Set cookies for this context */
  setCookie(...cookies: CookieData[]): Promise<void>;
  
  /** Delete cookies from this context */
  deleteCookie(...cookies: Cookie[]): Promise<void>;
}

type Permission =
  | "geolocation"
  | "midi"
  | "notifications"
  | "camera"
  | "microphone"
  | "background-sync"
  | "ambient-light-sensor"
  | "accelerometer"
  | "gyroscope"
  | "magnetometer"
  | "accessibility-events"
  | "clipboard-read"
  | "clipboard-write"
  | "payment-handler"
  | "idle-detection"
  | "midi-sysex";

const browser = await puppeteer.launch();

// Create isolated context
const context = await browser.createBrowserContext();

// Set permissions
await context.overridePermissions("https://example.com", [
  "geolocation",
  "notifications"
]);

// Create page in context
const page = await context.newPage();
await page.goto("https://example.com");

// Set context-specific cookies
await context.setCookie({
  name: "session",
  value: "abc123",
  domain: "example.com"
});

// Clean up
await context.close();
await browser.close();

/**
 * Get default launch arguments for the browser
 * @param options - Launch options to determine arguments for
 * @returns Array of command line arguments
 */
function defaultArgs(options?: LaunchOptions): string[];

/**
 * Get path to browser executable
 * @returns Path to browser executable
 */
function executablePath(): string;

/**
 * Remove old browser binaries from cache
 * @returns Promise that resolves when cleanup is complete
 */
function trimCache(): Promise<void>;

// Get default arguments
const args = puppeteer.defaultArgs({
  headless: false,
  devtools: true
});
console.log("Default args:", args);

// Get executable path
const execPath = puppeteer.executablePath();
console.log("Browser location:", execPath);

// Clean up old binaries
await puppeteer.trimCache();