zhongwei/gh-ulasbilgen-mcp-skills-plugins-chrome-devtools-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:03:44 +08:00
commit 51eac46940
41 changed files with 5371 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

310
skills/mcp-chrome-devtools/workflows/element-interaction.md Normal file
View File

@@ -0,0 +1,310 @@
# Element Interaction Workflows
User input simulation for clicking, typing, form filling, and drag & drop operations.
## Tools in This Group
### click
Clicks on an element identified by its UID.
**Required:** `--uid UID`
**Optional:** `--dblClick [true|false]`
```bash
# Single click
node scripts/click.js --uid button_submit_abc123
# Double click
node scripts/click.js --uid file_icon_xyz789 --dblClick true
```
### fill
Types text into inputs, textareas, or selects options in dropdown menus.
**Required:** `--uid UID --value VALUE`
```bash
# Fill text input
node scripts/fill.js --uid input_username_abc --value john.doe
# Fill textarea
node scripts/fill.js --uid textarea_comment_def --value "This is a comment"
# Select dropdown option
node scripts/fill.js --uid select_country_ghi --value "United States"
```
### fill_form
Fills multiple form fields at once using a JSON array.
**Required:** `--elements JSON_ARRAY`
```bash
node scripts/fill_form.js --elements '[{"uid":"input_email","value":"test@example.com"},{"uid":"input_password","value":"secret123"}]'
```
### hover
Hovers the mouse over an element.
**Required:** `--uid UID`
```bash
node scripts/hover.js --uid tooltip_trigger_abc
```
### drag
Drags one element onto another element.
**Required:** `--from-uid FROM_UID --to-uid TO_UID`
```bash
node scripts/drag.js --from-uid draggable_item_abc --to-uid dropzone_xyz
```
### upload_file
Uploads a file through a file input element.
**Required:** `--uid UID --filePath FILEPATH`
```bash
node scripts/upload_file.js --uid input_file_upload --filePath /Users/username/documents/resume.pdf
```
### press_key
Presses a key or key combination (for keyboard shortcuts, navigation, special keys).
**Required:** `--key KEY`
```bash
# Single key
node scripts/press_key.js --key Enter
# Key combination
node scripts/press_key.js --key "Control+S"
# Navigation
node scripts/press_key.js --key ArrowDown
```
## Workflows
### Workflow: Login Form Automation
Complete login process with validation:
- [ ] Open login page: `node scripts/new_page.js --url https://example.com/login`
- [ ] Wait for form: `node scripts/wait_for.js --text "Sign In" --timeout 5000`
- [ ] Get element UIDs: `node scripts/take_snapshot.js`
- [ ] Fill username: `node scripts/fill.js --uid input_username_a1b2 --value testuser`
- [ ] Fill password: `node scripts/fill.js --uid input_password_c3d4 --value mypassword123`
- [ ] Submit form: `node scripts/click.js --uid button_submit_e5f6`
- [ ] Wait for redirect: `node scripts/wait_for.js --text "Dashboard" --timeout 10000`
- [ ] Verify login: `node scripts/take_screenshot.js --filePath logged_in.png`
**Input Example:**
```
Username field UID: input_username_a1b2
Password field UID: input_password_c3d4
Submit button UID: button_submit_e5f6
```
**Expected Output:**
User logged in successfully, redirected to dashboard.
### Workflow: Multi-Field Form with Dropdowns
Fill complex form with various input types:
- [ ] Navigate to form: `node scripts/new_page.js --url https://example.com/signup`
- [ ] Get structure: `node scripts/take_snapshot.js`
- [ ] Fill first name: `node scripts/fill.js --uid input_firstname --value John`
- [ ] Fill last name: `node scripts/fill.js --uid input_lastname --value Doe`
- [ ] Fill email: `node scripts/fill.js --uid input_email --value john.doe@example.com`
- [ ] Select country: `node scripts/fill.js --uid select_country --value "United States"`
- [ ] Select state: `node scripts/fill.js --uid select_state --value California`
- [ ] Fill textarea: `node scripts/fill.js --uid textarea_bio --value "Software engineer with 5 years experience"`
- [ ] Submit: `node scripts/click.js --uid button_register`
- [ ] Verify: `node scripts/wait_for.js --text "Registration successful" --timeout 10000`
**Expected Output:**
All form fields filled correctly, registration completed.
### Workflow: Bulk Form Filling
Use fill_form for efficient multi-field updates:
- [ ] Open form: `node scripts/new_page.js --url https://example.com/profile`
- [ ] Identify UIDs: `node scripts/take_snapshot.js`
- [ ] Fill all fields at once:
```bash
node scripts/fill_form.js --elements '[
{"uid":"input_name","value":"John Doe"},
{"uid":"input_email","value":"john@example.com"},
{"uid":"input_phone","value":"555-1234"},
{"uid":"select_timezone","value":"America/Los_Angeles"}
]'
```
- [ ] Review changes: `node scripts/take_snapshot.js`
- [ ] Save: `node scripts/click.js --uid button_save`
- [ ] Verify: `node scripts/wait_for.js --text "Profile updated" --timeout 5000`
**Expected Output:**
All fields updated in single operation, profile saved successfully.
### Workflow: File Upload with Validation
Upload a file and verify success:
- [ ] Navigate to upload page: `node scripts/new_page.js --url https://example.com/upload`
- [ ] Get file input UID: `node scripts/take_snapshot.js`
- [ ] Select file: `node scripts/upload_file.js --uid input_file_abc123 --filePath /Users/username/documents/report.pdf`
- [ ] Wait for preview: `node scripts/wait_for.js --text "report.pdf" --timeout 5000`
- [ ] Verify file name appears: `node scripts/take_snapshot.js`
- [ ] Click upload button: `node scripts/click.js --uid button_upload_xyz`
- [ ] Wait for completion: `node scripts/wait_for.js --text "Upload successful" --timeout 30000`
- [ ] Capture confirmation: `node scripts/take_screenshot.js --filePath upload_complete.png`
**Input Example:**
File path: `/Users/username/documents/report.pdf`
File input UID: `input_file_abc123`
**Expected Output:**
File uploaded successfully, confirmation message displayed.
### Workflow: Drag and Drop Interface
Interact with drag-and-drop components:
- [ ] Open drag interface: `node scripts/new_page.js --url https://example.com/kanban`
- [ ] Get board structure: `node scripts/take_snapshot.js`
- [ ] Drag task 1: `node scripts/drag.js --from-uid task_item_1 --to-uid column_in_progress`
- [ ] Wait for update: `node scripts/wait_for.js --text "Task moved" --timeout 3000`
- [ ] Drag task 2: `node scripts/drag.js --from-uid task_item_2 --to-uid column_done`
- [ ] Verify final state: `node scripts/take_snapshot.js`
- [ ] Save changes: `node scripts/click.js --uid button_save_board`
**Expected Output:**
Tasks moved between columns, board state updated and saved.
### Workflow: Keyboard Navigation
Use keyboard shortcuts and navigation keys:
- [ ] Open page: `node scripts/new_page.js --url https://example.com/editor`
- [ ] Focus text area: `node scripts/click.js --uid textarea_editor_abc`
- [ ] Type content: `node scripts/fill.js --uid textarea_editor_abc --value "Hello world"`
- [ ] Select all: `node scripts/press_key.js --key "Control+A"`
- [ ] Copy: `node scripts/press_key.js --key "Control+C"`
- [ ] Navigate down: `node scripts/press_key.js --key ArrowDown`
- [ ] Paste: `node scripts/press_key.js --key "Control+V"`
- [ ] Save: `node scripts/press_key.js --key "Control+S"`
- [ ] Verify save: `node scripts/wait_for.js --text "Saved" --timeout 5000`
**Expected Output:**
Keyboard shortcuts execute correctly, content manipulated and saved.
### Workflow: Hover Tooltips and Menus
Interact with hover-triggered UI elements:
- [ ] Open page: `node scripts/new_page.js --url https://example.com/dashboard`
- [ ] Get elements: `node scripts/take_snapshot.js`
- [ ] Hover over help icon: `node scripts/hover.js --uid icon_help_abc`
- [ ] Wait for tooltip: `node scripts/wait_for.js --text "Click for help" --timeout 2000`
- [ ] Capture tooltip: `node scripts/take_screenshot.js --filePath tooltip.png`
- [ ] Hover over menu: `node scripts/hover.js --uid menu_trigger_xyz`
- [ ] Wait for dropdown: `node scripts/wait_for.js --text "Settings" --timeout 2000`
- [ ] Click menu item: `node scripts/click.js --uid menu_item_settings`
**Expected Output:**
Tooltips and dropdowns appear on hover, menu items clickable.
## Common Patterns
### Pattern: Always Snapshot Before Interaction
Get fresh UIDs for every interaction:
```bash
# 1. Navigate to page
node scripts/new_page.js --url https://example.com/form
# 2. Wait for page load
node scripts/wait_for.js --text "Submit" --timeout 5000
# 3. Get current element UIDs
node scripts/take_snapshot.js
# 4. Use UIDs from snapshot output
node scripts/fill.js --uid <uid-from-snapshot> --value "data"
```
### Pattern: Form Validation Handling
Handle form validation errors:
```bash
# 1. Fill form
node scripts/fill.js --uid input_email --value "invalid-email"
# 2. Submit
node scripts/click.js --uid button_submit
# 3. Check for error message
node scripts/wait_for.js --text "Invalid email" --timeout 3000
# 4. Correct the input
node scripts/fill.js --uid input_email --value "valid@example.com"
# 5. Resubmit
node scripts/click.js --uid button_submit
```
### Pattern: Wait After Each Interaction
Ensure UI updates before next action:
```bash
# 1. Click button
node scripts/click.js --uid button_load_more
# 2. Wait for new content
node scripts/wait_for.js --text "Showing 20 items" --timeout 5000
# 3. Now interact with new elements
node scripts/take_snapshot.js
```
## Troubleshooting
**Problem:** Element UID not found
**Solution:** UIDs are dynamic. Always take a fresh snapshot before interaction. Don't reuse old UIDs.
**Problem:** Click doesn't trigger action
**Solution:**
- Ensure element is visible and clickable (not hidden)
- Try waiting for page to fully load first with `wait_for.js`
- Check if element requires hover first: use `hover.js` then `click.js`
**Problem:** Fill doesn't work on input
**Solution:**
- Verify the element is an input/textarea/select
- For some custom components, use `click.js` to focus, then `press_key.js` to type
- Check if page has JavaScript that prevents fill
**Problem:** File upload fails
**Solution:**
- Use absolute file paths (not relative)
- Verify file exists at the specified path
- Use forward slashes in paths: `/Users/username/file.pdf`
**Problem:** Drag and drop doesn't work
**Solution:**
- Ensure both UIDs are valid and current
- Some drag implementations require specific timing - add `wait_for.js` between actions
- Verify dropzone accepts the dragged element type

