playwriter 0.0.30 → 0.0.33

package/dist/debugger-api.md

@@ -0,0 +1,457 @@
+# Debugger API Reference
+
+## Types
+
+```ts
+import type { CDPSession } from './cdp-session.js';
+export interface BreakpointInfo {
+    id: string;
+    file: string;
+    line: number;
+}
+export interface LocationInfo {
+    url: string;
+    lineNumber: number;
+    columnNumber: number;
+    callstack: Array<{
+        functionName: string;
+        url: string;
+        lineNumber: number;
+        columnNumber: number;
+    }>;
+    sourceContext: string;
+}
+export interface EvaluateResult {
+    value: unknown;
+}
+export interface ScriptInfo {
+    scriptId: string;
+    url: string;
+}
+/**
+ * A class for debugging JavaScript code via Chrome DevTools Protocol.
+ * Works with both Node.js (--inspect) and browser debugging.
+ *
+ * @example
+ * ```ts
+ * const cdp = await getCDPSessionForPage({ page, wsUrl })
+ * const dbg = new Debugger({ cdp })
+ *
+ * await dbg.setBreakpoint({ file: 'https://example.com/app.js', line: 42 })
+ * // trigger the code path, then:
+ * const location = await dbg.getLocation()
+ * const vars = await dbg.inspectLocalVariables()
+ * await dbg.resume()
+ * ```
+ */
+export declare class Debugger {
+    private cdp;
+    private debuggerEnabled;
+    private paused;
+    private currentCallFrames;
+    private breakpoints;
+    private scripts;
+    private xhrBreakpoints;
+    private blackboxPatterns;
+    /**
+     * Creates a new Debugger instance.
+     *
+     * @param options - Configuration options
+     * @param options.cdp - A CDPSession instance for sending CDP commands
+     *
+     * @example
+     * ```ts
+     * const cdp = await getCDPSessionForPage({ page, wsUrl })
+     * const dbg = new Debugger({ cdp })
+     * ```
+     */
+    constructor({ cdp }: {
+        cdp: CDPSession;
+    });
+    private setupEventListeners;
+    /**
+     * Enables the debugger and runtime domains. Called automatically by other methods.
+     * Also resumes execution if the target was started with --inspect-brk.
+     *
+     * @example
+     * ```ts
+     * await dbg.enable()
+     * ```
+     */
+    enable(): Promise<void>;
+    /**
+     * Sets a breakpoint at a specified URL and line number.
+     * Use the URL from listScripts() to find available scripts.
+     *
+     * @param options - Breakpoint options
+     * @param options.file - Script URL (e.g. https://example.com/app.js)
+     * @param options.line - Line number (1-based)
+     * @param options.condition - Optional JS expression; only pause when it evaluates to true
+     * @returns The breakpoint ID for later removal
+     *
+     * @example
+     * ```ts
+     * const id = await dbg.setBreakpoint({ file: 'https://example.com/app.js', line: 42 })
+     * // later:
+     * await dbg.deleteBreakpoint({ breakpointId: id })
+     *
+     * // Conditional breakpoint - only pause when userId is 123
+     * await dbg.setBreakpoint({
+     *   file: 'https://example.com/app.js',
+     *   line: 42,
+     *   condition: 'userId === 123'
+     * })
+     * ```
+     */
+    setBreakpoint({ file, line, condition }: {
+        file: string;
+        line: number;
+        condition?: string;
+    }): Promise<string>;
+    /**
+     * Removes a breakpoint by its ID.
+     *
+     * @param options - Options
+     * @param options.breakpointId - The breakpoint ID returned by setBreakpoint
+     *
+     * @example
+     * ```ts
+     * await dbg.deleteBreakpoint({ breakpointId: 'bp-123' })
+     * ```
+     */
+    deleteBreakpoint({ breakpointId }: {
+        breakpointId: string;
+    }): Promise<void>;
+    /**
+     * Returns a list of all active breakpoints set by this debugger instance.
+     *
+     * @returns Array of breakpoint info objects
+     *
+     * @example
+     * ```ts
+     * const breakpoints = dbg.listBreakpoints()
+     * // [{ id: 'bp-123', file: 'https://example.com/index.js', line: 42 }]
+     * ```
+     */
+    listBreakpoints(): BreakpointInfo[];
+    /**
+     * Inspects local variables in the current call frame.
+     * Must be paused at a breakpoint. String values over 1000 chars are truncated.
+     * Use evaluate() for full control over reading specific values.
+     *
+     * @returns Record of variable names to values
+     * @throws Error if not paused or no active call frames
+     *
+     * @example
+     * ```ts
+     * const vars = await dbg.inspectLocalVariables()
+     * // { myVar: 'hello', count: 42 }
+     * ```
+     */
+    inspectLocalVariables(): Promise<Record<string, unknown>>;
+    /**
+     * Returns global lexical scope variable names.
+     *
+     * @returns Array of global variable names
+     *
+     * @example
+     * ```ts
+     * const globals = await dbg.inspectGlobalVariables()
+     * // ['myGlobal', 'CONFIG']
+     * ```
+     */
+    inspectGlobalVariables(): Promise<string[]>;
+    /**
+     * Evaluates a JavaScript expression and returns the result.
+     * When paused at a breakpoint, evaluates in the current stack frame scope,
+     * allowing access to local variables. Otherwise evaluates in global scope.
+     * Values are not truncated, use this for full control over reading specific variables.
+     *
+     * @param options - Options
+     * @param options.expression - JavaScript expression to evaluate
+     * @returns The result value
+     *
+     * @example
+     * ```ts
+     * // When paused, can access local variables:
+     * const result = await dbg.evaluate({ expression: 'localVar + 1' })
+     *
+     * // Read a large string that would be truncated in inspectLocalVariables:
+     * const full = await dbg.evaluate({ expression: 'largeStringVar' })
+     * ```
+     */
+    evaluate({ expression }: {
+        expression: string;
+    }): Promise<EvaluateResult>;
+    /**
+     * Gets the current execution location when paused at a breakpoint.
+     * Includes the call stack and surrounding source code for context.
+     *
+     * @returns Location info with URL, line number, call stack, and source context
+     * @throws Error if debugger is not paused
+     *
+     * @example
+     * ```ts
+     * const location = await dbg.getLocation()
+     * console.log(location.url)          // 'https://example.com/src/index.js'
+     * console.log(location.lineNumber)   // 42
+     * console.log(location.callstack)    // [{ functionName: 'handleRequest', ... }]
+     * console.log(location.sourceContext)
+     * // '  40: function handleRequest(req) {
+     * //   41:   const data = req.body
+     * // > 42:   processData(data)
+     * //   43: }'
+     * ```
+     */
+    getLocation(): Promise<LocationInfo>;
+    /**
+     * Steps over to the next line of code, not entering function calls.
+     *
+     * @throws Error if debugger is not paused
+     *
+     * @example
+     * ```ts
+     * await dbg.stepOver()
+     * const newLocation = await dbg.getLocation()
+     * ```
+     */
+    stepOver(): Promise<void>;
+    /**
+     * Steps into a function call on the current line.
+     *
+     * @throws Error if debugger is not paused
+     *
+     * @example
+     * ```ts
+     * await dbg.stepInto()
+     * const location = await dbg.getLocation()
+     * // now inside the called function
+     * ```
+     */
+    stepInto(): Promise<void>;
+    /**
+     * Steps out of the current function, returning to the caller.
+     *
+     * @throws Error if debugger is not paused
+     *
+     * @example
+     * ```ts
+     * await dbg.stepOut()
+     * const location = await dbg.getLocation()
+     * // back in the calling function
+     * ```
+     */
+    stepOut(): Promise<void>;
+    /**
+     * Resumes code execution until the next breakpoint or completion.
+     *
+     * @throws Error if debugger is not paused
+     *
+     * @example
+     * ```ts
+     * await dbg.resume()
+     * // execution continues
+     * ```
+     */
+    resume(): Promise<void>;
+    /**
+     * Returns whether the debugger is currently paused at a breakpoint.
+     *
+     * @returns true if paused, false otherwise
+     *
+     * @example
+     * ```ts
+     * if (dbg.isPaused()) {
+     *   const vars = await dbg.inspectLocalVariables()
+     * }
+     * ```
+     */
+    isPaused(): boolean;
+    /**
+     * Configures the debugger to pause on exceptions.
+     *
+     * @param options - Options
+     * @param options.state - When to pause: 'none' (never), 'uncaught' (only uncaught), or 'all' (all exceptions)
+     *
+     * @example
+     * ```ts
+     * // Pause only on uncaught exceptions
+     * await dbg.setPauseOnExceptions({ state: 'uncaught' })
+     *
+     * // Pause on all exceptions (caught and uncaught)
+     * await dbg.setPauseOnExceptions({ state: 'all' })
+     *
+     * // Disable pausing on exceptions
+     * await dbg.setPauseOnExceptions({ state: 'none' })
+     * ```
+     */
+    setPauseOnExceptions({ state }: {
+        state: 'none' | 'uncaught' | 'all';
+    }): Promise<void>;
+    /**
+     * Lists available scripts where breakpoints can be set.
+     * Automatically enables the debugger if not already enabled.
+     *
+     * @param options - Options
+     * @param options.search - Optional string to filter scripts by URL (case-insensitive)
+     * @returns Array of up to 20 matching scripts with scriptId and url
+     *
+     * @example
+     * ```ts
+     * // List all scripts
+     * const scripts = await dbg.listScripts()
+     * // [{ scriptId: '1', url: 'https://example.com/app.js' }, ...]
+     *
+     * // Search for specific files
+     * const handlers = await dbg.listScripts({ search: 'handler' })
+     * // [{ scriptId: '5', url: 'https://example.com/handlers.js' }]
+     * ```
+     */
+    listScripts({ search }?: {
+        search?: string;
+    }): Promise<ScriptInfo[]>;
+    setXHRBreakpoint({ url }: {
+        url: string;
+    }): Promise<void>;
+    removeXHRBreakpoint({ url }: {
+        url: string;
+    }): Promise<void>;
+    listXHRBreakpoints(): string[];
+    /**
+     * Sets regex patterns for scripts to blackbox (skip when stepping).
+     * Blackboxed scripts are hidden from the call stack and stepped over automatically.
+     * Useful for ignoring framework/library code during debugging.
+     *
+     * @param options - Options
+     * @param options.patterns - Array of regex patterns to match script URLs
+     *
+     * @example
+     * ```ts
+     * // Skip all node_modules
+     * await dbg.setBlackboxPatterns({ patterns: ['node_modules'] })
+     *
+     * // Skip React and other frameworks
+     * await dbg.setBlackboxPatterns({
+     *   patterns: [
+     *     'node_modules/react',
+     *     'node_modules/react-dom',
+     *     'node_modules/next',
+     *     'webpack://',
+     *   ]
+     * })
+     *
+     * // Skip all third-party scripts
+     * await dbg.setBlackboxPatterns({ patterns: ['^https://cdn\\.'] })
+     *
+     * // Clear all blackbox patterns
+     * await dbg.setBlackboxPatterns({ patterns: [] })
+     * ```
+     */
+    setBlackboxPatterns({ patterns }: {
+        patterns: string[];
+    }): Promise<void>;
+    /**
+     * Adds a single regex pattern to the blackbox list.
+     *
+     * @param options - Options
+     * @param options.pattern - Regex pattern to match script URLs
+     *
+     * @example
+     * ```ts
+     * await dbg.addBlackboxPattern({ pattern: 'node_modules/lodash' })
+     * await dbg.addBlackboxPattern({ pattern: 'node_modules/axios' })
+     * ```
+     */
+    addBlackboxPattern({ pattern }: {
+        pattern: string;
+    }): Promise<void>;
+    /**
+     * Removes a pattern from the blackbox list.
+     *
+     * @param options - Options
+     * @param options.pattern - The exact pattern string to remove
+     */
+    removeBlackboxPattern({ pattern }: {
+        pattern: string;
+    }): Promise<void>;
+    /**
+     * Returns the current list of blackbox patterns.
+     */
+    listBlackboxPatterns(): string[];
+    private truncateValue;
+    private formatPropertyValue;
+    private processRemoteObject;
+}
+```
+
+## Examples
+
+```ts
+import { page, getCDPSession, createDebugger, console } from './debugger-examples-types.js'
+
+// Example: List available scripts and set a breakpoint
+async function listScriptsAndSetBreakpoint() {
+  const cdp = await getCDPSession({ page })
+  const dbg = createDebugger({ cdp })
+  await dbg.enable()
+
+  const scripts = await dbg.listScripts({ search: 'app' })
+  console.log(scripts)
+
+  if (scripts.length > 0) {
+    const bpId = await dbg.setBreakpoint({ file: scripts[0].url, line: 100 })
+    console.log('Breakpoint set:', bpId)
+  }
+}
+
+// Example: Inspect state when paused at a breakpoint
+async function inspectWhenPaused() {
+  const cdp = await getCDPSession({ page })
+  const dbg = createDebugger({ cdp })
+  await dbg.enable()
+
+  if (dbg.isPaused()) {
+    const loc = await dbg.getLocation()
+    console.log('Paused at:', loc.url, 'line', loc.lineNumber)
+    console.log('Source:', loc.sourceContext)
+
+    const vars = await dbg.inspectLocalVariables()
+    console.log('Variables:', vars)
+
+    const result = await dbg.evaluate({ expression: 'myVar.length' })
+    console.log('myVar.length =', result.value)
+
+    await dbg.stepOver()
+  }
+}
+
+// Example: Step through code
+async function stepThroughCode() {
+  const cdp = await getCDPSession({ page })
+  const dbg = createDebugger({ cdp })
+  await dbg.enable()
+
+  await dbg.setBreakpoint({ file: 'https://example.com/app.js', line: 42 })
+
+  if (dbg.isPaused()) {
+    await dbg.stepOver()
+    await dbg.stepInto()
+    await dbg.stepOut()
+    await dbg.resume()
+  }
+}
+
+// Example: Cleanup all breakpoints
+async function cleanupBreakpoints() {
+  const cdp = await getCDPSession({ page })
+  const dbg = createDebugger({ cdp })
+
+  const breakpoints = dbg.listBreakpoints()
+  for (const bp of breakpoints) {
+    await dbg.deleteBreakpoint({ breakpointId: bp.id })
+  }
+}
+
+export { listScriptsAndSetBreakpoint, inspectWhenPaused, stepThroughCode, cleanupBreakpoints }
+
+```

