MemLab - JavaScript Memory Leak Detection Framework

2.0.1 verified Sat Apr 25 auth: no javascript

MemLab is an end-to-end testing and analysis framework for identifying JavaScript memory leaks and optimization opportunities. Version 2.0.1 is the latest stable release, actively maintained by Meta. It provides automated browser memory leak detection using Puppeteer, a heap snapshot analysis API for Node.js/Electron/Hermes, and CLI tools for memory debugging. Key differentiators: supports custom leak detectors, object-oriented heap traversing, and integrates with unit testing. MemLab goes beyond simple heap dump analysis by automatically comparing snapshots and filtering leaks with retainer traces.

Common errors

error TypeError: memlab.run is not a function ↓

cause Using require() instead of import for ESM-only package.

fix

Replace const memlab = require('memlab') with import memlab from 'memlab'.

error Error: Cannot find module 'puppeteer' ↓

cause Puppeteer is an optional peer dependency not installed.

fix

Run npm install --save-dev puppeteer to install it.

error Error: The 'back' action must be a function ↓

cause Missing or invalid 'back' function in scenario object.

fix

Define an async 'back' function that returns to the pre-action state.

error Error: EACCES: permission denied, mkdir '/tmp/memlab' ↓

cause MemLab uses /tmp for snapshot storage; may lack permissions.

fix

Override work directory with memlab.setWorkDir('/custom/path') or run with sudo.

Warnings

breaking MemLab v2 drops CommonJS support; only ESM imports work. ↓

fix Use import syntax instead of require().

breaking The CLI 'memlab run' command changed its argument from --browser to --runner in v2. ↓

fix Use '--runner puppeteer' instead of '--browser puppeteer'.

deprecated Function 'createBrowserlessScenario' is deprecated in v2. Use the object-based scenario format. ↓

fix Define scenario as {url, action, back} instead.

gotcha Heap snapshot files can be very large (multiple GB). Ensure sufficient disk space. ↓

fix Monitor disk usage; consider using --max-snapshots option to limit files.

gotcha MemLab runs Puppeteer in headless mode by default; some sites may require full browser. ↓

fix Set headless: false in Puppeteer launch options within scenario.

gotcha Retainer traces may be unavailable if minified code is served; use source maps. ↓

fix Ensure the website serves non-minified code or source maps for readable traces.

Install

npm install memlab

yarn add memlab

pnpm add memlab

Imports

memlab
wrong
```
const memlab = require('memlab')
```
correct
```
import memlab from 'memlab'
```
MemLab is ESM-only since v2; CJS require will fail.

IScenario

wrong

import IScenario from 'memlab'

correct

import { IScenario } from 'memlab'

Type-only export; must use named import.

takeHeapSnapshot

wrong

import takeHeapSnapshot from 'memlab'

correct

import { takeHeapSnapshot } from 'memlab'

Named export for heap snapshot API.

Quickstart

Demonstrates using MemLab's programmatic API to define a scenario and run browser memory leak detection.

import memlab from 'memlab';
import fs from 'fs';

// Define a scenario as an object with url, action, back functions
const scenario = {
  url: () => 'https://example.com',
  async action(page) {
    await page.click('button#load-more');
  },
  async back(page) {
    await page.click('button#reset');
  }
};

async function runLeakDetection() {
  // Run leak detection with default options
  const result = await memlab.run(scenario);
  console.log(`Leaks found: ${result.leaks.length}`);
  for (const leak of result.leaks) {
    console.log(`Retained size: ${leak.retainedSize}`);
  }
}

runLeakDetection().catch(console.error);