Adam Ladachowski
5a7466b67d
📁 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
250 lines
8.4 KiB
Markdown
250 lines
8.4 KiB
Markdown
# Plan: Playwright Debugging Features
|
|
|
|
## Phase 1: Core Debugging (Console & Errors)
|
|
|
|
### Description
|
|
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 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 `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 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 `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: Network Monitoring
|
|
|
|
### Description
|
|
Implement network request/response capture for debugging API calls, identifying failed requests, and inspecting payloads.
|
|
|
|
### Steps
|
|
|
|
#### 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 `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 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
|
|
- Collect via `performance.timing` and `performance.getEntriesByType()`
|
|
- Return: domContentLoaded, load, firstPaint, firstContentfulPaint
|
|
- Include DOM stats: nodeCount, scriptCount, styleCount
|
|
|
|
#### 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
|
|
Implement accessibility tree inspection for debugging screen reader and a11y issues.
|
|
|
|
### Steps
|
|
|
|
#### 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 `A11yCommand` with optional `selector` for subtree
|
|
- Use `page.accessibility.snapshot()`
|
|
- Return tree with role, name, value, description
|
|
- Add `browser://a11y` MCP resource
|
|
|
|
## Phase 5: Dialog Handling
|
|
|
|
### Description
|
|
Implement automatic handling of browser dialogs (alert, confirm, prompt) to prevent blocking during automation.
|
|
|
|
### Steps
|
|
|
|
#### 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 `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()`
|
|
|
|
#### 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` name
|
|
- Use Playwright's device descriptors
|
|
- Apply viewport, userAgent, deviceScaleFactor, touch support
|
|
|
|
## Phase 9: Documentation
|
|
|
|
### Description
|
|
Update all documentation with new commands and examples.
|
|
|
|
### Steps
|
|
|
|
#### Step 9.1: Update README
|
|
- **Objective**: Document all commands with examples
|
|
- **Files**: `README.md`
|
|
- **Dependencies**: Phases 1-8
|
|
- **Implementation**:
|
|
- Add command reference grouped by category
|
|
- Include curl/MCP examples
|
|
- Document response formats
|
|
|
|
#### Step 9.2: Update CLAUDE.md
|
|
- **Objective**: Update developer documentation
|
|
- **Files**: `CLAUDE.md`
|
|
- **Dependencies**: Step 9.1
|
|
- **Implementation**:
|
|
- Update architecture notes
|
|
- Document new command types
|