package/dist/debugger-examples-types.d.ts

@@ -1,7 +1,8 @@
-import type { Page } from 'playwright-core';
+import type { Page, Locator } from 'playwright-core';
 import type { CDPSession } from './cdp-session.js';
 import type { Debugger } from './debugger.js';
 import type { Editor } from './editor.js';
+import type { StylesResult } from './styles.js';
 export declare const page: Page;
 export declare const getCDPSession: (options: {
     page: Page;
@@ -12,6 +13,11 @@ export declare const createDebugger: (options: {
 export declare const createEditor: (options: {
     cdp: CDPSession;
 }) => Editor;
+export declare const getStylesForLocator: (options: {
+    locator: Locator;
+    includeUserAgentStyles?: boolean;
+}) => Promise<StylesResult>;
+export declare const formatStylesAsText: (styles: StylesResult) => string;
 export declare const console: {
     log: (...args: unknown[]) => void;
 };

package/dist/debugger-examples-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"debugger-examples-types.d.ts","sourceRoot":"","sources":["../src/debugger-examples-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzC,MAAM,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,IAAI,CAAA;AAC/B,MAAM,CAAC,OAAO,CAAC,MAAM,aAAa,EAAE,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;AACpF,MAAM,CAAC,OAAO,CAAC,MAAM,cAAc,EAAE,CAAC,OAAO,EAAE;IAAE,GAAG,EAAE,UAAU,CAAA;CAAE,KAAK,QAAQ,CAAA;AAC/E,MAAM,CAAC,OAAO,CAAC,MAAM,YAAY,EAAE,CAAC,OAAO,EAAE;IAAE,GAAG,EAAE,UAAU,CAAA;CAAE,KAAK,MAAM,CAAA;AAC3E,MAAM,CAAC,OAAO,CAAC,MAAM,OAAO,EAAE;IAAE,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;CAAE,CAAA"}
+{"version":3,"file":"debugger-examples-types.d.ts","sourceRoot":"","sources":["../src/debugger-examples-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C,MAAM,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,IAAI,CAAA;AAC/B,MAAM,CAAC,OAAO,CAAC,MAAM,aAAa,EAAE,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;AACpF,MAAM,CAAC,OAAO,CAAC,MAAM,cAAc,EAAE,CAAC,OAAO,EAAE;IAAE,GAAG,EAAE,UAAU,CAAA;CAAE,KAAK,QAAQ,CAAA;AAC/E,MAAM,CAAC,OAAO,CAAC,MAAM,YAAY,EAAE,CAAC,OAAO,EAAE;IAAE,GAAG,EAAE,UAAU,CAAA;CAAE,KAAK,MAAM,CAAA;AAC3E,MAAM,CAAC,OAAO,CAAC,MAAM,mBAAmB,EAAE,CAAC,OAAO,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,sBAAsB,CAAC,EAAE,OAAO,CAAA;CAAE,KAAK,OAAO,CAAC,YAAY,CAAC,CAAA;AACpI,MAAM,CAAC,OAAO,CAAC,MAAM,kBAAkB,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,MAAM,CAAA;AACzE,MAAM,CAAC,OAAO,CAAC,MAAM,OAAO,EAAE;IAAE,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;CAAE,CAAA"}