326
skills/mcp-chrome-devtools/workflows/inspection-debugging.md Normal file
View File

@@ -0,0 +1,326 @@
# Inspection & Debugging Workflows
Monitor and debug web applications using snapshots, screenshots, console logs, and network requests.
## Tools in This Group
### take_snapshot
Captures text-based page structure from the accessibility tree with element UIDs.
**Optional:** `--verbose [true|false]`, `--filePath FILEPATH`
```bash
# Console output
node scripts/take_snapshot.js
# Verbose mode (more details)
node scripts/take_snapshot.js --verbose true
# Save to file
node scripts/take_snapshot.js --filePath snapshot.txt
```
**Output Example:**
```
Page: https://example.com
Title: Example Domain
button "Submit" [uid: button_submit_abc123]
input "Email" [uid: input_email_def456]
link "About" [uid: link_about_ghi789]
```
### take_screenshot
Captures visual screenshot of the page or specific element.
**Optional:** `--format [png|jpeg]`, `--quality 0-100`, `--uid UID`, `--fullPage [true|false]`, `--filePath FILEPATH`
```bash
# Full page screenshot
node scripts/take_screenshot.js --format png --fullPage true --filePath page.png
# Element screenshot
node scripts/take_screenshot.js --uid element_abc123 --filePath element.png
# Compressed JPEG
node scripts/take_screenshot.js --format jpeg --quality 80 --filePath page.jpg
```
### list_console_messages
Lists console logs, warnings, and errors from the current page.
**Optional:** `--pageSize SIZE`, `--pageIdx INDEX`, `--types [log,warn,error,info]`, `--includePreservedMessages [true|false]`
```bash
# All messages
node scripts/list_console_messages.js
# Only errors
node scripts/list_console_messages.js --types error
# Paginated results
node scripts/list_console_messages.js --pageSize 10 --pageIdx 0
```
### get_console_message
Retrieves a specific console message by ID.
**Required:** `--msgid MESSAGE_ID`
```bash
node scripts/get_console_message.js --msgid msg_abc123
```
### list_network_requests
Lists network requests made by the current page.
**Optional:** `--pageSize SIZE`, `--pageIdx INDEX`, `--resourceTypes [fetch,xhr,document,script,stylesheet]`, `--includePreservedRequests [true|false]`
```bash
# All requests
node scripts/list_network_requests.js
# Only API calls
node scripts/list_network_requests.js --resourceTypes fetch,xhr
# Paginated results
node scripts/list_network_requests.js --pageSize 20 --pageIdx 0
```
### get_network_request
Retrieves details of a specific network request.
**Optional:** `--reqid REQUEST_ID`
```bash
# Get specific request
node scripts/get_network_request.js --reqid req_abc123
# Get currently selected request in DevTools
node scripts/get_network_request.js
```
## Workflows
### Workflow: Debug JavaScript Errors
Identify and analyze console errors:
- [ ] Open page: `node scripts/new_page.js --url https://example.com/app`
- [ ] Wait for page load: `node scripts/wait_for.js --text "Welcome" --timeout 10000`
- [ ] List all console messages: `node scripts/list_console_messages.js`
- [ ] Filter errors only: `node scripts/list_console_messages.js --types error`
- [ ] Get specific error details: `node scripts/get_console_message.js --msgid <error-id-from-list>`
- [ ] Take screenshot of error state: `node scripts/take_screenshot.js --filePath error_state.png`
- [ ] Take snapshot for context: `node scripts/take_snapshot.js --filePath error_snapshot.txt`
**Expected Output:**
Console errors identified, stack traces captured, visual state documented.
### Workflow: Monitor API Calls
Track network requests and responses:
- [ ] Open application: `node scripts/new_page.js --url https://example.com/dashboard`
- [ ] Trigger data load: `node scripts/click.js --uid button_load_data`
- [ ] Wait for request: `node scripts/wait_for.js --text "Data loaded" --timeout 10000`
- [ ] List API calls: `node scripts/list_network_requests.js --resourceTypes fetch,xhr`
- [ ] Get specific request: `node scripts/get_network_request.js --reqid <request-id>`
- [ ] Verify response data in output
- [ ] Save network log: `node scripts/list_network_requests.js > network_log.txt`
**Expected Output:**
All API calls logged, request/response details captured, timing information available.
### Workflow: Visual Regression Testing
Capture screenshots for comparison:
- [ ] Open baseline page: `node scripts/new_page.js --url https://example.com/page`
- [ ] Wait for load: `node scripts/wait_for.js --text "Content loaded" --timeout 5000`
- [ ] Capture full page: `node scripts/take_screenshot.js --fullPage true --filePath baseline.png`
- [ ] Capture header: `node scripts/take_screenshot.js --uid header_main --filePath header.png`
- [ ] Capture footer: `node scripts/take_screenshot.js --uid footer_main --filePath footer.png`
- [ ] Navigate to variant: `node scripts/navigate_page.js --url https://example.com/page?variant=b`
- [ ] Wait for load: `node scripts/wait_for.js --text "Content loaded" --timeout 5000`
- [ ] Capture variant: `node scripts/take_screenshot.js --fullPage true --filePath variant.png`
**Expected Output:**
Screenshots captured for visual comparison, specific components isolated.
### Workflow: Form Submission Debugging
Debug form submission issues:
- [ ] Open form: `node scripts/new_page.js --url https://example.com/contact`
- [ ] Initial snapshot: `node scripts/take_snapshot.js`
- [ ] Fill form fields: `node scripts/fill.js --uid input_name --value "Test User"`
- [ ] Continue filling: `node scripts/fill.js --uid input_email --value "test@example.com"`
- [ ] Submit form: `node scripts/click.js --uid button_submit`
- [ ] Monitor console: `node scripts/list_console_messages.js --types error,warn`
- [ ] Monitor network: `node scripts/list_network_requests.js --resourceTypes fetch,xhr`
- [ ] Get POST request: `node scripts/get_network_request.js --reqid <post-request-id>`
- [ ] Check response: Verify status code and response body in output
- [ ] Take error screenshot: `node scripts/take_screenshot.js --filePath form_error.png`
**Expected Output:**
Form submission tracked, network call details captured, errors identified.
### Workflow: Content Extraction
Extract page content and structure:
- [ ] Navigate to page: `node scripts/new_page.js --url https://example.com/article`
- [ ] Wait for content: `node scripts/wait_for.js --text "Published" --timeout 5000`
- [ ] Take detailed snapshot: `node scripts/take_snapshot.js --verbose true --filePath article_structure.txt`
- [ ] Extract main content: `node scripts/evaluate_script.js --function "() => document.querySelector('article').textContent"`
- [ ] Extract metadata: `node scripts/evaluate_script.js --function "() => ({title: document.title, author: document.querySelector('.author').textContent})"`
- [ ] Screenshot article: `node scripts/take_screenshot.js --uid article_main --filePath article.png`
- [ ] List external resources: `node scripts/list_network_requests.js --resourceTypes script,stylesheet,image`
**Expected Output:**
Page structure documented, content extracted, external dependencies identified.
### Workflow: Performance Monitoring
Monitor page performance and resource loading:
- [ ] Open page: `node scripts/new_page.js --url https://example.com/heavy-page`
- [ ] Wait for interactive: `node scripts/wait_for.js --text "Loaded" --timeout 30000`
- [ ] List all requests: `node scripts/list_network_requests.js`
- [ ] Identify slow requests: Review timing in network list output
- [ ] Get slow request details: `node scripts/get_network_request.js --reqid <slow-request-id>`
- [ ] Check console warnings: `node scripts/list_console_messages.js --types warn`
- [ ] Take final screenshot: `node scripts/take_screenshot.js --filePath loaded_state.png`
**Expected Output:**
Resource loading times captured, slow requests identified, console warnings logged.
### Workflow: Multi-Step User Flow Debugging
Debug complex user interactions:
- [ ] Start flow: `node scripts/new_page.js --url https://example.com/checkout`
- [ ] **Step 1: Cart**
- [ ] Snapshot: `node scripts/take_snapshot.js --filePath step1_snapshot.txt`
- [ ] Screenshot: `node scripts/take_screenshot.js --filePath step1_cart.png`
- [ ] Console: `node scripts/list_console_messages.js > step1_console.txt`
- [ ] Network: `node scripts/list_network_requests.js > step1_network.txt`
- [ ] Next: `node scripts/click.js --uid button_checkout`
- [ ] **Step 2: Shipping**
- [ ] Wait: `node scripts/wait_for.js --text "Shipping Information" --timeout 5000`
- [ ] Snapshot: `node scripts/take_snapshot.js --filePath step2_snapshot.txt`
- [ ] Screenshot: `node scripts/take_screenshot.js --filePath step2_shipping.png`
- [ ] Fill: `node scripts/fill_form.js --elements '[{"uid":"input_address","value":"123 Main St"}]'`
- [ ] Next: `node scripts/click.js --uid button_continue`
- [ ] **Step 3: Payment**
- [ ] Wait: `node scripts/wait_for.js --text "Payment Method" --timeout 5000`
- [ ] Snapshot: `node scripts/take_snapshot.js --filePath step3_snapshot.txt`
- [ ] Console errors: `node scripts/list_console_messages.js --types error`
- [ ] Network calls: `node scripts/list_network_requests.js --resourceTypes fetch,xhr`
**Expected Output:**
Full debugging trace of multi-step flow, each step documented with snapshot/screenshot/logs.
## Common Patterns
### Pattern: Snapshot First, Then Screenshot
Use snapshot for UIDs and structure, screenshot for visual verification:
```bash
# 1. Get structure and UIDs
node scripts/take_snapshot.js --filePath structure.txt
# 2. Get visual representation
node scripts/take_screenshot.js --filePath visual.png
# 3. Use UIDs from snapshot for interaction
node scripts/click.js --uid <uid-from-snapshot>
```
### Pattern: Filter Console by Type
Focus on specific message types:
```bash
# Errors only (most critical)
node scripts/list_console_messages.js --types error
# Errors and warnings
node scripts/list_console_messages.js --types error,warn
# Everything
node scripts/list_console_messages.js
```
### Pattern: Track API Call Sequence
Monitor API calls in order:
```bash
# 1. Before action
node scripts/list_network_requests.js > before.txt
# 2. Trigger action
node scripts/click.js --uid button_submit
# 3. After action
node scripts/list_network_requests.js > after.txt
# 4. Compare to see new requests
# (manually diff before.txt and after.txt)
```
### Pattern: Element-Specific Screenshot
Capture specific UI components:
```bash
# 1. Get element UID
node scripts/take_snapshot.js
# 2. Screenshot just that element
node scripts/take_screenshot.js --uid <element-uid> --filePath component.png
```
## Troubleshooting
**Problem:** Snapshot shows different UIDs each time
**Solution:** This is expected. UIDs are regenerated on each snapshot. Always use the most recent snapshot before interaction.
**Problem:** Screenshot is blank or black
**Solution:**
- Wait for page to fully load with `wait_for.js`
- Check if element is visible (not hidden or off-screen)
- Try full page screenshot first: `--fullPage true`
**Problem:** Console messages not showing up
**Solution:**
- Messages accumulate since last navigation
- Reload page if you need to clear: `navigate_page.js --type reload`
- Use `--includePreservedMessages true` to see older messages
**Problem:** Network requests list is empty
**Solution:**
- Requests are captured from current navigation onwards
- Navigate to page after opening it to capture requests
- Use `--includePreservedRequests true` to see older requests
**Problem:** Cannot find specific console message ID
**Solution:**
- Run `list_console_messages.js` first to get message IDs
- Message IDs are shown in the list output
- Use the exact ID from the list in `get_console_message.js`
**Problem:** Screenshot file path error
**Solution:**
- Use absolute paths: `/Users/username/screenshots/image.png`
- Use forward slashes (not backslashes)
- Ensure directory exists before saving

