Chrome DevTools for coding agents
feat: add a skill for detecting memory leaks using take_memory_snapshot tool (#1162)
Ewad19a2350f975
diff --git a/eslint.config.mjs b/eslint.config.mjsindex f4790ca7..b1a6121c 100644--- a/eslint.config.mjs+++ b/eslint.config.mjs@@ -37,6 +37,7 @@ export default defineConfig(['puppeteer.config.cjs','eslint.config.mjs','rollup.config.mjs',+ 'skills/memory-leak-debugging/references/compare_snapshots.js',],},},diff --git a/skills/memory-leak-debugging/SKILL.md b/skills/memory-leak-debugging/SKILL.mdnew file mode 100644index 00000000..faa9957d--- /dev/null+++ b/skills/memory-leak-debugging/SKILL.md@@ -0,0 +1,50 @@+---+name: memory-leak-debugging+description: Diagnoses and resolves memory leaks in JavaScript/Node.js applications. Use when a user reports high memory usage, OOM errors, or wants to analyze heapsnapshots or run memory leak detection tools like memlab.+---++# Memory Leak Debugging++This skill provides expert guidance and workflows for finding, diagnosing, and fixing memory leaks in JavaScript and Node.js applications.++## Core Principles++- **Prefer `memlab`:** Do NOT attempt to read raw `.heapsnapshot` files directly, as they are extremely large and will consume too many tokens. Always recommend and use `memlab` to process snapshots and identify leak traces.+- **Isolate the Leak:** Determine if the leak is in the browser (client-side) or Node.js (server-side).+- **Common Culprits:** Look for detached DOM nodes, unhandled closures, global variables, event listeners not being removed, and caches growing unbounded. _Note: Detached DOM nodes are sometimes intentional caches; always ask the user before nulling them._++## Workflows++### 1. Capturing Snapshots++When investigating a frontend web application memory leak, utilize the `chrome-devtools-mcp` tools to interact with the application and take snapshots.++- Use tools like `click`, `navigate_page`, `fill`, etc., to manipulate the page into the desired state.+- Revert the page back to the original state after interactions to see if memory is released.+- Repeat the same user interactions 10 times to amplify the leak.+- Use `take_memory_snapshot` to save `.heapsnapshot` files to disk at baseline, target (after actions), and final (after reverting actions) states.++### 2. Using Memlab to Find Leaks (Recommended)++Once you have generated `.heapsnapshot` files using `take_memory_snapshot`, use `memlab` to automatically find memory leaks.++- Read [references/memlab.md](references/memlab.md) for how to use `memlab` to analyze the generated heapsnapshots.+- Do **not** read raw `.heapsnapshot` files using `read_file` or `cat`.++### 3. Identifying Common Leaks++When you have found a leak trace (e.g., via `memlab` output), you must identify the root cause in the code.++- Read [references/common-leaks.md](references/common-leaks.md) for examples of common memory leaks and how to fix them.++### 4. Fallback: Comparing Snapshots Manually++If `memlab` is not available, you MUST use the fallback script in the references directory to compare two `.heapsnapshot` files and identify the top growing objects and common leak types.++Run the script using Node.js:++```bash+node compare_snapshots.js <baseline.heapsnapshot> <target.heapsnapshot>+```++The script will analyze and output the top growing objects by size and highlight the 3 most common types of memory leaks (e.g., Detached DOM nodes, closures, Contexts) if they are present.diff --git a/skills/memory-leak-debugging/references/common-leaks.md b/skills/memory-leak-debugging/references/common-leaks.mdnew file mode 100644index 00000000..3220786d--- /dev/null+++ b/skills/memory-leak-debugging/references/common-leaks.md@@ -0,0 +1,33 @@+# Common Memory Leaks++When analyzing a retainer trace from `memlab`, look for these common patterns in the codebase:++## 1. Uncleared Event Listeners++Event listeners attached to global objects (like `window` or `document`) or long-living objects prevent garbage collection of the objects referenced in their callbacks.++**Fix:** Always call `removeEventListener` when a component unmounts or the listener is no longer needed.++## 2. Detached DOM Nodes++A DOM node is removed from the document tree but is still referenced by a JavaScript variable. While detachedness is a good signal for a memory leak, it's not always a bug. For example, websites sometimes intentionally cache detached navigation trees.++**Fix:** Signal the detached nodes to the user first. **Ask the user first** before nulling the references or changing the code, as the detached nodes might be part of an intentional cache. If confirmed as a leak, ensure variables holding DOM references are set to `null` when the node is removed, or limit their scope.++## 3. Unintentional Global Variables++Variables declared without `var`, `let`, or `const` (in non-strict mode) or explicitly attached to `window` remain in memory forever.++**Fix:** Use strict mode, properly declare variables, and avoid global state.++## 4. Closures++Closures can unintentionally keep references to large objects in their outer scope.++**Fix:** Nullify large objects when they are no longer needed, or refactor the closure to not capture unnecessary variables.++## 5. Unbounded Caches or Arrays++Data structures used for caching (like objects, Arrays, or Maps) that grow without limits.++**Fix:** Implement caching limits, use LRU caches, or use `WeakMap`/`WeakSet` for data associated with object lifecycles.diff --git a/skills/memory-leak-debugging/references/compare_snapshots.js b/skills/memory-leak-debugging/references/compare_snapshots.jsnew file mode 100644index 00000000..1c1be7a8--- /dev/null+++ b/skills/memory-leak-debugging/references/compare_snapshots.js@@ -0,0 +1,109 @@+/**+ * @license+ * Copyright 2025 Google LLC+ * SPDX-License-Identifier: Apache-2.0+ */++import * as fs from 'node:fs';++function parseSnapshot(filePath) {+ console.log(`Loading ${filePath}...`);+ const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));+ const strings = data.strings;+ const nodes = data.nodes;+ const nodeFields = data.snapshot.meta.node_fields;+ const nodeFieldCount = nodeFields.length;++ const typeOffset = nodeFields.indexOf('type');+ const nameOffset = nodeFields.indexOf('name');+ const sizeOffset = nodeFields.indexOf('self_size');++ const nodeTypes = data.snapshot.meta.node_types[typeOffset];++ const counts = {};+ const sizes = {};++ for (let i = 0; i < nodes.length; i += nodeFieldCount) {+ const typeIdx = nodes[i + typeOffset];+ const typeName = nodeTypes[typeIdx];+ const nameIdx = nodes[i + nameOffset];+ const name = typeof nameIdx === 'number' ? strings[nameIdx] : nameIdx;+ const size = nodes[i + sizeOffset];++ // Ignore native primitives/arrays that clutter the output unless specifically looking for them+ if (+ typeName === 'string' ||+ typeName === 'number' ||+ typeName === 'array'+ ) {+ continue;+ }++ const key = `${typeName}::${name}`;+ counts[key] = (counts[key] || 0) + 1;+ sizes[key] = (sizes[key] || 0) + size;+ }+ return {counts, sizes};+}++const [, , file1, file2] = process.argv;+if (!file1 || !file2) {+ console.error(+ 'Usage: node compare_snapshots.js <baseline.heapsnapshot> <target.heapsnapshot>',+ );+ process.exit(1);+}++try {+ const snap1 = parseSnapshot(file1);+ const snap2 = parseSnapshot(file2);++ const diffs = [];+ for (const key in snap2.counts) {+ const count1 = snap1.counts[key] || 0;+ const count2 = snap2.counts[key];+ const size1 = snap1.sizes[key] || 0;+ const size2 = snap2.sizes[key];++ if (count2 > count1) {+ diffs.push({+ key,+ countDiff: count2 - count1,+ sizeDiff: size2 - size1,+ });+ }+ }++ diffs.sort((a, b) => b.sizeDiff - a.sizeDiff);++ console.log('\n--- Top 10 growing objects by size ---');+ diffs.slice(0, 10).forEach(d => {+ console.log(`${d.key}: +${d.countDiff} objects, +${d.sizeDiff} bytes`);+ });++ // Look for common leak indicators+ const commonLeaks = diffs.filter(+ d =>+ d.key.toLowerCase().includes('detached') ||+ d.key.toLowerCase().includes('html') ||+ d.key.toLowerCase().includes('eventlistener') ||+ d.key.toLowerCase().includes('context') ||+ d.key.toLowerCase().includes('closure'),+ );++ commonLeaks.sort((a, b) => b.countDiff - a.countDiff);++ console.log('\n--- Top 3 most common types of memory leaks found ---');+ if (commonLeaks.length === 0) {+ console.log('No common DOM or Closure leaks detected.');+ } else {+ commonLeaks.slice(0, 3).forEach(d => {+ console.log(`${d.key}: +${d.countDiff} objects, +${d.sizeDiff} bytes`);+ });+ }+} catch (error) {+ console.error(+ 'Error parsing snapshots. They might be too large for JSON.parse or invalid.',+ );+ console.error(error.message);+}diff --git a/skills/memory-leak-debugging/references/memlab.md b/skills/memory-leak-debugging/references/memlab.mdnew file mode 100644index 00000000..207efdbb--- /dev/null+++ b/skills/memory-leak-debugging/references/memlab.md@@ -0,0 +1,29 @@+# Using Memlab++[Memlab](https://facebook.github.io/memlab/) is an E2E testing and analysis framework for finding JavaScript memory leaks.++## Important Rule++**NEVER read raw `.heapsnapshot` files directly.** They are too large and will exceed context limits. Always use `memlab` commands to analyze them.++## Analyzing Snapshots++You can use the `take_memory_snapshot` tool provided by the `chrome-devtools-mcp` extension to generate heap snapshots during an investigation. To find leaks, you generally need 3 snapshots:++1. **Baseline:** Before the suspect action.+2. **Target:** After the suspect action.+3. **Final:** After reverting the suspect action (e.g., closing a modal, navigating away).++Once you have these 3 snapshots saved to disk, you can use `memlab` to find leaks:++```bash+npx memlab find-leaks --baseline <path-to-baseline> --target <path-to-target> --final <path-to-final>+```++You can also parse a single snapshot to find the largest objects or explore it individually:++```bash+npx memlab analyze snapshot --snapshot <path-to-snapshot>+```++Memlab will output the retainer traces for identified leaks. Use these traces to guide your search in the codebase.