💬 Commit message: Update 2026-02-11 04:13:54, 13 files, 595 lines
📁 Files changed: 13 📝 Lines changed: 595 • PLAN.md • TODO.md • browser.d.ts • browser.d.ts.map • browser.js • browser.js.map • mcp.js • mcp.js.map • types.d.ts • types.d.ts.map • browser.ts • mcp.ts • types.ts
This commit is contained in:
Adam Ladachowski
@@ -1,238 +1,249 @@
|
||||
# Plan: Web Debugging Commands
|
||||
# Plan: Playwright Debugging Features
|
||||
|
||||
## Phase 1: Storage & Session Commands
|
||||
## Phase 1: Core Debugging (Console & Errors)
|
||||
|
||||
### Description
|
||||
Add commands for inspecting and manipulating browser storage and cookies. These are essential for debugging authentication, session state, and client-side data persistence.
|
||||
Implement fundamental debugging capabilities: console message capture and uncaught exception handling. These form the foundation for debugging client-side issues.
|
||||
|
||||
### Steps
|
||||
|
||||
#### Step 1.1: Add Cookies Command
|
||||
- **Objective**: Implement get/set/clear cookies functionality
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/server.ts`, `src/index.ts`
|
||||
#### Step 1.1: Add Console Command
|
||||
- **Objective**: Capture and retrieve console messages from browser
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
|
||||
- **Dependencies**: None
|
||||
- **Status**: COMPLETE
|
||||
- **Implementation**:
|
||||
- Add `CookiesCommand` type with `action: 'get' | 'set' | 'clear'`
|
||||
- Add optional `name`, `value`, `url` fields for set operation
|
||||
- Implement `cookies()` method using `context.cookies()` and `context.addCookies()`
|
||||
- Add logging with cookie icon
|
||||
- Add `ConsoleCommand` type with `level` filter and `clear` option
|
||||
- Store messages via `page.on('console')` listener
|
||||
- Return messages with level, text, timestamp, location
|
||||
|
||||
#### Step 1.2: Add Storage Command
|
||||
- **Objective**: Implement localStorage and sessionStorage read/write/clear
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/server.ts`, `src/index.ts`
|
||||
#### Step 1.2: Add Page Errors Command
|
||||
- **Objective**: Capture uncaught exceptions and unhandled promise rejections
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
|
||||
- **Dependencies**: Step 1.1
|
||||
- **Implementation**:
|
||||
- Add `StorageCommand` type with `storage: 'local' | 'session'` and `action: 'get' | 'set' | 'clear'`
|
||||
- Implement via `page.evaluate()` accessing `window.localStorage` / `window.sessionStorage`
|
||||
- Return all items on get, or specific key if provided
|
||||
- Add `ErrorsCommand` type with `clear` option
|
||||
- Listen to `page.on('pageerror')` for uncaught exceptions
|
||||
- Store error message, stack trace, timestamp
|
||||
- Add `browser://errors` MCP resource
|
||||
|
||||
## Phase 2: Console & Debugging Commands
|
||||
## Phase 2: Network Monitoring
|
||||
|
||||
### Description
|
||||
Add commands for capturing console output and debugging page state. Critical for understanding client-side errors and application behavior.
|
||||
Implement network request/response capture for debugging API calls, identifying failed requests, and inspecting payloads.
|
||||
|
||||
### Steps
|
||||
|
||||
#### Step 2.1: Add Console Command
|
||||
- **Objective**: Capture and return console messages (log, error, warn, info)
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/server.ts`, `src/index.ts`
|
||||
#### Step 2.1: Add Network Logging
|
||||
- **Objective**: Capture all network requests and responses
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
|
||||
- **Dependencies**: None
|
||||
- **Implementation**:
|
||||
- Add `ConsoleCommand` type with optional `clear: boolean`
|
||||
- Store console messages in array via `page.on('console')`
|
||||
- Initialize listener in `launch()` method
|
||||
- Return accumulated messages with type, text, and timestamp
|
||||
- Add `NetworkCommand` type with `filter` and `clear` options
|
||||
- Listen to `page.on('request')` and `page.on('response')`
|
||||
- Store: url, method, status, resourceType, timing, headers
|
||||
- Add optional body capture for XHR/fetch (with size limit)
|
||||
- Add `browser://network` MCP resource
|
||||
|
||||
#### Step 2.2: Add Metrics Command
|
||||
- **Objective**: Return performance metrics and DOM statistics
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/server.ts`, `src/index.ts`
|
||||
#### Step 2.2: Add Failed Requests Filter
|
||||
- **Objective**: Quick access to failed/error requests
|
||||
- **Files**: `src/browser.ts`, `src/mcp.ts`
|
||||
- **Dependencies**: Step 2.1
|
||||
- **Implementation**:
|
||||
- Add `failed` filter option to NetworkCommand
|
||||
- Include requests with status >= 400 or network errors
|
||||
- Add `browser://network/failed` MCP resource
|
||||
|
||||
#### Step 2.3: Add Request Interception
|
||||
- **Objective**: Block or mock specific requests
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
|
||||
- **Dependencies**: Step 2.1
|
||||
- **Implementation**:
|
||||
- Add `InterceptCommand` with `action: 'block' | 'mock' | 'clear'`
|
||||
- Support URL patterns (glob or regex)
|
||||
- For mock: allow custom response body/status
|
||||
- Use `page.route()` for interception
|
||||
|
||||
## Phase 3: Performance & Metrics
|
||||
|
||||
### Description
|
||||
Add performance timing and metrics collection for identifying bottlenecks and measuring page load characteristics.
|
||||
|
||||
### Steps
|
||||
|
||||
#### Step 3.1: Add Performance Metrics
|
||||
- **Objective**: Return page performance timing data
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
|
||||
- **Dependencies**: None
|
||||
- **Implementation**:
|
||||
- Add `MetricsCommand` type
|
||||
- Use `page.evaluate()` to gather `performance.timing`, DOM node counts
|
||||
- Return structured metrics object
|
||||
- Collect via `performance.timing` and `performance.getEntriesByType()`
|
||||
- Return: domContentLoaded, load, firstPaint, firstContentfulPaint
|
||||
- Include DOM stats: nodeCount, scriptCount, styleCount
|
||||
|
||||
## Phase 3: Interaction Commands
|
||||
#### Step 3.2: Add Resource Timing
|
||||
- **Objective**: Get timing breakdown for individual resources
|
||||
- **Files**: `src/browser.ts`, `src/mcp.ts`
|
||||
- **Dependencies**: Step 3.1
|
||||
- **Implementation**:
|
||||
- Add `resources` option to MetricsCommand
|
||||
- Use `performance.getEntriesByType('resource')`
|
||||
- Return: name, duration, transferSize, initiatorType
|
||||
|
||||
## Phase 4: Accessibility
|
||||
|
||||
### Description
|
||||
Add commands for advanced page interactions beyond click and type. Enables testing hover states, keyboard shortcuts, and form controls.
|
||||
Implement accessibility tree inspection for debugging screen reader and a11y issues.
|
||||
|
||||
### Steps
|
||||
|
||||
#### Step 3.1: Add Scroll Command
|
||||
- **Objective**: Scroll to position, element, or by delta
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/server.ts`, `src/index.ts`
|
||||
#### Step 4.1: Add Accessibility Snapshot
|
||||
- **Objective**: Dump accessibility tree for page or element
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
|
||||
- **Dependencies**: None
|
||||
- **Implementation**:
|
||||
- Add `ScrollCommand` with `selector?: string`, `x?: number`, `y?: number`, `behavior?: 'smooth' | 'instant'`
|
||||
- If selector provided, use `element.scrollIntoView()`
|
||||
- Otherwise use `window.scrollTo()`
|
||||
|
||||
#### Step 3.2: Add Hover Command
|
||||
- **Objective**: Trigger hover state on element
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/server.ts`, `src/index.ts`
|
||||
- **Dependencies**: None
|
||||
- **Implementation**:
|
||||
- Add `HoverCommand` with `selector: string`
|
||||
- Use `page.hover(selector)`
|
||||
- Return success with element info
|
||||
|
||||
#### Step 3.3: Add Select Command
|
||||
- **Objective**: Select option(s) in dropdown/select elements
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/server.ts`, `src/index.ts`
|
||||
- **Dependencies**: None
|
||||
- **Implementation**:
|
||||
- Add `SelectCommand` with `selector: string`, `value: string | string[]`
|
||||
- Use `page.selectOption(selector, value)`
|
||||
- Return selected values
|
||||
|
||||
#### Step 3.4: Add Keys Command
|
||||
- **Objective**: Send keyboard shortcuts and special keys
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/server.ts`, `src/index.ts`
|
||||
- **Dependencies**: None
|
||||
- **Implementation**:
|
||||
- Add `KeysCommand` with `keys: string` (e.g., "Control+a", "Escape", "Enter")
|
||||
- Use `page.keyboard.press()` for single keys
|
||||
- Support key combinations
|
||||
|
||||
## Phase 4: Network Commands
|
||||
|
||||
### Description
|
||||
Add commands for network inspection and manipulation. Enables debugging API calls, blocking resources, and simulating network conditions.
|
||||
|
||||
### Steps
|
||||
|
||||
#### Step 4.1: Add Network Logging
|
||||
- **Objective**: Capture and return network requests/responses
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/server.ts`, `src/index.ts`
|
||||
- **Dependencies**: None
|
||||
- **Implementation**:
|
||||
- Add `NetworkCommand` with `action: 'log' | 'clear'`, optional `filter: string`
|
||||
- Store requests via `page.on('request')` and `page.on('response')`
|
||||
- Return array of {url, method, status, type, timing}
|
||||
|
||||
#### Step 4.2: Add Block Command
|
||||
- **Objective**: Block URLs or patterns (ads, analytics, etc.)
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/server.ts`, `src/index.ts`
|
||||
- **Dependencies**: Step 4.1
|
||||
- **Implementation**:
|
||||
- Add `BlockCommand` with `patterns: string[]` and `action: 'add' | 'remove' | 'clear'`
|
||||
- Use `page.route()` to abort matching requests
|
||||
- Maintain list of blocked patterns
|
||||
|
||||
#### Step 4.3: Add Throttle Command
|
||||
- **Objective**: Simulate slow network conditions
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/server.ts`, `src/index.ts`
|
||||
- **Dependencies**: None
|
||||
- **Implementation**:
|
||||
- Add `ThrottleCommand` with `preset: 'slow3g' | 'fast3g' | 'offline' | 'none'`
|
||||
- Use CDP session to set network conditions via `Network.emulateNetworkConditions`
|
||||
|
||||
## Phase 5: Output Commands
|
||||
|
||||
### Description
|
||||
Add commands for exporting page content in different formats.
|
||||
|
||||
### Steps
|
||||
|
||||
#### Step 5.1: Add PDF Command
|
||||
- **Objective**: Save page as PDF
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/server.ts`, `src/index.ts`
|
||||
- **Dependencies**: None
|
||||
- **Implementation**:
|
||||
- Add `PdfCommand` with `path: string`, optional `format`, `landscape`, `margin`
|
||||
- Use `page.pdf()` (WebKit supports this)
|
||||
- Return path to saved file
|
||||
|
||||
#### Step 5.2: Add Accessibility Command
|
||||
- **Objective**: Dump accessibility tree snapshot
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/server.ts`, `src/index.ts`
|
||||
- **Dependencies**: None
|
||||
- **Implementation**:
|
||||
- Add `AccessibilityCommand` with optional `selector` for subtree
|
||||
- Add `A11yCommand` with optional `selector` for subtree
|
||||
- Use `page.accessibility.snapshot()`
|
||||
- Return tree structure
|
||||
- Return tree with role, name, value, description
|
||||
- Add `browser://a11y` MCP resource
|
||||
|
||||
## Phase 6: Advanced Commands
|
||||
## Phase 5: Dialog Handling
|
||||
|
||||
### Description
|
||||
Add commands for viewport manipulation, device emulation, and frame handling.
|
||||
Implement automatic handling of browser dialogs (alert, confirm, prompt) to prevent blocking during automation.
|
||||
|
||||
### Steps
|
||||
|
||||
#### Step 6.1: Add Viewport Command
|
||||
- **Objective**: Resize viewport dynamically
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/server.ts`, `src/index.ts`
|
||||
#### Step 5.1: Add Dialog Command
|
||||
- **Objective**: Configure how dialogs are handled
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
|
||||
- **Dependencies**: None
|
||||
- **Implementation**:
|
||||
- Add `ViewportCommand` with `width: number`, `height: number`
|
||||
- Add `DialogCommand` with `action: 'accept' | 'dismiss' | 'status'`
|
||||
- Option to set default behavior for future dialogs
|
||||
- Option to provide text response for prompts
|
||||
- Store dialog history (type, message, response)
|
||||
- Listen to `page.on('dialog')`
|
||||
|
||||
## Phase 6: Storage & Cookies
|
||||
|
||||
### Description
|
||||
Add commands for inspecting and manipulating browser storage, complementing the existing session save/restore.
|
||||
|
||||
### Steps
|
||||
|
||||
#### Step 6.1: Add Cookies Command
|
||||
- **Objective**: Get, set, and clear cookies
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
|
||||
- **Dependencies**: None
|
||||
- **Implementation**:
|
||||
- Add `CookiesCommand` with `action: 'get' | 'set' | 'delete' | 'clear'`
|
||||
- Use `context.cookies()` and `context.addCookies()`
|
||||
- Support filtering by name/domain
|
||||
- Add `browser://cookies` MCP resource
|
||||
|
||||
#### Step 6.2: Add Storage Command
|
||||
- **Objective**: Inspect/modify localStorage and sessionStorage
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
|
||||
- **Dependencies**: None
|
||||
- **Implementation**:
|
||||
- Add `StorageCommand` with `type: 'local' | 'session'`
|
||||
- Actions: get, set, delete, clear
|
||||
- Implement via `page.evaluate()`
|
||||
- Add `browser://storage/local` and `browser://storage/session` resources
|
||||
|
||||
## Phase 7: Advanced Interactions
|
||||
|
||||
### Description
|
||||
Add additional interaction commands for comprehensive testing scenarios.
|
||||
|
||||
### Steps
|
||||
|
||||
#### Step 7.1: Add Hover Command
|
||||
- **Objective**: Trigger hover state on elements
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
|
||||
- **Dependencies**: None
|
||||
- **Implementation**:
|
||||
- Add `HoverCommand` with `selector`
|
||||
- Use `page.hover(selector)`
|
||||
|
||||
#### Step 7.2: Add Select Command
|
||||
- **Objective**: Select options in dropdown elements
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
|
||||
- **Dependencies**: None
|
||||
- **Implementation**:
|
||||
- Add `SelectCommand` with `selector` and `value` (or values array)
|
||||
- Use `page.selectOption()`
|
||||
|
||||
#### Step 7.3: Add Keys Command
|
||||
- **Objective**: Send keyboard shortcuts and special keys
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
|
||||
- **Dependencies**: None
|
||||
- **Implementation**:
|
||||
- Add `KeysCommand` with `keys` string (e.g., "Control+a", "Escape")
|
||||
- Use `page.keyboard.press()`
|
||||
|
||||
#### Step 7.4: Add Upload Command
|
||||
- **Objective**: Set files on file input elements
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
|
||||
- **Dependencies**: None
|
||||
- **Implementation**:
|
||||
- Add `UploadCommand` with `selector` and `files` array
|
||||
- Use `page.setInputFiles()`
|
||||
|
||||
#### Step 7.5: Add Scroll Command
|
||||
- **Objective**: Scroll page or element into view
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
|
||||
- **Dependencies**: None
|
||||
- **Implementation**:
|
||||
- Add `ScrollCommand` with optional `selector`, `x`, `y`
|
||||
- If selector: use `element.scrollIntoView()`
|
||||
- Otherwise: use `window.scrollTo()`
|
||||
|
||||
## Phase 8: Viewport & Emulation
|
||||
|
||||
### Description
|
||||
Add device emulation and viewport manipulation for responsive testing.
|
||||
|
||||
### Steps
|
||||
|
||||
#### Step 8.1: Add Viewport Command
|
||||
- **Objective**: Resize browser viewport dynamically
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
|
||||
- **Dependencies**: None
|
||||
- **Implementation**:
|
||||
- Add `ViewportCommand` with `width` and `height`
|
||||
- Use `page.setViewportSize()`
|
||||
- Return new dimensions
|
||||
|
||||
#### Step 6.2: Add Emulate Command
|
||||
- **Objective**: Emulate mobile devices
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/server.ts`, `src/index.ts`
|
||||
- **Dependencies**: Step 6.1
|
||||
#### Step 8.2: Add Emulate Command
|
||||
- **Objective**: Emulate specific devices
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/mcp.ts`
|
||||
- **Dependencies**: Step 8.1
|
||||
- **Implementation**:
|
||||
- Add `EmulateCommand` with `device: string` (e.g., 'iPhone 12', 'Pixel 5')
|
||||
- Add `EmulateCommand` with `device` name
|
||||
- Use Playwright's device descriptors
|
||||
- Apply viewport, userAgent, deviceScaleFactor
|
||||
- Apply viewport, userAgent, deviceScaleFactor, touch support
|
||||
|
||||
#### Step 6.3: Add Frames Command
|
||||
- **Objective**: List and switch to iframe contexts
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/server.ts`, `src/index.ts`
|
||||
- **Dependencies**: None
|
||||
- **Implementation**:
|
||||
- Add `FramesCommand` with `action: 'list' | 'switch'`, optional `selector` or `index`
|
||||
- Use `page.frames()` to list, `frame.locator()` to switch context
|
||||
- Track current frame for subsequent commands
|
||||
|
||||
#### Step 6.4: Add Dialog Command
|
||||
- **Objective**: Handle alert/confirm/prompt dialogs
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/server.ts`, `src/index.ts`
|
||||
- **Dependencies**: None
|
||||
- **Implementation**:
|
||||
- Add `DialogCommand` with `action: 'accept' | 'dismiss'`, optional `text` for prompt
|
||||
- Set up `page.on('dialog')` handler
|
||||
- Queue dialogs and respond based on command
|
||||
|
||||
#### Step 6.5: Add Upload Command
|
||||
- **Objective**: Fill file input elements
|
||||
- **Files**: `src/types.ts`, `src/browser.ts`, `src/server.ts`, `src/index.ts`
|
||||
- **Dependencies**: None
|
||||
- **Implementation**:
|
||||
- Add `UploadCommand` with `selector: string`, `files: string[]`
|
||||
- Use `page.setInputFiles(selector, files)`
|
||||
- Return success with file count
|
||||
|
||||
## Phase 7: Documentation & Polish
|
||||
## Phase 9: Documentation
|
||||
|
||||
### Description
|
||||
Update documentation and CLI help text with all new commands.
|
||||
Update all documentation with new commands and examples.
|
||||
|
||||
### Steps
|
||||
|
||||
#### Step 7.1: Update README
|
||||
- **Objective**: Document all new commands with examples
|
||||
#### Step 9.1: Update README
|
||||
- **Objective**: Document all commands with examples
|
||||
- **Files**: `README.md`
|
||||
- **Dependencies**: Phases 1-6
|
||||
- **Dependencies**: Phases 1-8
|
||||
- **Implementation**:
|
||||
- Add command reference section
|
||||
- Include curl examples for each command
|
||||
- Add command reference grouped by category
|
||||
- Include curl/MCP examples
|
||||
- Document response formats
|
||||
|
||||
#### Step 7.2: Update CLAUDE.md
|
||||
#### Step 9.2: Update CLAUDE.md
|
||||
- **Objective**: Update developer documentation
|
||||
- **Files**: `CLAUDE.md`
|
||||
- **Dependencies**: Step 7.1
|
||||
- **Dependencies**: Step 9.1
|
||||
- **Implementation**:
|
||||
- Update architecture section with new command flow
|
||||
- Document internal logging format
|
||||
|
||||
#### Step 7.3: Update CLI Help
|
||||
- **Objective**: Update --help output with command list
|
||||
- **Files**: `src/cli.ts`
|
||||
- **Dependencies**: Phases 1-6
|
||||
- **Implementation**:
|
||||
- Expand server mode help section
|
||||
- Group commands by category
|
||||
- Update architecture notes
|
||||
- Document new command types
|
||||
|
||||
Reference in New Issue
Block a user