218
skills/mcp-chrome-devtools/workflows/page-management.md Normal file
View File

@@ -0,0 +1,218 @@
# Page Management Workflows
Browser window and tab operations for managing multiple pages and navigation.
## Tools in This Group
### new_page
Creates a new browser page (tab).
**Required:** `--url URL`
**Optional:** `--timeout MILLISECONDS`
```bash
node scripts/new_page.js --url https://example.com --timeout 30000
```
### list_pages
Lists all open pages with their indices and URLs.
```bash
node scripts/list_pages.js
```
**Output Example:**
```
Page 0: https://example.com (selected)
Page 1: https://google.com
Page 2: https://github.com
```
### select_page
Switches the active context to a specific page by index.
**Required:** `--pageIdx INDEX`
```bash
node scripts/select_page.js --pageIdx 1
```
### navigate_page
Navigates the currently selected page to a new URL.
**Optional:** `--url URL`, `--type [navigate|reload|back|forward]`, `--ignoreCache [true|false]`, `--timeout MILLISECONDS`
```bash
# Navigate to URL
node scripts/navigate_page.js --url https://example.com/page2
# Reload page
node scripts/navigate_page.js --type reload --ignoreCache true
# Go back
node scripts/navigate_page.js --type back
```
### resize_page
Resizes the browser window to specific dimensions.
**Required:** `--width WIDTH --height HEIGHT`
```bash
node scripts/resize_page.js --width 1920 --height 1080
```
### close_page
Closes a page by its index. Cannot close the last remaining page.
**Required:** `--pageIdx INDEX`
```bash
node scripts/close_page.js --pageIdx 2
```
## Workflows
### Workflow: Open Multiple Research Tabs
Open several pages for research or comparison:
- [ ] List current pages: `node scripts/list_pages.js`
- [ ] Open first article: `node scripts/new_page.js --url https://example.com/article1`
- [ ] Open second article: `node scripts/new_page.js --url https://example.com/article2`
- [ ] Open third article: `node scripts/new_page.js --url https://example.com/article3`
- [ ] Verify all open: `node scripts/list_pages.js`
**Expected Output:**
Multiple tabs open, each with different content, ready for analysis.
### Workflow: Navigate Through Site Pages
Walk through a multi-page flow:
- [ ] Start at homepage: `node scripts/new_page.js --url https://example.com`
- [ ] Take initial snapshot: `node scripts/take_snapshot.js`
- [ ] Click "About" link: `node scripts/click.js --uid link_about_xyz`
- [ ] Wait for page load: `node scripts/wait_for.js --text "About Us" --timeout 5000`
- [ ] Go back: `node scripts/navigate_page.js --type back`
- [ ] Verify homepage: `node scripts/wait_for.js --text "Welcome" --timeout 5000`
- [ ] Go forward: `node scripts/navigate_page.js --type forward`
**Expected Output:**
Browser navigates through pages, back/forward works correctly.
### Workflow: Multi-Tab Data Extraction
Extract data from multiple pages simultaneously:
- [ ] Open page 1: `node scripts/new_page.js --url https://example.com/data/item1`
- [ ] Take snapshot 1: `node scripts/take_snapshot.js --filePath item1.txt`
- [ ] Open page 2: `node scripts/new_page.js --url https://example.com/data/item2`
- [ ] Take snapshot 2: `node scripts/take_snapshot.js --filePath item2.txt`
- [ ] Open page 3: `node scripts/new_page.js --url https://example.com/data/item3`
- [ ] Take snapshot 3: `node scripts/take_snapshot.js --filePath item3.txt`
- [ ] Switch to page 0: `node scripts/select_page.js --pageIdx 0`
- [ ] Extract from page 0: `node scripts/evaluate_script.js --function "() => document.querySelector('.price').textContent"`
- [ ] Switch to page 1: `node scripts/select_page.js --pageIdx 1`
- [ ] Extract from page 1: `node scripts/evaluate_script.js --function "() => document.querySelector('.price').textContent"`
**Expected Output:**
Data extracted from multiple pages, context switching successful.
### Workflow: Responsive Design Testing
Test page at different viewport sizes:
- [ ] Open test page: `node scripts/new_page.js --url https://example.com`
- [ ] Desktop view: `node scripts/resize_page.js --width 1920 --height 1080`
- [ ] Take desktop screenshot: `node scripts/take_screenshot.js --fullPage true --filePath desktop.png`
- [ ] Tablet view: `node scripts/resize_page.js --width 768 --height 1024`
- [ ] Take tablet screenshot: `node scripts/take_screenshot.js --fullPage true --filePath tablet.png`
- [ ] Mobile view: `node scripts/resize_page.js --width 375 --height 667`
- [ ] Take mobile screenshot: `node scripts/take_screenshot.js --fullPage true --filePath mobile.png`
**Expected Output:**
Screenshots captured at different viewport sizes for comparison.
### Workflow: Clean Up Tabs
Close unnecessary tabs while keeping important ones:
- [ ] List all pages: `node scripts/list_pages.js`
- [ ] Identify indices to close (e.g., pages 2, 3, 4)
- [ ] Close page 4: `node scripts/close_page.js --pageIdx 4`
- [ ] Close page 3: `node scripts/close_page.js --pageIdx 3`
- [ ] Close page 2: `node scripts/close_page.js --pageIdx 2`
- [ ] Verify remaining: `node scripts/list_pages.js`
- [ ] Switch to desired page: `node scripts/select_page.js --pageIdx 0`
**Note:** Close tabs in reverse order (highest index first) to avoid index shifting issues.
**Expected Output:**
Unwanted tabs closed, important tabs remain active.
## Common Patterns
### Pattern: Safe Page Closing
Always list pages before closing to avoid errors:
```bash
# 1. Check what's open
node scripts/list_pages.js
# 2. Close specific page (use actual index from list)
node scripts/close_page.js --pageIdx 2
# 3. Verify closure
node scripts/list_pages.js
```
### Pattern: Page Context Switching
When working with multiple pages, always select before interacting:
```bash
# 1. List to see indices
node scripts/list_pages.js
# 2. Select target page
node scripts/select_page.js --pageIdx 1
# 3. Now interact with that page
node scripts/take_snapshot.js
node scripts/click.js --uid button_xyz
```
### Pattern: Reliable Navigation
Use wait_for to ensure page loads before interaction:
```bash
# 1. Navigate
node scripts/navigate_page.js --url https://example.com/login
# 2. Wait for key element
node scripts/wait_for.js --text "Sign In" --timeout 10000
# 3. Now safe to interact
node scripts/take_snapshot.js
```
## Troubleshooting
**Problem:** "Cannot close last page" error
**Solution:** You must keep at least one page open. Open a new page before closing the last one.
**Problem:** Page index out of range
**Solution:** Always run `list_pages.js` first to see current indices. Indices shift when pages are closed.
**Problem:** Navigation timeout
**Solution:** Increase timeout value: `--timeout 60000` (60 seconds) for slow-loading pages.
**Problem:** Wrong page context
**Solution:** Use `list_pages.js` to check which page is selected (marked with "selected"). Use `select_page.js` to switch.

