Browser Management

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

interface LaunchOptions {
  /** Path to browser executable (required for puppeteer-core) */
  executablePath?: string;
  /** Run browser in headless mode */
  headless?: boolean | "new";
  /** Additional command line arguments */
  args?: string[];
  /** Ignore default arguments */
  ignoreDefaultArgs?: boolean | string[];
  /** Handle SIGINT signal */
  handleSIGINT?: boolean;
  /** Handle SIGTERM signal */
  handleSIGTERM?: boolean;
  /** Handle SIGHUP signal */
  handleSIGHUP?: boolean;
  /** Timeout for browser launch */
  timeout?: number;
  /** Dump browser output to console */
  dumpio?: boolean;
  /** User data directory path */
  userDataDir?: string;
  /** Environment variables */
  env?: Record<string, string | undefined>;
  /** Open browser devtools */
  devtools?: boolean;
  /** Use pipe transport instead of websocket */
  pipe?: boolean;
  /** Slow down operations by specified milliseconds */
  slowMo?: number;
  /** Default viewport for pages */
  defaultViewport?: Viewport | null;
  /** Ignore HTTPS errors */
  ignoreHTTPSErrors?: boolean;
  /** Target filter for connection */
  targetFilter?: (target: Target) => boolean;
  /** Default timeout settings */
  timeout?: number;
  /** Browser type (chrome or firefox) */
  browser?: "chrome" | "firefox";
  /** Browser channel */
  channel?: string;
  /** Protocol to use */
  protocol?: "cdp" | "webDriverBiDi";
  /** Browser arguments for debugging */
  debuggingPort?: number;
}

import puppeteer from "puppeteer-core";

// Basic launch
const browser = await puppeteer.launch({
  executablePath: "/path/to/chrome",
  headless: true
});

// Launch with custom arguments
const browser = await puppeteer.launch({
  executablePath: "/usr/bin/google-chrome",
  headless: false,
  args: ["--no-sandbox", "--disable-dev-shm-usage"],
  defaultViewport: { width: 1920, height: 1080 }
});

// Launch for debugging
const browser = await puppeteer.launch({
  executablePath: "/path/to/chrome",
  headless: false,
  devtools: true,
  slowMo: 100
});

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

interface ConnectOptions {
  /** WebSocket endpoint of the browser */
  browserWSEndpoint?: string;
  /** HTTP URL of the browser */
  browserURL?: string;
  /** Ignore HTTPS errors */
  ignoreHTTPSErrors?: boolean;
  /** Default viewport for new pages */
  defaultViewport?: Viewport | null;
  /** Slow down operations by specified milliseconds */
  slowMo?: number;
  /** Filter targets during connection */
  targetFilter?: (target: Target) => boolean;
  /** Additional headers for connection */
  headers?: Record<string, string>;
  /** Protocol to use */
  protocol?: "cdp" | "webDriverBiDi";
}

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

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

// Connect with custom headers
const browser = await puppeteer.connect({
  browserWSEndpoint: "ws://remote:9222/devtools/browser",
  headers: { "Authorization": "Bearer token" }
});

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

// Get default arguments
const args = puppeteer.defaultArgs();
console.log(args); // ["--disable-background-networking", "--enable-features=...", ...]

// Get arguments for headless mode
const headlessArgs = puppeteer.defaultArgs({ headless: true });

// Get arguments excluding specific ones
const customArgs = puppeteer.defaultArgs({ 
  ignoreDefaultArgs: ["--disable-extensions"] 
});

/**
 * Get path to browser executable
 * @returns Path to executable or empty string for puppeteer-core
 */
function executablePath(): string;

// Get executable path (empty for puppeteer-core)
const path = puppeteer.executablePath();
console.log(path); // "" - must provide executablePath in launch options

