Openclaw Test Heap Leaks
Investigate OpenClaw pnpm test memory growth, Vitest OOMs, RSS spikes, and heap snapshot deltas.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Openclaw Test Heap Leaks when an AI agent needs a reusable SKILL.md workflow for this job: Investigate OpenClaw pnpm test memory growth, Vitest OOMs, RSS spikes, and heap snapshot deltas.
When not to use it
Skip Openclaw Test Heap Leaks when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/openclaw-test-heap-leaks # Save SKILL.md to ~/.claude/skills/openclaw-test-heap-leaks/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/openclaw-test-heap-leaks/SKILL.md. For a shared project, commit the folder at .claude/skills/openclaw-test-heap-leaks/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Openclaw Test Heap Leaks skill for this task: Reproduce the failing shape first. Confirm any required inputs or files before making changes.
What supports this recommendation?
80/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 84/100
- Practical detail
- 92/100
- Source evidence
- 63/100
- Source signals
- 72/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# OpenClaw Test Heap Leaks
Use this skill for test-memory investigations. Do not guess from RSS alone when heap snapshots are available. Treat snapshot-name deltas as triage evidence, not proof, until retainers or dominators support the call.
Read `../openclaw-test-performance/SKILL.md` first for the current test-performance commands and proof routing.
For **runtime fixes** (e.g., closure leaks in long-running services like the gateway), see [Validating runtime fixes](#validating-runtime-fixes-not-test-memory) below — that uses a dedicated harness rather than the unit-test profiling workflow.
## Workflow
1. Reproduce the failing shape first. - Match the real entrypoint and worker budget. For a broad unit-fast baseline with per-config max RSS and top-file timing, start with:
```bash pnpm test:perf:groups \ --config test/vitest/vitest.unit-fast.config.ts \ --allow-failures \ --output .artifacts/test-perf/unit-fast-memory.json ```
- For a suspected file, rerun that file with one worker and collect wall/RSS evidence: `/usr/bin/time -l pnpm test <file> --maxWorkers=1 --reporter=verbose`. - Current `pnpm test` execution is planned by `scripts/test-projects.mts`. Record the printed Vitest config or shard and preserve that shape when the report is configuration- or worker-budget-specific.
2. Collect the strongest available heap evidence. - Run `pnpm test:perf:profile:runner -- --output-dir .artifacts/test-perf/vitest-runner-profile -- <file>` for a CPU profile plus a sampling heap profile of the unit runner. Open the heap profile in DevTools and inspect the largest allocation families. - Sampling `.heapprofile` output is not a `.heapsnapshot`; do not pass it to the snapshot delta helper. - When a dedicated harness or another known producer emits repeated `.heapsnapshot` files, compare snapshots from the same PID with `.agents/skills/openclaw-test-heap-leaks/scripts/heapsnapshot-delta.mjs`. - If no snapshot or heap profile is available, RSS growth is useful triage evidence, but keep the leak classification inconclusive.
3. Classify the growth before choosing a fix. - If growth is dominated by Vite/Vitest transformed source strings, `Module`, `system / Context`, bytecode, descriptor arrays, or property maps, treat it as likely retained module graph growth in long-lived workers. - If growth is dominated by app objects, caches, buffers, server handles, timers, mock state, sqlite state, or similar runtime objects, treat it as a likely cleanup or lifecycle leak. - If the names are ambiguous, stop short of a confident label and inspect retainers/dominators in DevTools for the top deltas.
4. Fix the right layer. - For likely retained transformed-module growth in shared workers: - Inspect the owning Vitest config and the process chunking in `scripts/test-projects.test-support.mjs`. Fix process lifetime or project ownership there only when the same-shape evidence shows that shared-worker retention is the cause. - `test/vitest/vitest.unit-fast-isolated.config.ts` is for audited stateful tests that need a fresh module graph. Do not use it as a generic memory-hotspot list. - For real leaks: - Patch the implicated test or runtime cleanup path. - Look for missing `afterEach`/`afterAll`, module-reset gaps, retained global state, unreleased DB handles, or listeners/timers that survive the file.
5. Verify with the most direct proof. - Re-run the same grouped or scoped command and confirm the max-RSS trend or OOM is reduced. - When a dedicated producer emits heap profiles or snapshots, repeat the same producer and compare equivalent artifacts. - For routing or config changes, verify the expected Vitest config or shard starts and the affected tests complete.
## Heuristics
- Do not call everything a leak. Growth in a non-isolated shared Vitest project can be a worker-lifetime problem rather than an application object leak. - `scripts/test-projects.mts`, `scripts/test-group-report.mts`, and `scripts/run-vitest-profile.mts` are the current execution, grouped-RSS, and profile entrypoints. - The `[test] starting ...` lines identify the Vitest config or shard to reproduce. - `.artifacts/vitest-shard-timings.json` stores config/shard durations for scheduling. It is not a file-level memory-hotspot or behavior manifest. - When the same retained object families grow across multiple intervals in the same worker PID, trust the snapshots over intuition, then confirm ambiguous calls with retainer evidence.
## Snapshot Comparison
- Direct comparison: - `node .agents/skills/openclaw-test-heap-leaks/scripts/heapsnapshot-delta.mjs before.heapsnapshot after.heapsnapshot` - Auto-select earliest/latest snapshots per PID within one lane: - `node .agents/skills/openclaw-test-heap-leaks/scripts/heapsnapshot-delta.mjs --lane-dir <snapshot-directory>` - Useful flags: - `--top 40` - `--min-kb 32` - `--pid 16133`
Read the top positive deltas first. Large positive growth in module-transform artifacts points to shared-process lifetime or project ownership; large positive growth in runtime objects suggests a real leak. If the names alone do not settle it, open the same snapshot pair in DevTools and inspect retainers/dominators for the top rows before declaring root cause.
## Validating runtime fixes (not test-memory)
The workflow above is for diagnosing Vitest worker memory growth. For validating that a runtime/closure fix actually releases captured state, use the dedicated harness:
- `pnpm leak:embedded-run` — runs `scripts/embedded-run-abort-leak.ts`. Loops N aborted runs in a function-shaped scope mimicking `runEmbeddedAttempt`, writes heap snapshots, and reports a PASS/FAIL verdict on retention growth using `FinalizationRegistry` for tracked-instance counting plus RSS delta.
Modes:
- `closure-extracted` (default) — production fix shape (helper at module scope). - `closure-inline` — pre-fix shape (closure inside the runner scope). Use as a sensitivity check: if it passes you've broken the harness, not fixed a bug. - `synthetic-leak` — deliberately retains via a module-level bucket. Use to confirm the harness can detect leaks before trusting a PASS on a real fix.
Snapshots land in `.tmp/embedded-run-abort-leak/`. Diff with the same script as above:
``` node .agents/skills/openclaw-test-heap-leaks/scripts/heapsnapshot-delta.mjs \ .tmp/embedded-run-abort-leak/baseline-*.heapsnapshot \ .tmp/embedded-run-abort-leak/batch-N-*.heapsnapshot --top 30 ```
When fixing a different runtime leak, add a new harness alongside this one rather than retrofitting it. The fixture function should mimic the lexical scope of the function where the leak lives, not be a generic abort-loop.
## Output Expectations
When using this skill, report:
- The exact reproduce command. - Which Vitest config or target was reproduced, and which PID was compared when snapshots were available. - The dominant retained object families from the heap profile or snapshot delta, when available. - Whether the issue is a likely real leak or likely shared-worker retained module growth, plus whether retainers/dominators confirmed it. - The concrete fix or impact-reduction patch. - What you verified, and what snapshot overhead prevented you from verifying.
Intended uses
- Reproduce the failing shape first.
- Match the real entrypoint and worker budget. For a broad unit-fast baseline with per-config max RSS and top-file timing, start with:
- For a suspected file, rerun that file with one worker and collect wall/RSS evidence: /usr/bin/time -l pnpm test <file> --maxWorkers=1 --reporter=verbose.
- Current pnpm test execution is planned by scripts/test-projects.mts. Record the printed Vitest config or shard and preserve that shape when the report is configuration- or worker-budget-specific.
- Collect the strongest available heap evidence.
- Run pnpm test:perf:profile:runner -- --output-dir .artifacts/test-perf/vitest-runner-profile -- <file> for a CPU profile plus a sampling heap profile of the unit runner. Open the heap profile in DevTools and inspect the largest allocation families.
- Sampling .heapprofile output is not a .heapsnapshot; do not pass it to the snapshot delta helper.
- When a dedicated harness or another known producer emits repeated .heapsnapshot files, compare snapshots from the same PID with .agents/skills/openclaw-test-heap-leaks/scripts/heapsnapshot-delta.mjs.
- If no snapshot or heap profile is available, RSS growth is useful triage evidence, but keep the leak classification inconclusive.
- Classify the growth before choosing a fix.
- If growth is dominated by Vite/Vitest transformed source strings, Module, system / Context, bytecode, descriptor arrays, or property maps, treat it as likely retained module graph growth in long-lived workers.
- If growth is dominated by app objects, caches, buffers, server handles, timers, mock state, sqlite state, or similar runtime objects, treat it as a likely cleanup or lifecycle leak.
- If the names are ambiguous, stop short of a confident label and inspect retainers/dominators in DevTools for the top deltas.
- Fix the right layer.
- For likely retained transformed-module growth in shared workers:
- Inspect the owning Vitest config and the process chunking in scripts/test-projects.test-support.mjs. Fix process lifetime or project ownership there only when the same-shape evidence shows that shared-worker retention is the cause.
- test/vitest/vitest.unit-fast-isolated.config.ts is for audited stateful tests that need a fresh module graph. Do not use it as a generic memory-hotspot list.
- For real leaks:
- Patch the implicated test or runtime cleanup path.
- Look for missing afterEach/afterAll, module-reset gaps, retained global state, unreleased DB handles, or listeners/timers that survive the file.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.