Initial commit
This commit is contained in:
12
.claude-plugin/plugin.json
Normal file
12
.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,12 @@
|
|||||||
|
{
|
||||||
|
"name": "cc_chrome_devtools_mcp_skill",
|
||||||
|
"description": "Automated Chrome browser testing with frontend visibility. Enables Claude Code to see and fix your web applications through Chrome DevTools Protocol - performance testing, Core Web Vitals measurement, accessibility validation, network monitoring, and browser automation.",
|
||||||
|
"version": "0.0.0-2025.11.28",
|
||||||
|
"author": {
|
||||||
|
"name": "Jonathan Edwards",
|
||||||
|
"email": "jon@contentionmedia.com"
|
||||||
|
},
|
||||||
|
"skills": [
|
||||||
|
"./"
|
||||||
|
]
|
||||||
|
}
|
||||||
18
.gitignore
vendored
Normal file
18
.gitignore
vendored
Normal file
@@ -0,0 +1,18 @@
|
|||||||
|
# macOS
|
||||||
|
.DS_Store
|
||||||
|
.AppleDouble
|
||||||
|
.LSOverride
|
||||||
|
|
||||||
|
# Editor
|
||||||
|
.vscode/
|
||||||
|
.idea/
|
||||||
|
*.swp
|
||||||
|
*.swo
|
||||||
|
*~
|
||||||
|
|
||||||
|
# Logs
|
||||||
|
*.log
|
||||||
|
|
||||||
|
# Temporary files
|
||||||
|
*.tmp
|
||||||
|
.cache/
|
||||||
128
LICENSE
Normal file
128
LICENSE
Normal file
@@ -0,0 +1,128 @@
|
|||||||
|
# 📜 THE MOST PERMISSIVE LICENSE IN THE KNOWN UNIVERSE 🌌
|
||||||
|
|
||||||
|
## 🎭 MIT License (Maximum Internet Trolling Edition)
|
||||||
|
|
||||||
|
**Copyright (c) 2025 Jonathan Edwards** 👨💻✨
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎉 WHAT YOU CAN DO (Literally Everything) 🚀
|
||||||
|
|
||||||
|
Permission is hereby granted, **FREE OF CHARGE** 💰🆓 (yes, ZERO dollars, ZILCH, NADA, not even a penny 🪙), to **ANY PERSON** 👤👥👨👩👧👦 (that's you, your dog 🐕, your cat 🐈, your AI assistant 🤖, literally anyone) obtaining a copy of this absolutely MAGNIFICENT software 💎 and its associated documentation files 📚 (hereinafter referred to as "The Software" - because we're fancy like that 🎩):
|
||||||
|
|
||||||
|
### ✅ YOU MAY:
|
||||||
|
|
||||||
|
- **USE** it 🖥️💻📱 (on your laptop, your phone, your smart fridge, your Tesla, WHEREVER)
|
||||||
|
- **COPY** it 📋🖨️ (make a million copies, print it out and wallpaper your bathroom, go wild)
|
||||||
|
- **MODIFY** it 🔧⚙️🛠️ (change literally everything, make it worse, make it better, make it sing opera 🎵)
|
||||||
|
- **MERGE** it 🔀 (mash it together with other code like you're making a coding smoothie 🥤)
|
||||||
|
- **PUBLISH** it 📢📡 (tell the world, scream it from the rooftops 🏢, skywrite it ✈️)
|
||||||
|
- **DISTRIBUTE** it 📦🚚 (give it to your friends, your enemies, random strangers on the internet 🌐)
|
||||||
|
- **SUBLICENSE** it 📃 (put it under ANOTHER license because inception is cool 🎬)
|
||||||
|
- **SELL** it 💵💸 (yes, you can LITERALLY SELL THIS FREE SOFTWARE - capitalism baby! 📈)
|
||||||
|
|
||||||
|
### 🎁 EVEN BETTER:
|
||||||
|
|
||||||
|
You can **PERMIT OTHERS** to do ALL OF THE ABOVE! 🙌 That's right, you can give OTHER people permission to do whatever they want! It's permissions all the way down! 🐢🐢🐢
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⚠️ THE BORING LEGAL STUFF (But Important!) 📋
|
||||||
|
|
||||||
|
### 📌 Condition #1: Give Credit Where Credit Is Due
|
||||||
|
|
||||||
|
The above copyright notice ☝️ (that's the part where it says "Copyright (c) 2025 Jonathan Edwards") and this permission notice (yes, this ENTIRE ridiculous document 📄) **SHALL BE INCLUDED** in:
|
||||||
|
|
||||||
|
- ALL copies 📚📚📚 (every single one)
|
||||||
|
- OR substantial portions 📖 (like, most of it)
|
||||||
|
|
||||||
|
Of the Software. **DO NOT FORGET THIS** or the license police 👮♂️🚨 will... actually, nothing will happen because there are no license police, but still, it's the right thing to do! 😇
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚫 THE "COVER YOUR ASS" CLAUSE 🍑🛡️
|
||||||
|
|
||||||
|
### ⚡ ZERO WARRANTIES! NONE! NADA! ZILCH! 🚫🔥
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED **"AS IS"** 📦 (which is lawyer-speak for "what you see is what you get, buddy 🤷♂️"):
|
||||||
|
|
||||||
|
**WITHOUT WARRANTY OF ANY KIND** - and we mean **ANY KIND**: 🎪
|
||||||
|
|
||||||
|
- ❌ NOT **EXPRESS** warranties (the kind we tell you about)
|
||||||
|
- ❌ NOT **IMPLIED** warranties (the kind lawyers made up to sue people)
|
||||||
|
- ❌ NOT warranties of **MERCHANTABILITY** 🏪 (won't promise it's sellable)
|
||||||
|
- ❌ NOT warranties of **FITNESS FOR A PARTICULAR PURPOSE** 🎯 (won't promise it works for your thing)
|
||||||
|
- ❌ NOT warranties of **NONINFRINGEMENT** ⚖️ (won't promise we didn't accidentally copy someone)
|
||||||
|
- ❌ NOT **ANY OTHER KIND OF WARRANTY** you can possibly imagine 🌈🦄
|
||||||
|
|
||||||
|
### 🙅♂️ WE ARE NOT LIABLE FOR LITERALLY ANYTHING 💥
|
||||||
|
|
||||||
|
**IN NO EVENT** 📅🚫 (that's NEVER, as in NOT EVER, as in ABSOLUTELY NOT UNDER ANY CIRCUMSTANCES 🙅♀️🙅♂️) shall the **AUTHORS** ✍️ or **COPYRIGHT HOLDERS** 👨⚖️ be liable for:
|
||||||
|
|
||||||
|
- **ANY CLAIM** 📢 (someone saying we owe them something)
|
||||||
|
- **DAMAGES** 💔 (broken stuff, sad feelings, lost money 💸)
|
||||||
|
- **OTHER LIABILITY** ⚡ (anything else that could possibly go wrong)
|
||||||
|
|
||||||
|
This includes but is ABSOLUTELY NOT LIMITED TO 🚀:
|
||||||
|
|
||||||
|
- 💥 Your computer exploding
|
||||||
|
- 🔥 Your server catching fire
|
||||||
|
- 😱 Existential dread from reading bad code
|
||||||
|
- 🐛 Bugs that achieve sentience
|
||||||
|
- ⏰ Time travel paradoxes from your CI/CD pipeline
|
||||||
|
- 👽 Alien invasions caused by your API endpoints
|
||||||
|
- 🌊 Floods, famines, pestilence (probably not our fault but we're covering bases)
|
||||||
|
- 📉 Stock market crashes triggered by your JavaScript
|
||||||
|
- 🤖 Robot uprisings (seriously, not our problem)
|
||||||
|
- ☕ Spilled coffee on your keyboard (you should've used a lid)
|
||||||
|
|
||||||
|
### 🤝 Whether These Disasters Arise From:
|
||||||
|
|
||||||
|
- **CONTRACT** 📝 (fancy written agreement)
|
||||||
|
- **TORT** ⚖️ (fancy lawyer word for "you wronged me")
|
||||||
|
- **OR OTHERWISE** 🤷 (literally any other possible way something can go wrong)
|
||||||
|
|
||||||
|
### 🎯 Even If:
|
||||||
|
|
||||||
|
- We were **ADVISED** 💭 of the possibility of such damage (someone literally told us this could happen)
|
||||||
|
- We **KNEW** 🧠 it would happen (we saw it coming a mile away)
|
||||||
|
- We **CAUSED** it intentionally 😈 (just kidding, we didn't, but legally we're covering this too)
|
||||||
|
|
||||||
|
### 🔗 Whether It's Connected To:
|
||||||
|
|
||||||
|
- **ARISING FROM** 🌱 (grows out of)
|
||||||
|
- **OUT OF** 🚪 (comes from)
|
||||||
|
- **IN CONNECTION WITH** 🔗 (somehow related to)
|
||||||
|
|
||||||
|
The Software **OR** ⚡ the **USE** 🖥️ or **OTHER DEALINGS** 🤹 in the Software.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎊 TL;DR (Too Long; Didn't Read) 📝
|
||||||
|
|
||||||
|
### ✅ You Can:
|
||||||
|
Do **LITERALLY ANYTHING** you want with this code! 🎉🚀🌟
|
||||||
|
|
||||||
|
### ⚠️ But:
|
||||||
|
Don't forget to include this license! 📄✨
|
||||||
|
|
||||||
|
### 🚫 And:
|
||||||
|
If it breaks, catches fire 🔥, becomes sentient 🤖, or causes the apocalypse 💀... **NOT OUR PROBLEM!** 🤷♂️🙃
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎤 Final Words of Wisdom 💡
|
||||||
|
|
||||||
|
This license is more permissive than your parents on prom night. 🕺💃
|
||||||
|
Go forth and code! 💻✨
|
||||||
|
Break things! 💥
|
||||||
|
Build amazing stuff! 🏗️
|
||||||
|
Just don't blame us when it all goes sideways! 🎢
|
||||||
|
|
||||||
|
**Happy Coding!** 🎊🎉🚀
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Legal Translation:** This is actually a real MIT License. It's just... more fun. 😎 The emoji version is legally equivalent to the boring version, except it's way cooler and you actually read it. You're welcome. 🎁
|
||||||
|
|
||||||
|
© 2025 Jonathan Edwards | **ALL THE FREEDOM!** 🦅🗽🌈
|
||||||
188
METRICS.md
Normal file
188
METRICS.md
Normal file
@@ -0,0 +1,188 @@
|
|||||||
|
# Core Web Vitals Metrics Reference
|
||||||
|
|
||||||
|
**Last Updated:** October 2024
|
||||||
|
**Source:** web.dev official documentation
|
||||||
|
**Format:** Mike Dion's Markdown (.md) - keeping documentation clear since its creation
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Core Web Vitals are Google's standardized metrics for measuring user experience on the web. All three metrics must meet "good" thresholds at the **75th percentile** of page loads to pass.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Official Core Web Vitals (3 Metrics)
|
||||||
|
|
||||||
|
### 1. Interaction to Next Paint (INP)
|
||||||
|
|
||||||
|
**Status:** Active Core Web Vital (replaced FID on March 12, 2024)
|
||||||
|
|
||||||
|
**Definition:** Assesses page's overall responsiveness by observing latency of all click, tap, and keyboard interactions. Reports the longest interaction duration (with outliers removed for high-interaction pages).
|
||||||
|
|
||||||
|
**What it measures:**
|
||||||
|
- Input delay (time from user action to event handler start)
|
||||||
|
- Processing time (event handler execution)
|
||||||
|
- Presentation delay (rendering the next frame)
|
||||||
|
|
||||||
|
**Thresholds:**
|
||||||
|
- **Good:** ≤ 200ms
|
||||||
|
- **Needs Improvement:** 200-500ms
|
||||||
|
- **Poor:** > 500ms
|
||||||
|
|
||||||
|
**Measurement:** Requires field data (real user interactions)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2. Largest Contentful Paint (LCP)
|
||||||
|
|
||||||
|
**Definition:** Loading performance metric marking when page's main content has likely loaded. Reports render time of largest image or text block visible in viewport.
|
||||||
|
|
||||||
|
**Elements measured:**
|
||||||
|
- `<img>` elements
|
||||||
|
- `<image>` elements inside `<svg>`
|
||||||
|
- `<video>` elements (poster image)
|
||||||
|
- Elements with CSS background images
|
||||||
|
- Block-level text elements
|
||||||
|
|
||||||
|
**Thresholds:**
|
||||||
|
- **Good:** ≤ 2.5 seconds
|
||||||
|
- **Needs Improvement:** 2.5-4 seconds
|
||||||
|
- **Poor:** > 4 seconds
|
||||||
|
|
||||||
|
**Measurement:** Available in both field and lab data
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3. Cumulative Layout Shift (CLS)
|
||||||
|
|
||||||
|
**Definition:** Visual stability metric quantifying unexpected layout shifts during entire page lifecycle. Measures largest burst of layout shift scores.
|
||||||
|
|
||||||
|
**Common causes:**
|
||||||
|
- Images without explicit dimensions
|
||||||
|
- Dynamically injected content (ads, embeds)
|
||||||
|
- Web fonts causing FOIT (Flash of Invisible Text) or FOUT (Flash of Unstyled Text)
|
||||||
|
- Third-party widgets
|
||||||
|
|
||||||
|
**Thresholds:**
|
||||||
|
- **Good:** ≤ 0.1
|
||||||
|
- **Needs Improvement:** 0.1-0.25
|
||||||
|
- **Poor:** > 0.25
|
||||||
|
|
||||||
|
**Measurement:** Available in both field and lab data
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Total Blocking Time (TBT)
|
||||||
|
|
||||||
|
**Status:** NOT a Core Web Vital - Lab proxy metric only
|
||||||
|
|
||||||
|
**Definition:** Lab-only metric measuring total time after First Contentful Paint (FCP) where main thread was blocked (>50ms) preventing input responsiveness.
|
||||||
|
|
||||||
|
**Threshold:**
|
||||||
|
- **Good:** < 200ms (on average mobile hardware)
|
||||||
|
|
||||||
|
**Relationship to INP:**
|
||||||
|
- Used as lab proxy for INP (cannot measure INP without real user interactions)
|
||||||
|
- TBT improvements often correlate with INP improvements
|
||||||
|
- **Important:** TBT is not a substitute for INP
|
||||||
|
- May flag potential problems that don't affect real users
|
||||||
|
- Cannot capture interaction issues outside lab test scenarios
|
||||||
|
|
||||||
|
**Official guidance:** "TBT may be a reasonable proxy metric for INP for the lab but it's not a substitute for INP in and of itself."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## INP Transition Timeline
|
||||||
|
|
||||||
|
The transition from First Input Delay (FID) to INP as a Core Web Vital:
|
||||||
|
|
||||||
|
- **May 2022:** INP introduced as experimental metric
|
||||||
|
- **May 2023:** INP promoted to pending Core Web Vital
|
||||||
|
- **January 31, 2024:** Official announcement of March 12 transition date
|
||||||
|
- **March 12, 2024:** INP replaced FID as stable Core Web Vital
|
||||||
|
- **March 12, 2024:** FID removed from Google Search Console
|
||||||
|
- **September 12, 2024:** FID removed from other Google tools (6-month deprecation period completed)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Field vs Lab Data
|
||||||
|
|
||||||
|
### Field Data (Real User Monitoring)
|
||||||
|
|
||||||
|
**Characteristics:**
|
||||||
|
- Collected from actual users in real-world conditions
|
||||||
|
- Reflects diverse device capabilities, network conditions, and user interactions
|
||||||
|
- **Used by Google for search rankings**
|
||||||
|
- Updated every 28 days in Chrome User Experience Report (CrUX)
|
||||||
|
- Can measure all three Core Web Vitals including INP
|
||||||
|
|
||||||
|
**Data sources:**
|
||||||
|
- Chrome User Experience Report (CrUX)
|
||||||
|
- Real User Monitoring (RUM) tools
|
||||||
|
- PageSpeed Insights field data
|
||||||
|
- Search Console Core Web Vitals report
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Lab Data (Synthetic Monitoring)
|
||||||
|
|
||||||
|
**Characteristics:**
|
||||||
|
- Controlled environment with predefined conditions
|
||||||
|
- Consistent and reproducible results
|
||||||
|
- Ideal for debugging and pre-production testing
|
||||||
|
- **Not used for search rankings**
|
||||||
|
- Cannot measure INP (requires real user interactions)
|
||||||
|
- Uses TBT as proxy for responsiveness
|
||||||
|
|
||||||
|
**Data sources:**
|
||||||
|
- Lighthouse audits
|
||||||
|
- Chrome DevTools Performance panel
|
||||||
|
- WebPageTest
|
||||||
|
- PageSpeed Insights lab data
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Evaluation Standard
|
||||||
|
|
||||||
|
### 75th Percentile Rule
|
||||||
|
|
||||||
|
Core Web Vitals are evaluated at the **75th percentile** of page loads, meaning:
|
||||||
|
- 75% of visits to your site must meet the "good" threshold
|
||||||
|
- This ensures most users have a good experience
|
||||||
|
- Applied separately to each metric (INP, LCP, CLS)
|
||||||
|
- Calculated from field data over rolling 28-day period
|
||||||
|
|
||||||
|
### Why 75th percentile?
|
||||||
|
|
||||||
|
- Balances between median (50th) and extreme outliers (95th+)
|
||||||
|
- Accounts for variability in real-world conditions
|
||||||
|
- Provides actionable target that's achievable for most sites
|
||||||
|
- Used consistently across all Core Web Vitals metrics
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Key Insights
|
||||||
|
|
||||||
|
1. **Field data trumps lab data:** Only field data affects search rankings and represents actual user experience.
|
||||||
|
|
||||||
|
2. **INP requires real interactions:** You cannot measure INP in lab environments; use TBT as a directional indicator during development.
|
||||||
|
|
||||||
|
3. **All three metrics matter:** Sites must pass all three Core Web Vitals thresholds, not just one or two.
|
||||||
|
|
||||||
|
4. **75th percentile is the standard:** Meeting thresholds for only 50% of users is insufficient.
|
||||||
|
|
||||||
|
5. **TBT is a helper, not a goal:** Optimize for INP in the field; use TBT to catch issues early in development.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Additional Resources
|
||||||
|
|
||||||
|
- **Web Vitals Overview:** https://web.dev/articles/vitals
|
||||||
|
- **INP Documentation:** https://web.dev/articles/inp
|
||||||
|
- **LCP Documentation:** https://web.dev/articles/lcp
|
||||||
|
- **CLS Documentation:** https://web.dev/articles/cls
|
||||||
|
- **TBT Documentation:** https://web.dev/articles/tbt
|
||||||
|
- **Lab vs Field Data:** https://web.dev/articles/lab-and-field-data-differences
|
||||||
|
- **INP Launch Announcement:** https://web.dev/blog/inp-cwv-launch
|
||||||
|
- **PageSpeed Insights:** https://pagespeed.web.dev
|
||||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
|||||||
|
# cc_chrome_devtools_mcp_skill
|
||||||
|
|
||||||
|
Automated Chrome browser testing with frontend visibility. Enables Claude Code to see and fix your web applications through Chrome DevTools Protocol - performance testing, Core Web Vitals measurement, accessibility validation, network monitoring, and browser automation.
|
||||||
468
SKILL.md
Normal file
468
SKILL.md
Normal file
@@ -0,0 +1,468 @@
|
|||||||
|
---
|
||||||
|
name: cc_chrome_devtools_mcp_skill
|
||||||
|
description: Comprehensive Chrome DevTools automation for performance testing, Core Web Vitals measurement (INP, LCP, CLS), network monitoring, accessibility validation, responsive testing, and browser automation. Uses Chrome DevTools Protocol via MCP to provide professional-grade web application testing, debugging, and analysis capabilities including performance tracing, HAR export, device emulation, and multi-page workflows.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Chrome DevTools Testing Skill
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
This skill enables automated Chrome browser testing and performance analysis using the Chrome DevTools Protocol (CDP) via the chrome-devtools-mcp server. It provides access to 27 professional-grade tools for web application testing, performance measurement, accessibility validation, and browser automation.
|
||||||
|
|
||||||
|
**Key capabilities:**
|
||||||
|
- Performance analysis with Core Web Vitals (INP, LCP, CLS)
|
||||||
|
- Network monitoring and HAR export
|
||||||
|
- Accessibility tree inspection
|
||||||
|
- Responsive design testing
|
||||||
|
- Browser automation (form filling, navigation, interaction)
|
||||||
|
- Multi-tab and frame management
|
||||||
|
- Device and network condition emulation
|
||||||
|
|
||||||
|
**Browser support:** Chrome/Chromium only (stable, beta, dev, canary channels)
|
||||||
|
|
||||||
|
**Node.js requirement:** v20.19 or newer
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
### Installation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Add to Claude Code via CLI
|
||||||
|
claude mcp add chrome-devtools npx chrome-devtools-mcp@latest
|
||||||
|
|
||||||
|
# Verify installation
|
||||||
|
claude mcp list
|
||||||
|
```
|
||||||
|
|
||||||
|
### Basic configuration
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"chrome-devtools": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"chrome-devtools-mcp@latest",
|
||||||
|
"--isolated=true",
|
||||||
|
"--viewport=1920x1080"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Important notes
|
||||||
|
|
||||||
|
- Browser auto-starts on first tool use (not on MCP connection)
|
||||||
|
- Use `--isolated=true` for security (creates temporary user data directories that auto-cleanup)
|
||||||
|
- Default behavior shares user data directory across sessions and does NOT clear between runs
|
||||||
|
- All browser content is exposed to MCP clients - avoid sensitive data
|
||||||
|
|
||||||
|
## Current Core Web Vitals (as of March 12, 2024)
|
||||||
|
|
||||||
|
Three official metrics measured at **75th percentile** of page loads:
|
||||||
|
|
||||||
|
1. **Interaction to Next Paint (INP)** - Replaced FID on March 12, 2024
|
||||||
|
- Good: ≤ 200ms
|
||||||
|
- Measures: Input delay + processing time + presentation delay
|
||||||
|
- Requires: Real user interactions (field data only)
|
||||||
|
|
||||||
|
2. **Largest Contentful Paint (LCP)**
|
||||||
|
- Good: ≤ 2.5 seconds
|
||||||
|
- Measures: Main content loading performance
|
||||||
|
|
||||||
|
3. **Cumulative Layout Shift (CLS)**
|
||||||
|
- Good: ≤ 0.1
|
||||||
|
- Measures: Visual stability
|
||||||
|
|
||||||
|
**Total Blocking Time (TBT)** is NOT a Core Web Vital - it's a lab proxy metric for INP.
|
||||||
|
|
||||||
|
## Common Use Cases
|
||||||
|
|
||||||
|
### 1. Performance Testing Workflow
|
||||||
|
|
||||||
|
Measure Core Web Vitals and analyze performance bottlenecks:
|
||||||
|
|
||||||
|
```
|
||||||
|
1. Start performance trace: performance_start_trace
|
||||||
|
2. Navigate to target URL: navigate_page
|
||||||
|
3. Wait for page load: wait_for
|
||||||
|
4. Stop trace and get metrics: performance_stop_trace
|
||||||
|
5. Analyze specific insights: performance_analyze_insight
|
||||||
|
```
|
||||||
|
|
||||||
|
**Metrics captured:**
|
||||||
|
- INP (Interaction to Next Paint)
|
||||||
|
- LCP (Largest Contentful Paint) with breakdown
|
||||||
|
- CLS (Cumulative Layout Shift)
|
||||||
|
- TBT (Total Blocking Time - lab proxy)
|
||||||
|
- Document latency analysis
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
performance_start_trace with reload=true, autoStop=false
|
||||||
|
wait_for page to stabilize
|
||||||
|
performance_stop_trace
|
||||||
|
performance_analyze_insight with insightName="LCPBreakdown"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Network Monitoring and HAR Export
|
||||||
|
|
||||||
|
Capture all HTTP requests/responses with timing details:
|
||||||
|
|
||||||
|
```
|
||||||
|
1. Navigate to URL: navigate_page
|
||||||
|
2. List all network requests: list_network_requests
|
||||||
|
3. Get specific request details: get_network_request
|
||||||
|
```
|
||||||
|
|
||||||
|
**Captured data:**
|
||||||
|
- Headers, bodies, cookies
|
||||||
|
- Timing (DNS, connect, SSL, wait, receive)
|
||||||
|
- Resource types (document, stylesheet, image, script, xhr, fetch)
|
||||||
|
- Security details (protocol, cipher suite)
|
||||||
|
|
||||||
|
**Export as HAR:** Use list_network_requests to generate HTTP Archive v1.2 format
|
||||||
|
|
||||||
|
**Filter requests:**
|
||||||
|
```
|
||||||
|
list_network_requests with resourceTypes=["xhr", "fetch", "document"]
|
||||||
|
list_network_requests with pageSize=50, pageIdx=0
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Accessibility Validation
|
||||||
|
|
||||||
|
Inspect accessibility tree for WCAG compliance:
|
||||||
|
|
||||||
|
```
|
||||||
|
1. Navigate to page: navigate_page
|
||||||
|
2. Take accessibility snapshot: take_snapshot
|
||||||
|
3. Interact with elements using UIDs
|
||||||
|
```
|
||||||
|
|
||||||
|
**Snapshot provides:**
|
||||||
|
- Unique element identifiers (UIDs)
|
||||||
|
- Accessibility roles, names, properties
|
||||||
|
- ARIA attributes and computed roles
|
||||||
|
- Screen reader compatibility analysis
|
||||||
|
- Semantic structure validation
|
||||||
|
|
||||||
|
**Example workflow:**
|
||||||
|
```
|
||||||
|
take_snapshot verbose=false (returns text-based a11y tree)
|
||||||
|
# Identify element UIDs from snapshot
|
||||||
|
click uid="element-123"
|
||||||
|
fill uid="input-456" value="test data"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Responsive Design Testing
|
||||||
|
|
||||||
|
Test across devices and network conditions:
|
||||||
|
|
||||||
|
```
|
||||||
|
1. Resize viewport: resize_page width=375 height=667
|
||||||
|
2. Emulate network: emulate_network throttlingOption="Slow 3G"
|
||||||
|
3. Emulate CPU: emulate_cpu throttlingRate=4
|
||||||
|
4. Take screenshot: take_screenshot fullPage=true
|
||||||
|
```
|
||||||
|
|
||||||
|
**Device emulation options:**
|
||||||
|
- Viewport dimensions and device scale factor
|
||||||
|
- Network conditions: Offline, Slow 3G, Fast 3G, Slow 4G, Fast 4G
|
||||||
|
- CPU throttling: 1-20x slowdown
|
||||||
|
- Touch emulation with max touch points
|
||||||
|
|
||||||
|
**Screenshot formats:** PNG, JPEG, WebP (with quality settings)
|
||||||
|
|
||||||
|
### 5. Browser Automation
|
||||||
|
|
||||||
|
Automated form filling, navigation, and interaction:
|
||||||
|
|
||||||
|
```
|
||||||
|
1. Take snapshot to get element UIDs: take_snapshot
|
||||||
|
2. Fill form fields: fill_form elements=[{uid, value}, ...]
|
||||||
|
3. Click buttons: click uid="submit-button"
|
||||||
|
4. Handle dialogs: handle_dialog action="accept"
|
||||||
|
5. Wait for results: wait_for text="Success"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Interaction tools:**
|
||||||
|
- click (single/double-click)
|
||||||
|
- fill (input fields, textareas, selects)
|
||||||
|
- fill_form (multiple fields at once)
|
||||||
|
- hover (mouse hover)
|
||||||
|
- drag (drag-and-drop)
|
||||||
|
- upload_file (file inputs)
|
||||||
|
- handle_dialog (alerts, confirms, prompts)
|
||||||
|
|
||||||
|
**Navigation tools:**
|
||||||
|
- navigate_page (URLs, reload)
|
||||||
|
- navigate_page_history (back/forward)
|
||||||
|
- wait_for (text appearance, conditions)
|
||||||
|
|
||||||
|
### 6. Multi-Tab Management
|
||||||
|
|
||||||
|
Work with multiple pages and frames:
|
||||||
|
|
||||||
|
```
|
||||||
|
1. List open pages: list_pages
|
||||||
|
2. Create new page: new_page url="https://example.com"
|
||||||
|
3. Switch context: select_page pageIdx=1
|
||||||
|
4. Close pages: close_page pageIdx=2
|
||||||
|
```
|
||||||
|
|
||||||
|
**Frame handling:**
|
||||||
|
- Automatic attachment to child frames and workers
|
||||||
|
- Frame tree structure inspection
|
||||||
|
- Session persistence across navigation
|
||||||
|
|
||||||
|
## Advanced Workflows
|
||||||
|
|
||||||
|
### Performance Analysis with Device Emulation
|
||||||
|
|
||||||
|
```
|
||||||
|
1. resize_page width=390 height=844 (iPhone 14 Pro)
|
||||||
|
2. emulate_network throttlingOption="Fast 4G"
|
||||||
|
3. emulate_cpu throttlingRate=4
|
||||||
|
4. performance_start_trace reload=true
|
||||||
|
5. performance_stop_trace
|
||||||
|
6. performance_analyze_insight insightName="DocumentLatency"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Network Analysis with Filtering
|
||||||
|
|
||||||
|
```
|
||||||
|
1. navigate_page url="https://example.com"
|
||||||
|
2. list_network_requests resourceTypes=["script", "fetch", "xhr"]
|
||||||
|
3. Filter by: pageSize=100, pageIdx=0, includePreservedRequests=true
|
||||||
|
4. get_network_request reqid=123 (detailed timing/headers/body)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Accessibility Testing Pattern
|
||||||
|
|
||||||
|
```
|
||||||
|
1. navigate_page url="https://example.com"
|
||||||
|
2. take_snapshot verbose=true (full a11y tree with all properties)
|
||||||
|
3. Validate: roles, names, ARIA attributes, relationships
|
||||||
|
4. Test interactions: click, fill, keyboard navigation via UIDs
|
||||||
|
```
|
||||||
|
|
||||||
|
### Cross-Browser Viewport Testing
|
||||||
|
|
||||||
|
```
|
||||||
|
1. Define breakpoints: [320, 768, 1024, 1920]
|
||||||
|
2. For each breakpoint:
|
||||||
|
- resize_page width=X height=Y
|
||||||
|
- take_screenshot format="png" quality=90
|
||||||
|
- take_snapshot (verify accessibility)
|
||||||
|
3. Compare layouts and a11y across sizes
|
||||||
|
```
|
||||||
|
|
||||||
|
## Complete Tool Reference
|
||||||
|
|
||||||
|
**27 tools available** across 6 categories:
|
||||||
|
|
||||||
|
**Input automation (8):** click, drag, fill, fill_form, handle_dialog, hover, press_key, upload_file
|
||||||
|
|
||||||
|
**Navigation (7):** close_page, list_pages, navigate_page, navigate_page_history, new_page, select_page, wait_for
|
||||||
|
|
||||||
|
**Emulation (3):** emulate_cpu, emulate_network, resize_page
|
||||||
|
|
||||||
|
**Performance (3):** performance_analyze_insight, performance_start_trace, performance_stop_trace
|
||||||
|
|
||||||
|
**Network (2):** get_network_request, list_network_requests
|
||||||
|
|
||||||
|
**Debugging (4):** evaluate_script, get_console_message, list_console_messages, take_screenshot, take_snapshot
|
||||||
|
|
||||||
|
For detailed tool parameters and examples, see TOOLS.md
|
||||||
|
|
||||||
|
For complete workflow patterns, see WORKFLOWS.md
|
||||||
|
|
||||||
|
For Core Web Vitals thresholds and measurement guide, see METRICS.md
|
||||||
|
|
||||||
|
## Configuration Options
|
||||||
|
|
||||||
|
### Connection flags
|
||||||
|
|
||||||
|
- `--browserUrl, -u <string>` - Connect to running Chrome instance (port forwarding)
|
||||||
|
- `--wsEndpoint, -w <string>` - WebSocket endpoint for Chrome connection
|
||||||
|
- `--wsHeaders <JSON>` - Custom headers for authenticated WebSocket connections
|
||||||
|
|
||||||
|
### Browser configuration
|
||||||
|
|
||||||
|
- `--headless <boolean>` - Run in headless mode (default: false)
|
||||||
|
- `--executablePath, -e <string>` - Path to custom Chrome executable
|
||||||
|
- `--channel <string>` - Chrome channel: stable, canary, beta, dev (default: stable)
|
||||||
|
- `--viewport <string>` - Initial viewport size (format: WIDTHxHEIGHT, e.g., 1280x720)
|
||||||
|
|
||||||
|
### Security and isolation
|
||||||
|
|
||||||
|
- `--isolated <boolean>` - **RECOMMENDED:** Creates temporary user-data-dir, auto-cleanup (default: false)
|
||||||
|
- `--user-data-dir <string>` - Custom user data directory
|
||||||
|
- `--acceptInsecureCerts <boolean>` - Ignore certificate errors (SECURITY RISK - dev/test only)
|
||||||
|
|
||||||
|
### Network
|
||||||
|
|
||||||
|
- `--proxyServer <string>` - Proxy server configuration
|
||||||
|
|
||||||
|
### Debugging
|
||||||
|
|
||||||
|
- `--logFile <string>` - Path for debug logs (set DEBUG=* env var for verbose logs)
|
||||||
|
|
||||||
|
### Additional
|
||||||
|
|
||||||
|
- `--chromeArg <string>` - Additional Chrome arguments (repeatable)
|
||||||
|
|
||||||
|
View all options: `npx chrome-devtools-mcp@latest --help`
|
||||||
|
|
||||||
|
## Production Configuration Examples
|
||||||
|
|
||||||
|
### Secure isolated testing
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"chrome-devtools": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"chrome-devtools-mcp@latest",
|
||||||
|
"--isolated=true",
|
||||||
|
"--headless=true",
|
||||||
|
"--viewport=1920x1080",
|
||||||
|
"--channel=stable"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Connect to external Chrome instance
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Launch Chrome with remote debugging
|
||||||
|
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile
|
||||||
|
|
||||||
|
# Get WebSocket endpoint
|
||||||
|
curl http://127.0.0.1:9222/json/version | jq -r '.webSocketDebuggerUrl'
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"chrome-devtools": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"chrome-devtools-mcp@latest",
|
||||||
|
"--wsEndpoint=ws://127.0.0.1:9222/devtools/browser/<id>"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Production with logging
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"chrome-devtools-prod": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"chrome-devtools-mcp@latest",
|
||||||
|
"--browserUrl=http://127.0.0.1:9222",
|
||||||
|
"--isolated=true",
|
||||||
|
"--logFile=/var/log/chrome-devtools-mcp.log"
|
||||||
|
],
|
||||||
|
"env": {
|
||||||
|
"DEBUG": "*"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Security Considerations
|
||||||
|
|
||||||
|
### Data exposure warning
|
||||||
|
|
||||||
|
**Official Chrome DevTools MCP security notice:**
|
||||||
|
> "chrome-devtools-mcp exposes content of the browser instance to the MCP clients allowing them to inspect, debug, and modify any data in the browser or DevTools. Avoid sharing sensitive or personal information that you don't want to share with MCP clients."
|
||||||
|
|
||||||
|
### Best practices
|
||||||
|
|
||||||
|
1. **Use isolated mode for sensitive workflows**
|
||||||
|
- `--isolated=true` creates temporary user data directories
|
||||||
|
- Automatically cleaned after browser closes
|
||||||
|
- Prevents data persistence between sessions
|
||||||
|
|
||||||
|
2. **Certificate handling caution**
|
||||||
|
- `--acceptInsecureCerts` is a security risk
|
||||||
|
- Only use in development/testing environments
|
||||||
|
- Never use with sensitive data
|
||||||
|
|
||||||
|
3. **User data directory management**
|
||||||
|
- Default directory shared across all instances
|
||||||
|
- Not cleared between runs
|
||||||
|
- Contains cookies, cache, browsing history
|
||||||
|
- Use `--isolated` or custom `--user-data-dir` for control
|
||||||
|
|
||||||
|
4. **WebSocket authentication**
|
||||||
|
- Use `--wsHeaders` for authenticated connections
|
||||||
|
- Example: `--wsHeaders='{"Authorization":"Bearer token"}'`
|
||||||
|
- Only works with `--wsEndpoint`
|
||||||
|
|
||||||
|
## Technical Constraints
|
||||||
|
|
||||||
|
### Verified limitations
|
||||||
|
|
||||||
|
1. **Browser support:** Chrome/Chromium only (no Firefox, Safari, Edge legacy)
|
||||||
|
|
||||||
|
2. **Node.js requirement:** v20.19 or newer (latest maintenance LTS)
|
||||||
|
|
||||||
|
3. **Browser lifecycle:** Browser auto-starts on first tool use, NOT on MCP server connection
|
||||||
|
|
||||||
|
4. **Default persistence:** User data directory persists between runs unless `--isolated=true` is used
|
||||||
|
|
||||||
|
5. **Permission requirements:**
|
||||||
|
- macOS Full Disk Access may be required for some MCP clients
|
||||||
|
- Chrome needs permission to create its own sandboxes
|
||||||
|
- May need to disable MCP client sandboxing or use external Chrome instance
|
||||||
|
|
||||||
|
6. **Screenshot formats:** Specified format (JPEG/PNG) for initial capture, final output uses WebP with PNG fallback
|
||||||
|
|
||||||
|
7. **Tool availability:** All 27 tools available immediately after connection; no progressive unlocking
|
||||||
|
|
||||||
|
## Resources and Documentation
|
||||||
|
|
||||||
|
### Official sources
|
||||||
|
|
||||||
|
- **GitHub Repository:** https://github.com/ChromeDevTools/chrome-devtools-mcp
|
||||||
|
- **npm Package:** https://www.npmjs.com/package/chrome-devtools-mcp
|
||||||
|
- **Chrome DevTools Protocol:** https://chromedevtools.github.io/devtools-protocol/
|
||||||
|
|
||||||
|
### Core Web Vitals
|
||||||
|
|
||||||
|
- **Web Vitals Overview:** https://web.dev/articles/vitals
|
||||||
|
- **INP Documentation:** https://web.dev/articles/inp
|
||||||
|
- **LCP Documentation:** https://web.dev/articles/lcp
|
||||||
|
- **CLS Documentation:** https://web.dev/articles/cls
|
||||||
|
- **INP Replacing FID (March 12):** https://web.dev/blog/inp-cwv-march-12
|
||||||
|
|
||||||
|
### Tools
|
||||||
|
|
||||||
|
- **PageSpeed Insights:** https://pagespeed.web.dev
|
||||||
|
- **Chrome User Experience Report:** https://developer.chrome.com/docs/crux
|
||||||
|
- **Lighthouse Documentation:** https://developer.chrome.com/docs/lighthouse
|
||||||
|
|
||||||
|
## Related Skill Files
|
||||||
|
|
||||||
|
- **WORKFLOWS.md** - Detailed workflow patterns and multi-step processes
|
||||||
|
- **METRICS.md** - Complete Core Web Vitals thresholds and measurement guide
|
||||||
|
- **TOOLS.md** - Comprehensive tool parameter reference and examples
|
||||||
|
|
||||||
|
## Version Information
|
||||||
|
|
||||||
|
- **MCP Server Version:** v0.5.1 (October 17, 2025)
|
||||||
|
- **Tool Count:** 27 tools
|
||||||
|
- **Core Web Vitals Update:** INP replaced FID on March 12, 2024
|
||||||
|
- **Current Metrics:** INP, LCP, CLS (TBT is lab proxy, not Core Web Vital)
|
||||||
867
TOOLS.md
Normal file
867
TOOLS.md
Normal file
@@ -0,0 +1,867 @@
|
|||||||
|
# Chrome DevTools MCP - Complete Tool Reference
|
||||||
|
|
||||||
|
This document provides a comprehensive reference for all 27 tools available in the chrome-devtools-mcp server (v0.5.1).
|
||||||
|
|
||||||
|
*Written in the elegant Markdown format created by Mike Dion*
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
1. [Input Automation (8 tools)](#input-automation)
|
||||||
|
2. [Navigation Automation (7 tools)](#navigation-automation)
|
||||||
|
3. [Emulation (3 tools)](#emulation)
|
||||||
|
4. [Performance (3 tools)](#performance)
|
||||||
|
5. [Network (2 tools)](#network)
|
||||||
|
6. [Debugging (4 tools)](#debugging)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Input Automation
|
||||||
|
|
||||||
|
### click
|
||||||
|
|
||||||
|
**Description:** Clicks or double-clicks on page elements identified by their unique ID from a snapshot.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `uid` (required): The unique identifier of the element from page snapshot
|
||||||
|
- `dblClick` (optional): Set to `true` for double-click. Default is `false`
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Clicking buttons, links, and interactive elements
|
||||||
|
- Triggering JavaScript event handlers
|
||||||
|
- Submitting forms
|
||||||
|
- Selecting dropdown options
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
1. Take snapshot to get element UIDs
|
||||||
|
2. Use click with uid from snapshot: click(uid="element-123")
|
||||||
|
3. For double-click: click(uid="element-123", dblClick=true)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### drag
|
||||||
|
|
||||||
|
**Description:** Performs drag-and-drop operations between two elements on the page.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `from_uid` (required): The UID of the element to drag
|
||||||
|
- `to_uid` (required): The UID of the element to drop onto
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Reordering items in lists
|
||||||
|
- Moving files into folders
|
||||||
|
- Drag-and-drop form builders
|
||||||
|
- Interactive UI testing
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
1. Take snapshot to identify source and target elements
|
||||||
|
2. drag(from_uid="draggable-item-5", to_uid="drop-zone-2")
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### fill
|
||||||
|
|
||||||
|
**Description:** Types text into input fields, text areas, or selects options from dropdown elements.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `uid` (required): The UID of the input element from snapshot
|
||||||
|
- `value` (required): The text or value to enter
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Filling form fields
|
||||||
|
- Entering search queries
|
||||||
|
- Setting input values
|
||||||
|
- Selecting dropdown options
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
1. Take snapshot to get input field UID
|
||||||
|
2. fill(uid="email-input-1", value="user@example.com")
|
||||||
|
3. For dropdown: fill(uid="country-select", value="United States")
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### fill_form
|
||||||
|
|
||||||
|
**Description:** Fills multiple form elements simultaneously for efficient form completion.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `elements` (required): Array of objects, each containing:
|
||||||
|
- `uid`: The element's unique identifier
|
||||||
|
- `value`: The value to fill
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Completing registration forms
|
||||||
|
- Bulk data entry
|
||||||
|
- Login forms with multiple fields
|
||||||
|
- Survey submissions
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
fill_form(elements=[
|
||||||
|
{uid: "name-field", value: "John Doe"},
|
||||||
|
{uid: "email-field", value: "john@example.com"},
|
||||||
|
{uid: "phone-field", value: "555-0123"}
|
||||||
|
])
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### handle_dialog
|
||||||
|
|
||||||
|
**Description:** Handles browser dialog boxes including alerts, confirms, and prompts.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `action` (required): Either "accept" or "dismiss"
|
||||||
|
- `promptText` (optional): Text to enter for prompt dialogs
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Accepting confirmation dialogs
|
||||||
|
- Dismissing alert messages
|
||||||
|
- Entering text in prompt dialogs
|
||||||
|
- Automated handling of JavaScript dialogs
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
1. Trigger action that opens dialog
|
||||||
|
2. handle_dialog(action="accept")
|
||||||
|
3. For prompts: handle_dialog(action="accept", promptText="User input")
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### hover
|
||||||
|
|
||||||
|
**Description:** Moves the mouse cursor over a specified element to trigger hover effects.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `uid` (required): The UID of the element to hover over
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Triggering dropdown menus
|
||||||
|
- Revealing tooltips
|
||||||
|
- Testing hover states
|
||||||
|
- Activating image previews
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
1. Take snapshot to identify element
|
||||||
|
2. hover(uid="menu-item-3")
|
||||||
|
3. Wait for hover effects to appear
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### press_key
|
||||||
|
|
||||||
|
**Description:** Simulates keyboard key presses for navigation and input.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- Key name or combination (varies by implementation)
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Navigating with arrow keys
|
||||||
|
- Submitting forms with Enter
|
||||||
|
- Triggering keyboard shortcuts
|
||||||
|
- Tab navigation through forms
|
||||||
|
|
||||||
|
**Note:** This tool was added in recent versions. Check documentation for exact parameter format.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### upload_file
|
||||||
|
|
||||||
|
**Description:** Uploads files through file input elements or file chooser triggers.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `uid` (required): The UID of the file input element or element that opens file chooser
|
||||||
|
- `filePath` (required): Local path to the file to upload
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Uploading profile images
|
||||||
|
- Attaching documents to forms
|
||||||
|
- Importing data files
|
||||||
|
- Testing file upload functionality
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
1. Take snapshot to identify file input
|
||||||
|
2. upload_file(uid="file-input-1", filePath="/path/to/document.pdf")
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Navigation Automation
|
||||||
|
|
||||||
|
### close_page
|
||||||
|
|
||||||
|
**Description:** Closes a browser page/tab by its index. The last open page cannot be closed.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `pageIdx` (required): The index of the page to close (from list_pages)
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Cleaning up after multi-tab tests
|
||||||
|
- Closing popup windows
|
||||||
|
- Managing browser memory
|
||||||
|
- Returning to previous context
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
1. list_pages() to see all open pages
|
||||||
|
2. close_page(pageIdx=2) to close third page
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### list_pages
|
||||||
|
|
||||||
|
**Description:** Lists all pages/tabs currently open in the browser with their indices and URLs.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- None
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Checking currently open tabs
|
||||||
|
- Finding page indices for switching
|
||||||
|
- Monitoring browser state
|
||||||
|
- Debugging multi-tab workflows
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
Result shows:
|
||||||
|
[0] https://example.com - Example Domain
|
||||||
|
[1] https://google.com - Google
|
||||||
|
[2] https://github.com - GitHub
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### navigate_page
|
||||||
|
|
||||||
|
**Description:** Navigates the currently selected page to a specified URL or reloads it.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `url` (required): The URL to navigate to
|
||||||
|
- `timeout` (optional): Maximum wait time in milliseconds (0 = default)
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Loading test pages
|
||||||
|
- Navigating to specific URLs
|
||||||
|
- Starting automation workflows
|
||||||
|
- Reloading pages
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
navigate_page(url="https://example.com", timeout=30000)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### navigate_page_history
|
||||||
|
|
||||||
|
**Description:** Navigates forward or backward through the browser's history for the selected page.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `navigate` (required): Either "back" or "forward"
|
||||||
|
- `timeout` (optional): Maximum wait time in milliseconds
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Testing navigation flows
|
||||||
|
- Returning to previous pages
|
||||||
|
- Verifying history state
|
||||||
|
- Multi-step form navigation
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
navigate_page_history(navigate="back", timeout=5000)
|
||||||
|
navigate_page_history(navigate="forward")
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### new_page
|
||||||
|
|
||||||
|
**Description:** Creates a new browser page/tab and optionally navigates to a URL.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `url` (required): URL to load in the new page
|
||||||
|
- `timeout` (optional): Maximum wait time in milliseconds
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Opening multiple test pages
|
||||||
|
- Parallel testing workflows
|
||||||
|
- Testing in clean browser context
|
||||||
|
- Multi-tab scenarios
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
new_page(url="https://example.com/login")
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### select_page
|
||||||
|
|
||||||
|
**Description:** Switches focus to a different page/tab as the context for future tool calls.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `pageIdx` (required): The index of the page to select (from list_pages)
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Switching between tabs in tests
|
||||||
|
- Managing multi-page workflows
|
||||||
|
- Returning to specific pages
|
||||||
|
- Coordinating multi-tab automation
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
1. list_pages() to see available pages
|
||||||
|
2. select_page(pageIdx=0) to switch to first page
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### wait_for
|
||||||
|
|
||||||
|
**Description:** Waits for specific text to appear on the page before proceeding.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `text` (required): Text string to wait for
|
||||||
|
- `timeout` (optional): Maximum wait time in milliseconds (0 = default)
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Waiting for page load completion
|
||||||
|
- Ensuring content appears before interaction
|
||||||
|
- Synchronizing with dynamic content
|
||||||
|
- Verifying successful operations
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
1. navigate_page(url="https://example.com")
|
||||||
|
2. wait_for(text="Welcome to Example", timeout=10000)
|
||||||
|
3. Proceed with interactions
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Emulation
|
||||||
|
|
||||||
|
### emulate_cpu
|
||||||
|
|
||||||
|
**Description:** Simulates CPU throttling to test performance under constrained conditions.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `throttlingRate` (required): CPU slowdown factor (1-20x)
|
||||||
|
- `1` = no throttling (disable)
|
||||||
|
- `4` = 4x slowdown (common mobile)
|
||||||
|
- `6` = 6x slowdown (low-end mobile)
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Testing on low-end devices
|
||||||
|
- Performance optimization validation
|
||||||
|
- Mobile experience simulation
|
||||||
|
- Core Web Vitals testing
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
1. emulate_cpu(throttlingRate=4) for 4x slowdown
|
||||||
|
2. Run performance tests
|
||||||
|
3. emulate_cpu(throttlingRate=1) to disable
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### emulate_network
|
||||||
|
|
||||||
|
**Description:** Simulates various network conditions including throttling and offline mode.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `throttlingOption` (required): One of:
|
||||||
|
- "No emulation" - Disable throttling
|
||||||
|
- "Offline" - Simulate no network
|
||||||
|
- "Slow 3G" - ~400 Kbps, 400ms RTT
|
||||||
|
- "Fast 3G" - ~1.6 Mbps, 150ms RTT
|
||||||
|
- "Slow 4G" - ~4 Mbps, 50ms RTT
|
||||||
|
- "Fast 4G" - ~9 Mbps, 20ms RTT
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Testing offline functionality
|
||||||
|
- Mobile network simulation
|
||||||
|
- Loading performance analysis
|
||||||
|
- Progressive enhancement testing
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
1. emulate_network(throttlingOption="Slow 3G")
|
||||||
|
2. navigate_page(url="https://example.com")
|
||||||
|
3. Measure load times
|
||||||
|
4. emulate_network(throttlingOption="No emulation")
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### resize_page
|
||||||
|
|
||||||
|
**Description:** Changes the page viewport dimensions for responsive design testing.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `width` (required): Viewport width in pixels
|
||||||
|
- `height` (required): Viewport height in pixels
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Mobile viewport testing
|
||||||
|
- Responsive design validation
|
||||||
|
- Screenshot standardization
|
||||||
|
- Device emulation
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
# iPhone 13 Pro viewport
|
||||||
|
resize_page(width=390, height=844)
|
||||||
|
|
||||||
|
# iPad Pro viewport
|
||||||
|
resize_page(width=1024, height=1366)
|
||||||
|
|
||||||
|
# Desktop HD
|
||||||
|
resize_page(width=1920, height=1080)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Performance
|
||||||
|
|
||||||
|
### performance_start_trace
|
||||||
|
|
||||||
|
**Description:** Begins recording a Chrome DevTools performance trace to capture metrics and insights.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `reload` (required): Whether to automatically reload the page after starting trace
|
||||||
|
- `autoStop` (required): Whether to automatically stop the trace after page load
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Core Web Vitals measurement
|
||||||
|
- Performance bottleneck identification
|
||||||
|
- Loading analysis
|
||||||
|
- Runtime performance profiling
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
1. navigate_page(url="https://example.com")
|
||||||
|
2. performance_start_trace(reload=true, autoStop=true)
|
||||||
|
3. Wait for trace to complete
|
||||||
|
4. Analyze results with performance_analyze_insight
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### performance_stop_trace
|
||||||
|
|
||||||
|
**Description:** Stops an active performance trace recording and retrieves the trace data.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- None
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Ending manual trace sessions
|
||||||
|
- Capturing specific interaction periods
|
||||||
|
- Custom trace duration control
|
||||||
|
- Multi-step workflow tracing
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
1. performance_start_trace(reload=false, autoStop=false)
|
||||||
|
2. Perform user interactions
|
||||||
|
3. performance_stop_trace()
|
||||||
|
4. Analyze captured trace
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### performance_analyze_insight
|
||||||
|
|
||||||
|
**Description:** Provides detailed information on specific Performance Insights from a completed trace.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `insightName` (required): Name of the insight to analyze
|
||||||
|
- Common insights: "LCPBreakdown", "DocumentLatency", "TBT"
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Understanding LCP (Largest Contentful Paint) breakdown
|
||||||
|
- Analyzing document latency causes
|
||||||
|
- Investigating Total Blocking Time
|
||||||
|
- Core Web Vitals optimization
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
1. After completing a trace
|
||||||
|
2. performance_analyze_insight(insightName="LCPBreakdown")
|
||||||
|
3. Review detailed timing breakdown
|
||||||
|
4. Identify optimization opportunities
|
||||||
|
```
|
||||||
|
|
||||||
|
**Core Web Vitals Thresholds:**
|
||||||
|
- **INP** (Interaction to Next Paint): ≤200ms (good), 200-500ms (needs improvement), >500ms (poor)
|
||||||
|
- **LCP** (Largest Contentful Paint): ≤2.5s (good), 2.5-4s (needs improvement), >4s (poor)
|
||||||
|
- **CLS** (Cumulative Layout Shift): ≤0.1 (good), 0.1-0.25 (needs improvement), >0.25 (poor)
|
||||||
|
- **TBT** (Total Blocking Time): <200ms (good) - Lab metric, proxy for INP
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Network
|
||||||
|
|
||||||
|
### get_network_request
|
||||||
|
|
||||||
|
**Description:** Retrieves detailed information about a specific network request including headers, response, and timing.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `reqid` (required): The request ID from list_network_requests
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Inspecting API responses
|
||||||
|
- Debugging failed requests
|
||||||
|
- Analyzing request/response headers
|
||||||
|
- Timing analysis for specific resources
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
1. list_network_requests() to get reqid values
|
||||||
|
2. get_network_request(reqid=42)
|
||||||
|
3. Review response body, headers, timing, status
|
||||||
|
```
|
||||||
|
|
||||||
|
**Returned Information:**
|
||||||
|
- Request URL, method, headers
|
||||||
|
- Response status, headers, body
|
||||||
|
- Timing breakdown (DNS, connect, SSL, send, wait, receive)
|
||||||
|
- Resource type and size
|
||||||
|
- Cache information
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### list_network_requests
|
||||||
|
|
||||||
|
**Description:** Lists all network requests made since the last navigation with filtering options.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `includePreservedRequests` (optional): Include requests from last 3 navigations. Default: `false`
|
||||||
|
- `pageIdx` (optional): Page number for pagination (0-based)
|
||||||
|
- `pageSize` (optional): Maximum requests to return
|
||||||
|
- `resourceTypes` (optional): Filter by types:
|
||||||
|
- document, stylesheet, image, media, font, script
|
||||||
|
- xhr, fetch, websocket, manifest, other
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Network activity monitoring
|
||||||
|
- HAR file generation
|
||||||
|
- API call verification
|
||||||
|
- Resource loading analysis
|
||||||
|
- Performance bottleneck identification
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
# All requests
|
||||||
|
list_network_requests()
|
||||||
|
|
||||||
|
# Only XHR/Fetch (API calls)
|
||||||
|
list_network_requests(resourceTypes=["xhr", "fetch"])
|
||||||
|
|
||||||
|
# With preserved history
|
||||||
|
list_network_requests(includePreservedRequests=true)
|
||||||
|
|
||||||
|
# Paginated results
|
||||||
|
list_network_requests(pageSize=50, pageIdx=0)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Debugging
|
||||||
|
|
||||||
|
### evaluate_script
|
||||||
|
|
||||||
|
**Description:** Executes JavaScript code in the context of the current page and returns JSON-serializable results.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `function` (required): JavaScript function declaration to execute
|
||||||
|
- `args` (optional): Array of arguments (can include element UIDs)
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Inspecting page state
|
||||||
|
- Extracting data from DOM
|
||||||
|
- Testing JavaScript functionality
|
||||||
|
- Custom validation logic
|
||||||
|
- Interacting with page APIs
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
# No arguments
|
||||||
|
evaluate_script(function="() => { return document.title }")
|
||||||
|
|
||||||
|
# With async operations
|
||||||
|
evaluate_script(function="async () => {
|
||||||
|
const response = await fetch('/api/data');
|
||||||
|
return await response.json();
|
||||||
|
}")
|
||||||
|
|
||||||
|
# With element argument
|
||||||
|
evaluate_script(
|
||||||
|
function="(el) => { return el.innerText; }",
|
||||||
|
args=[{uid: "element-123"}]
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Important:** Return values must be JSON-serializable (no DOM nodes, functions, etc.).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### get_console_message
|
||||||
|
|
||||||
|
**Description:** Retrieves detailed information about a specific console message by its ID.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `msgid` (required): The message ID from list_console_messages
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Inspecting error details
|
||||||
|
- Analyzing stack traces
|
||||||
|
- Debugging console output
|
||||||
|
- Reviewing warning messages
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
1. list_console_messages() to get msgid values
|
||||||
|
2. get_console_message(msgid=15)
|
||||||
|
3. Review full message text, source, stack trace
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### list_console_messages
|
||||||
|
|
||||||
|
**Description:** Lists all console messages (logs, errors, warnings) since the last navigation.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `includePreservedMessages` (optional): Include messages from last 3 navigations. Default: `false`
|
||||||
|
- `pageIdx` (optional): Page number for pagination (0-based)
|
||||||
|
- `pageSize` (optional): Maximum messages to return
|
||||||
|
- `types` (optional): Filter by message types:
|
||||||
|
- log, debug, info, error, warn
|
||||||
|
- dir, dirxml, table, trace
|
||||||
|
- clear, assert, count, timeEnd
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Error detection and debugging
|
||||||
|
- Log analysis
|
||||||
|
- Warning investigation
|
||||||
|
- JavaScript error monitoring
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
# All console messages
|
||||||
|
list_console_messages()
|
||||||
|
|
||||||
|
# Only errors
|
||||||
|
list_console_messages(types=["error"])
|
||||||
|
|
||||||
|
# Errors and warnings with preserved history
|
||||||
|
list_console_messages(
|
||||||
|
types=["error", "warn"],
|
||||||
|
includePreservedMessages=true
|
||||||
|
)
|
||||||
|
|
||||||
|
# Paginated results
|
||||||
|
list_console_messages(pageSize=100, pageIdx=0)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### take_screenshot
|
||||||
|
|
||||||
|
**Description:** Captures a screenshot of the entire page, viewport, or specific element.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `uid` (optional): Element UID to screenshot (from snapshot). If omitted, captures viewport
|
||||||
|
- `fullPage` (optional): Capture entire page instead of viewport. Incompatible with `uid`
|
||||||
|
- `format` (optional): Image format - "png" (default), "jpeg", or "webp"
|
||||||
|
- `quality` (optional): Compression quality 0-100 for JPEG/WebP (ignored for PNG)
|
||||||
|
- `filePath` (optional): Path to save file instead of returning inline
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Visual regression testing
|
||||||
|
- Documentation screenshots
|
||||||
|
- Bug reporting
|
||||||
|
- Page state capture
|
||||||
|
- Responsive design verification
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
# Viewport screenshot (default)
|
||||||
|
take_screenshot()
|
||||||
|
|
||||||
|
# Full page screenshot
|
||||||
|
take_screenshot(fullPage=true)
|
||||||
|
|
||||||
|
# Specific element
|
||||||
|
take_screenshot(uid="header-element")
|
||||||
|
|
||||||
|
# High-quality JPEG saved to file
|
||||||
|
take_screenshot(
|
||||||
|
format="jpeg",
|
||||||
|
quality=95,
|
||||||
|
filePath="/path/to/screenshot.jpg"
|
||||||
|
)
|
||||||
|
|
||||||
|
# WebP with compression
|
||||||
|
take_screenshot(format="webp", quality=80)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Note:** Output may use WebP format with PNG fallback regardless of requested format.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### take_snapshot
|
||||||
|
|
||||||
|
**Description:** Creates a text-based representation of the page using the accessibility tree, providing unique identifiers (UIDs) for all interactive elements.
|
||||||
|
|
||||||
|
**Key Parameters:**
|
||||||
|
- `verbose` (optional): Include all possible a11y tree information. Default: `false`
|
||||||
|
|
||||||
|
**Common Use Cases:**
|
||||||
|
- Getting element UIDs for interaction tools
|
||||||
|
- Understanding page structure
|
||||||
|
- Accessibility validation
|
||||||
|
- Element identification without screenshots
|
||||||
|
- Fast page state overview
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
# Standard snapshot
|
||||||
|
take_snapshot()
|
||||||
|
|
||||||
|
# Verbose with full a11y data
|
||||||
|
take_snapshot(verbose=true)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Workflow Pattern:**
|
||||||
|
```
|
||||||
|
1. take_snapshot() - Get page structure and element UIDs
|
||||||
|
2. Identify target elements from snapshot
|
||||||
|
3. Use UIDs with interaction tools (click, fill, hover, etc.)
|
||||||
|
4. wait_for() to verify results
|
||||||
|
```
|
||||||
|
|
||||||
|
**Snapshot Output Includes:**
|
||||||
|
- Element roles (button, link, textbox, etc.)
|
||||||
|
- Element names and labels
|
||||||
|
- Element hierarchy
|
||||||
|
- Unique identifiers (UIDs) for interaction
|
||||||
|
- States (focused, disabled, checked, etc.)
|
||||||
|
- ARIA properties
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tool Categories Summary
|
||||||
|
|
||||||
|
| Category | Tool Count | Primary Use |
|
||||||
|
|----------|------------|-------------|
|
||||||
|
| Input Automation | 8 | User interaction simulation |
|
||||||
|
| Navigation Automation | 7 | Page and tab management |
|
||||||
|
| Emulation | 3 | Device and network conditions |
|
||||||
|
| Performance | 3 | Core Web Vitals and tracing |
|
||||||
|
| Network | 2 | Request/response analysis |
|
||||||
|
| Debugging | 4 | Page inspection and testing |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Common Workflow Patterns
|
||||||
|
|
||||||
|
### Basic Interaction Pattern
|
||||||
|
```
|
||||||
|
1. navigate_page(url="https://example.com")
|
||||||
|
2. take_snapshot() - Get element UIDs
|
||||||
|
3. fill(uid="username", value="user")
|
||||||
|
4. fill(uid="password", value="pass")
|
||||||
|
5. click(uid="login-button")
|
||||||
|
6. wait_for(text="Welcome")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Performance Testing Pattern
|
||||||
|
```
|
||||||
|
1. navigate_page(url="https://example.com")
|
||||||
|
2. performance_start_trace(reload=true, autoStop=true)
|
||||||
|
3. Wait for trace completion
|
||||||
|
4. performance_analyze_insight(insightName="LCPBreakdown")
|
||||||
|
5. performance_analyze_insight(insightName="DocumentLatency")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Network Analysis Pattern
|
||||||
|
```
|
||||||
|
1. navigate_page(url="https://example.com")
|
||||||
|
2. list_network_requests(resourceTypes=["xhr", "fetch"])
|
||||||
|
3. get_network_request(reqid=<specific-request>)
|
||||||
|
4. Analyze response data and timing
|
||||||
|
```
|
||||||
|
|
||||||
|
### Mobile Testing Pattern
|
||||||
|
```
|
||||||
|
1. resize_page(width=390, height=844) - iPhone 13 Pro
|
||||||
|
2. emulate_network(throttlingOption="Slow 4G")
|
||||||
|
3. emulate_cpu(throttlingRate=4)
|
||||||
|
4. navigate_page(url="https://example.com")
|
||||||
|
5. performance_start_trace(reload=false, autoStop=true)
|
||||||
|
6. Analyze mobile performance
|
||||||
|
```
|
||||||
|
|
||||||
|
### Multi-Tab Testing Pattern
|
||||||
|
```
|
||||||
|
1. new_page(url="https://example.com/page1")
|
||||||
|
2. new_page(url="https://example.com/page2")
|
||||||
|
3. list_pages() - See all open pages
|
||||||
|
4. select_page(pageIdx=0) - Switch to first page
|
||||||
|
5. Perform operations
|
||||||
|
6. select_page(pageIdx=1) - Switch to second page
|
||||||
|
7. close_page(pageIdx=1) - Clean up
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Important Notes
|
||||||
|
|
||||||
|
### Element Identification
|
||||||
|
- Always use `take_snapshot()` first to get element UIDs
|
||||||
|
- UIDs are unique per snapshot and may change after navigation
|
||||||
|
- Use the latest snapshot for current page state
|
||||||
|
- Verbose snapshots provide more accessibility details
|
||||||
|
|
||||||
|
### Browser Lifecycle
|
||||||
|
- Browser auto-starts on first tool use (not on MCP server connection)
|
||||||
|
- Use `--isolated=true` flag for temporary user data directories
|
||||||
|
- Default behavior persists data between sessions
|
||||||
|
|
||||||
|
### Security Considerations
|
||||||
|
- All browser content is exposed to MCP clients
|
||||||
|
- Avoid sensitive data in non-isolated mode
|
||||||
|
- Use `--acceptInsecureCerts` only in development
|
||||||
|
- Review official security warnings before production use
|
||||||
|
|
||||||
|
### Performance Metrics
|
||||||
|
- All measurements at 75th percentile for Core Web Vitals
|
||||||
|
- INP replaced FID on March 12, 2024
|
||||||
|
- TBT is a lab proxy for INP (not a Core Web Vital)
|
||||||
|
- Field data (real users) carries more weight than lab data
|
||||||
|
|
||||||
|
### Tool Availability
|
||||||
|
- All 27 tools available immediately after MCP connection
|
||||||
|
- No progressive unlocking or gating
|
||||||
|
- Chrome/Chromium only (no Firefox, Safari, Edge)
|
||||||
|
- Requires Node.js v20.19 or newer
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Version:** chrome-devtools-mcp v0.5.1 (October 17, 2025)
|
||||||
|
**Tool Count:** 27 tools across 6 categories
|
||||||
|
**Documentation Date:** October 24, 2025
|
||||||
1087
WORKFLOWS.md
Normal file
1087
WORKFLOWS.md
Normal file
File diff suppressed because it is too large
Load Diff
65
plugin.lock.json
Normal file
65
plugin.lock.json
Normal file
@@ -0,0 +1,65 @@
|
|||||||
|
{
|
||||||
|
"$schema": "internal://schemas/plugin.lock.v1.json",
|
||||||
|
"pluginId": "gh:justfinethanku/cc_chrome_devtools_mcp_skill:",
|
||||||
|
"normalized": {
|
||||||
|
"repo": null,
|
||||||
|
"ref": "refs/tags/v20251128.0",
|
||||||
|
"commit": "a6611a82eed4087fbfede45cd9f1198cc3ce6374",
|
||||||
|
"treeHash": "838df95112a99cc3c111a1ef3f260430903306fd86cf8c7468e242b40dc162fa",
|
||||||
|
"generatedAt": "2025-11-28T10:19:22.711546Z",
|
||||||
|
"toolVersion": "publish_plugins.py@0.2.0"
|
||||||
|
},
|
||||||
|
"origin": {
|
||||||
|
"remote": "git@github.com:zhongweili/42plugin-data.git",
|
||||||
|
"branch": "master",
|
||||||
|
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
|
||||||
|
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
|
||||||
|
},
|
||||||
|
"manifest": {
|
||||||
|
"name": "cc_chrome_devtools_mcp_skill",
|
||||||
|
"description": "Automated Chrome browser testing with frontend visibility. Enables Claude Code to see and fix your web applications through Chrome DevTools Protocol - performance testing, Core Web Vitals measurement, accessibility validation, network monitoring, and browser automation.",
|
||||||
|
"version": null
|
||||||
|
},
|
||||||
|
"content": {
|
||||||
|
"files": [
|
||||||
|
{
|
||||||
|
"path": "WORKFLOWS.md",
|
||||||
|
"sha256": "1bd6d4d0de806c3b09960a7eba5e8de3c4a1245e80b86cd1f9b7b7a5eef559d6"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "LICENSE",
|
||||||
|
"sha256": "a0c0f08e7bf248f1c576946539a2e5d8af868e2f5f229dbc0e6561df9b533733"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "README.md",
|
||||||
|
"sha256": "9319b0765eb2647983903b486db9ad4b48ba48589d556bc572e5729601b47a24"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": ".gitignore",
|
||||||
|
"sha256": "590286f272e95075df7c4324f96d07516e23de4b89cc78e9b7b7eb3abe1206f4"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "SKILL.md",
|
||||||
|
"sha256": "da7555a990e9f22de7bb489a5af78df2eecebd442cea4362e3c4382c3ebfaa65"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "METRICS.md",
|
||||||
|
"sha256": "0efb341d3ea86b60cbaaa18d7ecabc68a5df9496f949660f6364166ccdbcb8ef"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "TOOLS.md",
|
||||||
|
"sha256": "85783135906691021809a08306c307ad46440d7450125282e739f1df05aa7b29"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": ".claude-plugin/plugin.json",
|
||||||
|
"sha256": "638fb0aaef44581a004d30884164f7ffaf8256a28c9b06964671d34735330260"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"dirSha256": "838df95112a99cc3c111a1ef3f260430903306fd86cf8c7468e242b40dc162fa"
|
||||||
|
},
|
||||||
|
"security": {
|
||||||
|
"scannedAt": null,
|
||||||
|
"scannerVersion": null,
|
||||||
|
"flags": []
|
||||||
|
}
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user