383
skills/mcp-chrome-devtools/workflows/performance-analysis.md Normal file
View File

@@ -0,0 +1,383 @@
# Performance Analysis Workflows
Advanced tools for JavaScript execution, performance tracing, device emulation, and automation utilities.
## Tools in This Group
### evaluate_script
Executes JavaScript code in the page context and returns JSON-serializable results.
**Required:** `--function FUNCTION_STRING`
**Optional:** `--args JSON_ARRAY`
```bash
# Simple extraction
node scripts/evaluate_script.js --function "() => document.title"
# With parameters
node scripts/evaluate_script.js --function "(x, y) => x + y" --args '[5, 3]'
# Complex extraction
node scripts/evaluate_script.js --function "() => Array.from(document.querySelectorAll('h2')).map(h => h.textContent)"
```
### wait_for
Waits for specific text to appear on the page (for dynamic content loading).
**Required:** `--text TEXT`
**Optional:** `--timeout MILLISECONDS`
```bash
# Wait up to 10 seconds
node scripts/wait_for.js --text "Loading complete" --timeout 10000
# Wait for error message
node scripts/wait_for.js --text "Error" --timeout 5000
```
### handle_dialog
Handles browser dialogs (alert, confirm, prompt).
**Required:** `--action [accept|dismiss]`
**Optional:** `--promptText TEXT`
```bash
# Accept alert
node scripts/handle_dialog.js --action accept
# Dismiss confirm
node scripts/handle_dialog.js --action dismiss
# Accept prompt with text
node scripts/handle_dialog.js --action accept --promptText "User input"
```
### emulate
Emulates network conditions and CPU throttling.
**Optional:** `--networkConditions JSON`, `--cpuThrottlingRate NUMBER`
```bash
# Slow 3G network
node scripts/emulate.js --networkConditions '{"downloadThroughput":50000,"uploadThroughput":50000,"latency":2000}'
# 4x CPU throttling
node scripts/emulate.js --cpuThrottlingRate 4
# Both
node scripts/emulate.js --networkConditions '{"downloadThroughput":100000,"uploadThroughput":50000,"latency":100}' --cpuThrottlingRate 2
```
### performance_start_trace
Starts recording performance trace for Core Web Vitals and performance insights.
**Required:** `--reload [true|false]`, `--autoStop [true|false]`
```bash
# Start tracing with page reload
node scripts/performance_start_trace.js --reload true --autoStop false
# Start tracing without reload
node scripts/performance_start_trace.js --reload false --autoStop true
```
### performance_stop_trace
Stops the active performance trace and returns results.
```bash
node scripts/performance_stop_trace.js
```
**Output includes:**
- Core Web Vitals: LCP, FID, CLS scores
- Performance insights and recommendations
- Insight set IDs for detailed analysis
### performance_analyze_insight
Gets detailed information about a specific performance insight.
**Required:** `--insightSetId SET_ID`, `--insightName INSIGHT_NAME`
```bash
node scripts/performance_analyze_insight.js --insightSetId set_abc123 --insightName LargestContentfulPaint
```
## Workflows
### Workflow: Extract Structured Data
Scrape data from pages using JavaScript:
- [ ] Open page: `node scripts/new_page.js --url https://example.com/products`
- [ ] Wait for load: `node scripts/wait_for.js --text "Products" --timeout 10000`
- [ ] Extract product titles:
```bash
node scripts/evaluate_script.js --function "() => Array.from(document.querySelectorAll('.product-title')).map(el => el.textContent)"
```
- [ ] Extract product prices:
```bash
node scripts/evaluate_script.js --function "() => Array.from(document.querySelectorAll('.product-price')).map(el => el.textContent)"
```
- [ ] Extract complete product data:
```bash
node scripts/evaluate_script.js --function "() => Array.from(document.querySelectorAll('.product')).map(p => ({title: p.querySelector('.title').textContent, price: p.querySelector('.price').textContent, id: p.dataset.id}))"
```
**Expected Output:**
Structured JSON data extracted from page, ready for processing.
### Workflow: Comprehensive Performance Analysis
Measure page performance and Core Web Vitals:
- [ ] Open page: `node scripts/new_page.js --url https://example.com/landing`
- [ ] Start trace with reload: `node scripts/performance_start_trace.js --reload true --autoStop false`
- [ ] Wait for page load: `node scripts/wait_for.js --text "Get Started" --timeout 20000`
- [ ] Interact with page: `node scripts/click.js --uid button_cta`
- [ ] Wait for interaction: `node scripts/wait_for.js --text "Form" --timeout 5000`
- [ ] Stop trace: `node scripts/performance_stop_trace.js`
- [ ] Review output for:
- LCP (Largest Contentful Paint) - should be < 2.5s
- FID (First Input Delay) - should be < 100ms
- CLS (Cumulative Layout Shift) - should be < 0.1
- Performance insights list
- [ ] Analyze specific insight: `node scripts/performance_analyze_insight.js --insightSetId <set-id> --insightName LargestContentfulPaint`
**Expected Output:**
Full performance profile, CWV scores, actionable insights for optimization.
### Workflow: Test Under Network Constraints
Simulate slow connections:
- [ ] Set up slow 3G: `node scripts/emulate.js --networkConditions '{"downloadThroughput":50000,"uploadThroughput":50000,"latency":2000}'`
- [ ] Open page: `node scripts/new_page.js --url https://example.com --timeout 60000`
- [ ] Start performance trace: `node scripts/performance_start_trace.js --reload true --autoStop false`
- [ ] Wait for load: `node scripts/wait_for.js --text "Content" --timeout 60000`
- [ ] Stop trace: `node scripts/performance_stop_trace.js`
- [ ] Review load times: Check trace output for timing metrics
- [ ] Screenshot loaded state: `node scripts/take_screenshot.js --filePath slow_3g_loaded.png`
- [ ] Reset to fast network: `node scripts/emulate.js --networkConditions '{"downloadThroughput":10000000,"uploadThroughput":10000000,"latency":10}'`
**Expected Output:**
Page behavior under slow network documented, performance impact measured.
### Workflow: CPU Throttling Test
Test performance on low-powered devices:
- [ ] Apply 4x throttling: `node scripts/emulate.js --cpuThrottlingRate 4`
- [ ] Open app: `node scripts/new_page.js --url https://example.com/app`
- [ ] Start trace: `node scripts/performance_start_trace.js --reload true --autoStop false`
- [ ] Interact with heavy UI: `node scripts/click.js --uid button_render_chart`
- [ ] Wait for render: `node scripts/wait_for.js --text "Chart loaded" --timeout 30000`
- [ ] Stop trace: `node scripts/performance_stop_trace.js`
- [ ] Check JavaScript execution time in trace output
- [ ] Remove throttling: `node scripts/emulate.js --cpuThrottlingRate 1`
- [ ] Repeat test for comparison
**Expected Output:**
Performance comparison between throttled and normal CPU, bottlenecks identified.
### Workflow: Handle Dynamic Content Loading
Work with lazy-loaded content:
- [ ] Open page: `node scripts/new_page.js --url https://example.com/infinite-scroll`
- [ ] Wait for initial load: `node scripts/wait_for.js --text "Item 1" --timeout 5000`
- [ ] Scroll to bottom: `node scripts/evaluate_script.js --function "() => window.scrollTo(0, document.body.scrollHeight)"`
- [ ] Wait for more items: `node scripts/wait_for.js --text "Item 20" --timeout 10000`
- [ ] Take snapshot: `node scripts/take_snapshot.js`
- [ ] Scroll again: `node scripts/evaluate_script.js --function "() => window.scrollTo(0, document.body.scrollHeight)"`
- [ ] Wait for more: `node scripts/wait_for.js --text "Item 40" --timeout 10000`
- [ ] Extract all items:
```bash
node scripts/evaluate_script.js --function "() => Array.from(document.querySelectorAll('.item')).length"
```
**Expected Output:**
All lazy-loaded content triggered and captured, full list extracted.
### Workflow: Automated Dialog Handling
Automate flows with browser dialogs:
- [ ] Open page: `node scripts/new_page.js --url https://example.com/confirm-action`
- [ ] Click delete button: `node scripts/click.js --uid button_delete`
- [ ] Handle confirm dialog: `node scripts/handle_dialog.js --action accept`
- [ ] Wait for deletion: `node scripts/wait_for.js --text "Deleted successfully" --timeout 5000`
- [ ] Verify: `node scripts/take_snapshot.js`
**For prompt dialog:**
```bash
# Click button that opens prompt
node scripts/click.js --uid button_rename
# Enter new name and accept
node scripts/handle_dialog.js --action accept --promptText "New Name"
# Verify change
node scripts/wait_for.js --text "New Name" --timeout 3000
```
**Expected Output:**
Browser dialogs handled automatically, flow completes without manual intervention.
### Workflow: Custom Metrics Collection
Collect custom performance metrics:
- [ ] Open page: `node scripts/new_page.js --url https://example.com/dashboard`
- [ ] Wait for load: `node scripts/wait_for.js --text "Dashboard" --timeout 10000`
- [ ] Get page load time:
```bash
node scripts/evaluate_script.js --function "() => performance.timing.loadEventEnd - performance.timing.navigationStart"
```
- [ ] Get resource count:
```bash
node scripts/evaluate_script.js --function "() => performance.getEntriesByType('resource').length"
```
- [ ] Get memory usage (if available):
```bash
node scripts/evaluate_script.js --function "() => performance.memory ? performance.memory.usedJSHeapSize : null"
```
- [ ] Get paint timings:
```bash
node scripts/evaluate_script.js --function "() => performance.getEntriesByType('paint').map(p => ({name: p.name, time: p.startTime}))"
```
**Expected Output:**
Custom performance metrics collected via Performance API, specific to your needs.
### Workflow: A/B Test Performance Comparison
Compare performance across variants:
- [ ] **Variant A:**
- [ ] Open: `node scripts/new_page.js --url https://example.com?variant=a`
- [ ] Trace: `node scripts/performance_start_trace.js --reload true --autoStop false`
- [ ] Wait: `node scripts/wait_for.js --text "Content" --timeout 15000`
- [ ] Stop: `node scripts/performance_stop_trace.js > variant_a_trace.txt`
- [ ] Screenshot: `node scripts/take_screenshot.js --filePath variant_a.png`
- [ ] **Variant B:**
- [ ] Navigate: `node scripts/navigate_page.js --url https://example.com?variant=b`
- [ ] Trace: `node scripts/performance_start_trace.js --reload true --autoStop false`
- [ ] Wait: `node scripts/wait_for.js --text "Content" --timeout 15000`
- [ ] Stop: `node scripts/performance_stop_trace.js > variant_b_trace.txt`
- [ ] Screenshot: `node scripts/take_screenshot.js --filePath variant_b.png`
- [ ] Compare CWV scores from both trace files
**Expected Output:**
Performance metrics for both variants, data-driven comparison for optimization.
## Common Patterns
### Pattern: Safe Script Evaluation
Always return JSON-serializable data:
```bash
# Good: Returns string
node scripts/evaluate_script.js --function "() => document.title"
# Good: Returns array of strings
node scripts/evaluate_script.js --function "() => Array.from(document.querySelectorAll('a')).map(a => a.href)"
# Bad: Returns DOM nodes (not serializable)
# node scripts/evaluate_script.js --function "() => document.querySelectorAll('a')"
```
### Pattern: Wait Before Interaction
Always wait for dynamic content:
```bash
# 1. Trigger action
node scripts/click.js --uid button_load
# 2. Wait for content
node scripts/wait_for.js --text "Loaded" --timeout 10000
# 3. Now safe to interact
node scripts/take_snapshot.js
```
### Pattern: Complete Performance Workflow
Standard performance analysis sequence:
```bash
# 1. Start tracing
node scripts/performance_start_trace.js --reload true --autoStop false
# 2. Let page load completely
node scripts/wait_for.js --text "Ready" --timeout 20000
# 3. Stop tracing
node scripts/performance_stop_trace.js
# 4. Analyze specific insights
node scripts/performance_analyze_insight.js --insightSetId <id> --insightName <name>
```
### Pattern: Emulation Reset
Reset emulation to normal after testing:
```bash
# 1. Test under constraints
node scripts/emulate.js --cpuThrottlingRate 4
# ... run tests ...
# 2. Reset to normal
node scripts/emulate.js --cpuThrottlingRate 1
```
## Troubleshooting
**Problem:** evaluate_script returns null or error
**Solution:**
- Ensure function returns JSON-serializable values (no DOM nodes, functions, or circular references)
- Use .map() to extract primitive values from DOM elements
- Check browser console for JavaScript errors: `list_console_messages.js --types error`
**Problem:** wait_for times out
**Solution:**
- Increase timeout: `--timeout 30000` (30 seconds)
- Verify text actually appears on page (check with `take_snapshot.js`)
- Text match is exact - check spelling and case
- Wait for network to finish if text appears after API call
**Problem:** Dialog not handled
**Solution:**
- Dialog must be already open when you call `handle_dialog.js`
- Trigger dialog first (e.g., click button), then immediately call `handle_dialog.js`
- Some "dialogs" are custom HTML, not browser dialogs - use `click.js` instead
**Problem:** Performance trace shows unexpected results
**Solution:**
- Ensure page fully loads before stopping trace
- Use `--reload true` for consistent initial page load measurement
- Clear browser cache if testing first-time load performance
- Disable browser extensions that might affect performance
**Problem:** Emulation not working
**Solution:**
- Emulation settings persist for the session
- To remove emulation, set back to normal values
- Network conditions JSON must be valid with all three properties
- CPU throttling rate of 1 = normal, higher = slower
**Problem:** Script evaluation with args fails
**Solution:**
- Args must be valid JSON array: `--args '[1, 2, 3]'`
- Function must accept the correct number of parameters
- Use single quotes around JSON, double quotes inside
- Example: `--function "(a, b) => a + b" --args '[5, 10]'`