interface Browser extends EventEmitter {
  /** Get the browser process (Node.js only) */
  process(): ChildProcess | null;
  /** Create new isolated browser context */
  createBrowserContext(options?: BrowserContextOptions): Promise<BrowserContext>;
  /** Get all browser contexts */
  browserContexts(): BrowserContext[];
  /** Get default browser context */
  defaultBrowserContext(): BrowserContext;
  /** Get WebSocket endpoint */
  wsEndpoint(): string;
  /** Create new page in default context */
  newPage(): Promise<Page>;
  /** Get all targets (pages, workers, etc.) */
  targets(): Target[];
  /** Get browser version */
  version(): Promise<string>;
  /** Get browser user agent */
  userAgent(): Promise<string>;
  /** Close browser and all pages */
  close(): Promise<void>;
  /** Disconnect from browser without closing */
  disconnect(): Promise<void>;
  /** Check if browser is connected */
  connected: boolean;
  /** Get protocol type being used */
  protocol: "cdp" | "webDriverBiDi";
  /** Install browser extension (Chrome only) */
  installExtension(path: string): Promise<string>;
  /** Uninstall browser extension (Chrome only) */
  uninstallExtension(id: string): Promise<void>;
}

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

const browser = await puppeteer.launch({ executablePath: "/path/to/chrome" });

// Create new page
const page = await browser.newPage();

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

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

// Check connection
if (browser.connected) {
  console.log("Browser is connected");
}

// Handle browser events
browser.on("disconnected", () => {
  console.log("Browser disconnected");
});

browser.on("targetcreated", (target) => {
  console.log("New target created:", target.type());
});

// Close browser
await browser.close();

interface BrowserEvents {
  /** Emitted when browser disconnects */
  "disconnected": () => void;
  /** Emitted when new target is created */
  "targetcreated": (target: Target) => void;
  /** Emitted when target is destroyed */
  "targetdestroyed": (target: Target) => void;
  /** Emitted when target URL changes */
  "targetchanged": (target: Target) => void;
}

class TimeoutError extends Error {
  constructor(message: string);
}

class ProtocolError extends Error {
  constructor(message: string);
  originalMessage: string;
}

try {
  const browser = await puppeteer.launch({
    executablePath: "/invalid/path",
    timeout: 30000
  });
} catch (error) {
  if (error instanceof TimeoutError) {
    console.log("Browser launch timed out");
  } else if (error.message.includes("Failed to launch")) {
    console.log("Invalid executable path or browser failed to start");
  }
}

interface Device {
  userAgent: string;
  viewport: Viewport;
}

const KnownDevices: Record<string, Device>;

// Example known devices (partial list):
// - iPhone 15 Pro, iPhone 15 Pro Max
// - iPhone 14, iPhone 14 Plus, iPhone 14 Pro, iPhone 14 Pro Max  
// - iPhone 13 Pro, iPhone 13 Pro Max, iPhone 13 Mini
// - iPhone 12, iPhone 12 Pro, iPhone 12 Pro Max, iPhone 12 Mini
// - iPhone 11, iPhone 11 Pro, iPhone 11 Pro Max
// - iPhone X, iPhone XR, iPhone 8, iPhone 8 Plus, iPhone 7, iPhone 6
// - iPad Pro, iPad Pro 11, iPad, iPad Mini
// - Galaxy S9+, Galaxy S8, Galaxy S5, Galaxy Note 3, Galaxy Tab S4
// - Pixel 5, Pixel 4, Pixel 3, Pixel 2, Pixel 2 XL
// - Nexus 7, Nexus 6P, Nexus 5X, Nexus 5, Nexus 4, Nexus 10
// - Moto G4, BlackBerry Z30, Microsoft Lumia 950
// - And many more...

import puppeteer, { KnownDevices } from "puppeteer-core";

const browser = await puppeteer.launch({ executablePath: "/path/to/chrome" });
const page = await browser.newPage();

// Emulate iPhone 15 Pro
const iPhone15Pro = KnownDevices['iPhone 15 Pro'];
await page.emulate(iPhone15Pro);

// Emulate iPad Pro
const iPadPro = KnownDevices['iPad Pro'];
await page.emulate(iPadPro);

// Emulate Galaxy S9+
const galaxyS9Plus = KnownDevices['Galaxy S9+'];
await page.emulate(galaxyS9Plus);

// Custom device emulation
const customDevice = {
  userAgent: 'Mozilla/5.0 (Linux; Android 9; Custom Device) AppleWebKit/537.36',
  viewport: {
    width: 414,
    height: 896,
    deviceScaleFactor: 2,
    isMobile: true,
    hasTouch: true,
    isLandscape: false
  }
};
await page.emulate(customDevice);

await page.goto("https://example.com");
await browser.close();