test(test-utils): Add MemoryProfiler for heap snapshot testing via CDP (#20555)

Adds CDPClient and MemoryProfiler to test-utils for V8 heap profiling.
This PR prevents #20407 entirely by comparing heap snapshots.

Within a Playwright test following can now be used:

```ts
const profiler = new MemoryProfiler({ port: INSPECTOR_PORT });

await profiler.connect();

// ... make initial requests to let the runtime settle ...

const baselineSnapshot = await profiler.takeHeapSnapshot();

// ... run some operations that might leak memory ...

const finalSnapshot = await profiler.takeHeapSnapshot();
const result = profiler.compareSnapshots(baselineSnapshot, finalSnapshot);

expect(result.nodeGrowthPercent).toBeLessThan(1);

await profiler.close();
```

This works by using the Chrome Developer Protocol (CDP). There is also a
[CDPSession](https://playwright.dev/docs/api/class-cdpsession) API
available from Playwright, but that would only work for sessions which
run in the browser. Theoretically, this could also work in integration
tests, but the idea is that this could in the future also be extended to
use the CDPSession from Playwright for browser tests.

Author: JPeer264

dev-packages/e2e-tests/test-applications/cloudflare-workers/playwright.config.ts

@@ -6,10 +6,11 @@ if (!testEnv) {
 }
 
 const APP_PORT = 38787;
+export const INSPECTOR_PORT = 9230;
 
 const config = getPlaywrightConfig(
   {
-    startCommand: `pnpm dev --port ${APP_PORT}`,
+    startCommand: `pnpm dev --port ${APP_PORT} --inspector-port ${INSPECTOR_PORT}`,
     port: APP_PORT,
   },
   {

dev-packages/e2e-tests/test-applications/cloudflare-workers/tests/memory.test.ts

@@ -0,0 +1,31 @@
+import { MemoryProfiler } from '@sentry-internal/test-utils';
+import { expect, test } from '@playwright/test';
+import { INSPECTOR_PORT } from '../playwright.config';
+
+test.describe('Worker V8 isolate memory tests', () => {
+  test('worker memory is reclaimed after GC', async ({ baseURL }) => {
+    const profiler = new MemoryProfiler({ port: INSPECTOR_PORT });
+
+    // Warm up: make initial requests and let the runtime settle
+    for (let i = 0; i < 5; i++) {
+      await fetch(baseURL!);
+    }
+
+    await profiler.connect();
+
+    const baselineSnapshot = await profiler.takeHeapSnapshot();
+
+    for (let i = 0; i < 50; i++) {
+      const res = await fetch(baseURL!);
+      expect(res.status).toBe(200);
+      await res.text();
+    }
+
+    const finalSnapshot = await profiler.takeHeapSnapshot();
+    const result = profiler.compareSnapshots(baselineSnapshot, finalSnapshot);
+
+    expect(result.nodeGrowthPercent).toBeLessThan(1);
+
+    await profiler.close();
+  });
+});

dev-packages/test-utils/package.json

@@ -44,11 +44,13 @@
     "@playwright/test": "~1.56.0"
   },
   "dependencies": {
-    "express": "^4.21.2"
+    "express": "^4.21.2",
+    "ws": "^8.20.0"
   },
   "devDependencies": {
     "@playwright/test": "~1.56.0",
     "@sentry/core": "10.51.0",
+    "@types/ws": "^8.18.1",
     "eslint-plugin-regexp": "^1.15.0"
   },
   "volta": {

dev-packages/test-utils/src/cdp-client.ts

@@ -0,0 +1,310 @@
+import { WebSocket } from 'ws';
+
+/**
+ * Configuration options for the Chrome Developer Protocol (CDP) client.
+ */
+export interface CDPClientOptions {
+  /**
+   * WebSocket URL to connect to (e.g., 'ws://127.0.0.1:9229/ws').
+   * Can also use the format 'ws://host:port' without path for standard V8 inspector.
+   */
+  url: string;
+
+  /**
+   * Number of connection retry attempts before giving up.
+   * @default 5
+   */
+  retries?: number;
+
+  /**
+   * Delay in milliseconds between retry attempts.
+   * @default 1000
+   */
+  retryDelayMs?: number;
+
+  /**
+   * Connection timeout in milliseconds.
+   * @default 10000
+   */
+  connectionTimeoutMs?: number;
+
+  /**
+   * Default timeout for CDP method calls in milliseconds.
+   * @default 30000
+   */
+  defaultTimeoutMs?: number;
+
+  /**
+   * Whether to log debug messages.
+   * @default false
+   */
+  debug?: boolean;
+}
+
+interface CDPResponse {
+  id?: number;
+  method?: string;
+  params?: unknown;
+  error?: { message: string };
+  result?: unknown;
+}
+
+interface PendingRequest {
+  resolve: (value: unknown) => void;
+  reject: (error: Error) => void;
+}
+
+type EventHandler = (params: unknown) => void;
+
+/**
+ * Low-level CDP client for connecting to V8 inspector endpoints.
+ *
+ * For memory profiling, prefer using `MemoryProfiler` which provides a higher-level API.
+ *
+ * @example
+ * ```typescript
+ * const cdp = new CDPClient({ url: 'ws://127.0.0.1:9229/ws' });
+ * await cdp.connect();
+ * await cdp.send('Runtime.enable');
+ * await cdp.close();
+ * ```
+ */
+export class CDPClient {
+  #ws: WebSocket | null;
+  #messageId: number;
+  #pendingRequests: Map<number, PendingRequest>;
+  #eventHandlers: Map<string, Set<EventHandler>>;
+  #connected: boolean;
+  readonly #options: Required<CDPClientOptions>;
+
+  public constructor(options: CDPClientOptions) {
+    this.#ws = null;
+    this.#messageId = 0;
+    this.#pendingRequests = new Map();
+    this.#eventHandlers = new Map();
+    this.#connected = false;
+    this.#options = {
+      retries: 5,
+      retryDelayMs: 1000,
+      connectionTimeoutMs: 10000,
+      defaultTimeoutMs: 30000,
+      debug: false,
+      ...options,
+    };
+  }
+
+  /**
+   * Connect to the V8 inspector WebSocket endpoint.
+   * Will retry according to the configured retry settings.
+   */
+  public async connect(): Promise<void> {
+    const { retries, retryDelayMs } = this.#options;
+
+    for (let attempt = 1; attempt <= retries; attempt++) {
+      try {
+        await this.#tryConnect();
+        return;
+      } catch (err) {
+        this.#log(`Connection attempt ${attempt}/${retries} failed:`, (err as Error).message);
+        if (attempt < retries) {
+          await new Promise(resolve => setTimeout(resolve, retryDelayMs));
+        } else {
+          throw err;
+        }
+      }
+    }
+  }
+
+  /**
+   * Send a CDP method call and wait for the response.
+   *
+   * @param method - The CDP method name (e.g., 'HeapProfiler.enable')
+   * @param params - Optional parameters for the method
+   * @param timeoutMs - Timeout in milliseconds (defaults to configured defaultTimeoutMs)
+   * @returns The result from the CDP method
+   */
+  public async send<T = unknown>(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T> {
+    if (!this.#ws || this.#ws.readyState !== WebSocket.OPEN) {
+      throw new Error('WebSocket not connected');
+    }
+
+    const timeout = timeoutMs ?? this.#options.defaultTimeoutMs;
+    const id = ++this.#messageId;
+    const message = JSON.stringify({ id, method, params });
+
+    this.#log('Sending:', method, params || '');
+
+    return new Promise((resolve, reject) => {
+      this.#pendingRequests.set(id, {
+        resolve: value => resolve(value as T),
+        reject,
+      });
+      this.#ws!.send(message);
+
+      setTimeout(() => {
+        if (this.#pendingRequests.has(id)) {
+          this.#pendingRequests.delete(id);
+          reject(new Error(`CDP request ${method} timed out after ${timeout}ms`));
+        }
+      }, timeout);
+    });
+  }
+
+  /**
+   * Send a CDP method call without waiting for a response.
+   * Useful for commands that may not return responses in certain V8 environments.
+   *
+   * @param method - The CDP method name
+   * @param params - Optional parameters for the method
+   * @param settleDelayMs - Time to wait after sending (default: 100ms)
+   */
+  public async sendFireAndForget(method: string, params?: Record<string, unknown>, settleDelayMs = 100): Promise<void> {
+    if (!this.#ws || this.#ws.readyState !== WebSocket.OPEN) {
+      throw new Error('WebSocket not connected');
+    }
+
+    const id = ++this.#messageId;
+    const message = JSON.stringify({ id, method, params });
+
+    this.#log('Sending (fire-and-forget):', method, params || '');
+
+    this.#ws.send(message);
+
+    // Give the command time to execute
+    await new Promise(resolve => setTimeout(resolve, settleDelayMs));
+  }
+
+  /**
+   * Register a handler for a CDP event method (e.g., 'HeapProfiler.addHeapSnapshotChunk').
+   * Returns a function that, when called, removes the handler.
+   */
+  public on(method: string, handler: EventHandler): () => void {
+    let handlers = this.#eventHandlers.get(method);
+    if (!handlers) {
+      handlers = new Set();
+      this.#eventHandlers.set(method, handlers);
+    }
+    handlers.add(handler);
+
+    return () => {
+      handlers.delete(handler);
+      if (handlers.size === 0) {
+        this.#eventHandlers.delete(method);
+      }
+    };
+  }
+
+  /**
+   * Check if the client is currently connected.
+   */
+  public isConnected(): boolean {
+    return this.#connected && this.#ws?.readyState === WebSocket.OPEN;
+  }
+
+  /**
+   * Close the WebSocket connection.
+   */
+  public async close(): Promise<void> {
+    if (this.#ws) {
+      this.#ws.close();
+      this.#ws = null;
+      this.#connected = false;
+    }
+  }
+
+  #log(...args: unknown[]): void {
+    if (this.#options.debug) {
+      // eslint-disable-next-line no-console
+      console.log('[CDPClient]', ...args);
+    }
+  }
+
+  async #tryConnect(): Promise<void> {
+    const { url, connectionTimeoutMs } = this.#options;
+
+    return new Promise((resolve, reject) => {
+      this.#ws = new WebSocket(url);
+
+      const timeoutId = setTimeout(() => {
+        // Close the WebSocket to prevent state corruption from orphaned sockets on retry
+        this.#ws?.close();
+        reject(new Error(`Connection to ${url} timed out after ${connectionTimeoutMs}ms`));
+      }, connectionTimeoutMs);
+
+      this.#ws.on('open', () => {
+        clearTimeout(timeoutId);
+        this.#connected = true;
+        this.#log('WebSocket connected to', url);
+        resolve();
+      });
+
+      this.#ws.on('error', (err: Error) => {
+        clearTimeout(timeoutId);
+        this.#ws?.close();
+        reject(new Error(`Failed to connect to inspector at ${url}: ${err.message}`));
+      });
+
+      this.#ws.on('close', () => {
+        this.#connected = false;
+      });
+
+      this.#setupMessageHandler();
+    });
+  }
+
+  #setupMessageHandler(): void {
+    this.#ws?.on('message', (data: Buffer) => {
+      try {
+        const rawMessage = data.toString();
+        this.#log('Received raw message:', rawMessage.slice(0, 500));
+
+        const message = JSON.parse(rawMessage) as CDPResponse;
+
+        if (message.method) {
+          this.#handleCdpEvent(message);
+          return;
+        }
+
+        if (message.id !== undefined) {
+          this.#handleCdpResponse(message);
+        }
+      } catch (e) {
+        this.#log('Failed to parse CDP message:', e);
+      }
+    });
+  }
+
+  #handleCdpEvent(message: CDPResponse): void {
+    this.#log('CDP event:', message.method);
+
+    const handlers = this.#eventHandlers.get(message.method!);
+
+    if (handlers) {
+      for (const handler of handlers) {
+        try {
+          handler(message.params);
+        } catch (err) {
+          this.#log('Event handler threw:', err);
+        }
+      }
+    }
+  }
+
+  #handleCdpResponse(message: CDPResponse): void {
+    this.#log('CDP response for id:', message.id, 'error:', message.error, 'has result:', message.result !== undefined);
+
+    const pending = this.#pendingRequests.get(message.id!);
+
+    if (pending) {
+      this.#pendingRequests.delete(message.id!);
+
+      if (message.error) {
+        pending.reject(new Error(`CDP error: ${message.error.message}`));
+      } else {
+        pending.resolve(message.result);
+      }
+    } else {
+      this.#log('No pending request found for id:', message.id);
+    }
+  }
+}

dev-packages/test-utils/src/index.ts

@@ -20,3 +20,9 @@ export { createBasicSentryServer, createTestServer } from './server';
 export { startMockSentryServer } from './mock-sentry-server';
 export type { MockSentryServerOptions, MockSentryServer } from './mock-sentry-server';
 export * from './sourcemap-upload-utils';
+
+export { CDPClient } from './cdp-client';
+export type { CDPClientOptions } from './cdp-client';
+
+export { MemoryProfiler } from './memory-profiler';
+export type { MemoryProfilerOptions, SnapshotStats, SnapshotComparisonResult } from './memory-profiler';