@viewscript/renderer 0.1.0-202605140639

package/tests/e2e/memory-stability.spec.ts

@@ -0,0 +1,396 @@
+/**
+ * Memory Stability E2E Tests
+ *
+ * This module verifies that the WASM Resource Manager correctly prevents
+ * memory leaks during sustained HMR operations.
+ *
+ * ## Test Strategy
+ *
+ * 1. Measure baseline WASM heap size
+ * 2. Simulate 10,000 HMR patches (entity add/remove cycles)
+ * 3. Force garbage collection
+ * 4. Flush FinalizationRegistry cleanup queue
+ * 5. Measure final WASM heap size
+ * 6. Assert: |final - baseline| < 1MB
+ *
+ * ## Why This Matters
+ *
+ * Without explicit WASM resource management, each HMR patch that creates
+ * GPU objects (PaintSpec, PathEntity) would leak memory. Over a dev session
+ * with thousands of hot reloads, this could exhaust available memory.
+ */
+
+import { test, expect, type Page, type CDPSession } from '@playwright/test';
+
+// =============================================================================
+// Configuration
+// =============================================================================
+
+const CONFIG = {
+  /** Number of HMR patch cycles to simulate */
+  HMR_CYCLES: 10000,
+
+  /** Entities per patch (add then remove) */
+  ENTITIES_PER_PATCH: 5,
+
+  /** Maximum allowed heap growth (bytes) */
+  MAX_HEAP_GROWTH_BYTES: 1024 * 1024, // 1MB
+
+  /** Delay between patches (ms) - 0 for stress test */
+  PATCH_DELAY_MS: 0,
+
+  /** GC attempts before final measurement */
+  GC_ATTEMPTS: 3,
+};
+
+// =============================================================================
+// Types
+// =============================================================================
+
+interface MemoryMetrics {
+  jsHeapSizeUsed: number;
+  jsHeapSizeTotal: number;
+  wasmHeapEstimate: number;
+  timestamp: number;
+}
+
+interface TestResult {
+  baselineMemory: MemoryMetrics;
+  finalMemory: MemoryMetrics;
+  heapGrowth: number;
+  resourceStats: {
+    allocated: number;
+    released: number;
+    leaked: number;
+  };
+  passed: boolean;
+}
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+test.describe('Memory Stability: WASM Resource Management', () => {
+  test.setTimeout(300000); // 5 minutes for stress test
+
+  /**
+   * Core stability test: 10,000 HMR cycles without memory leak.
+   */
+  test('maintains stable memory through 10,000 HMR cycles', async ({ page }) => {
+    const cdp = await page.context().newCDPSession(page);
+    await setupTestPage(page);
+
+    // Enable performance instrumentation
+    await cdp.send('Performance.enable');
+
+    // Phase 1: Measure baseline
+    await forceGC(cdp);
+    const baseline = await measureMemory(page, cdp);
+    console.log(`[Baseline] JS Heap: ${formatBytes(baseline.jsHeapSizeUsed)}`);
+
+    // Phase 2: Run HMR stress test
+    console.log(`[Stress Test] Running ${CONFIG.HMR_CYCLES} HMR cycles...`);
+    const resourceStats = await runHMRStressTest(page, CONFIG.HMR_CYCLES);
+
+    // Phase 3: Force cleanup
+    await forceGC(cdp);
+    await flushFinalizationRegistry(page);
+    await forceGC(cdp);
+
+    // Phase 4: Measure final
+    const final = await measureMemory(page, cdp);
+    console.log(`[Final] JS Heap: ${formatBytes(final.jsHeapSizeUsed)}`);
+
+    // Phase 5: Calculate and assert
+    const heapGrowth = final.jsHeapSizeUsed - baseline.jsHeapSizeUsed;
+    const result: TestResult = {
+      baselineMemory: baseline,
+      finalMemory: final,
+      heapGrowth,
+      resourceStats,
+      passed: heapGrowth < CONFIG.MAX_HEAP_GROWTH_BYTES,
+    };
+
+    console.log('=== Memory Stability Report ===');
+    console.log(`Baseline:    ${formatBytes(baseline.jsHeapSizeUsed)}`);
+    console.log(`Final:       ${formatBytes(final.jsHeapSizeUsed)}`);
+    console.log(`Growth:      ${formatBytes(heapGrowth)}`);
+    console.log(`Allocated:   ${resourceStats.allocated}`);
+    console.log(`Released:    ${resourceStats.released}`);
+    console.log(`Leaked:      ${resourceStats.leaked}`);
+    console.log(`Limit:       ${formatBytes(CONFIG.MAX_HEAP_GROWTH_BYTES)}`);
+    console.log(`Result:      ${result.passed ? 'PASS' : 'FAIL'}`);
+
+    // Assertions
+    expect(heapGrowth).toBeLessThan(CONFIG.MAX_HEAP_GROWTH_BYTES);
+    expect(resourceStats.leaked).toBe(0);
+  });
+
+  /**
+   * Verify FinalizationRegistry actually triggers cleanup.
+   */
+  test('FinalizationRegistry releases orphaned resources', async ({ page }) => {
+    await setupTestPage(page);
+
+    // Create resources without explicit release
+    const orphanCount = await page.evaluate(() => {
+      const manager = (window as any).__VS_RESOURCE_MANAGER__;
+      const mockResources: any[] = [];
+
+      // Create 100 mock WASM resources
+      for (let i = 0; i < 100; i++) {
+        const mock = {
+          deleted: false,
+          delete() { this.deleted = true; },
+          isDeleted() { return this.deleted; },
+        };
+        manager.register(mock, 'paint', i);
+        mockResources.push(mock);
+      }
+
+      // Clear references (make them GC-eligible)
+      mockResources.length = 0;
+
+      return manager.getStats().currentActive;
+    });
+
+    // Force GC
+    const cdp = await page.context().newCDPSession(page);
+    await forceGC(cdp);
+
+    // Flush cleanup queue
+    await flushFinalizationRegistry(page);
+
+    // Check that resources were cleaned up
+    const afterCleanup = await page.evaluate(() => {
+      return (window as any).__VS_RESOURCE_MANAGER__.getStats().currentActive;
+    });
+
+    console.log(`Orphaned: ${orphanCount}, After cleanup: ${afterCleanup}`);
+
+    // Some resources may still be pending GC, but count should decrease
+    expect(afterCleanup).toBeLessThan(orphanCount);
+  });
+
+  /**
+   * Verify explicit release works correctly.
+   */
+  test('explicit release immediately frees resources', async ({ page }) => {
+    await setupTestPage(page);
+
+    const result = await page.evaluate(() => {
+      const manager = (window as any).__VS_RESOURCE_MANAGER__;
+
+      // Create and explicitly release
+      const tokens: symbol[] = [];
+      for (let i = 0; i < 50; i++) {
+        const mock = {
+          deleted: false,
+          delete() { this.deleted = true; },
+          isDeleted() { return this.deleted; },
+        };
+        tokens.push(manager.register(mock, 'path', i));
+      }
+
+      const beforeRelease = manager.getStats().currentActive;
+
+      // Release all
+      for (const token of tokens) {
+        manager.release(token);
+      }
+
+      const afterRelease = manager.getStats().currentActive;
+
+      return { beforeRelease, afterRelease };
+    });
+
+    expect(result.beforeRelease).toBe(50);
+    expect(result.afterRelease).toBe(0);
+  });
+
+  /**
+   * Verify entity-based batch release.
+   */
+  test('releaseByEntity cleans up all associated resources', async ({ page }) => {
+    await setupTestPage(page);
+
+    const result = await page.evaluate(() => {
+      const manager = (window as any).__VS_RESOURCE_MANAGER__;
+
+      // Create resources for entity 42
+      for (let i = 0; i < 10; i++) {
+        const mock = { delete() {}, isDeleted() { return false; } };
+        manager.register(mock, 'paint', 42);
+      }
+
+      // Create resources for entity 99
+      for (let i = 0; i < 10; i++) {
+        const mock = { delete() {}, isDeleted() { return false; } };
+        manager.register(mock, 'path', 99);
+      }
+
+      const before = manager.getStats().currentActive;
+
+      // Release only entity 42
+      const released = manager.releaseByEntity(42);
+
+      const after = manager.getStats().currentActive;
+
+      return { before, after, released };
+    });
+
+    expect(result.before).toBe(20);
+    expect(result.released).toBe(10);
+    expect(result.after).toBe(10);
+  });
+});
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+async function setupTestPage(page: Page): Promise<void> {
+  await page.goto('/test-harness.html', { waitUntil: 'networkidle' });
+  await page.waitForFunction(() => (window as any).__VS_RENDERER_READY__ === true);
+
+  // Initialize resource manager on page
+  await page.evaluate(() => {
+    // Simplified resource manager for testing
+    class TestResourceManager {
+      private resources = new Map<symbol, { ref: WeakRef<any>; entry: any }>();
+      private registry: FinalizationRegistry<{ token: symbol }>;
+      private cleanupQueue: symbol[] = [];
+      private stats = { allocated: 0, released: 0 };
+
+      constructor() {
+        this.registry = new FinalizationRegistry(({ token }) => {
+          this.cleanupQueue.push(token);
+        });
+      }
+
+      register(resource: any, type: string, entityId: number | null) {
+        const token = Symbol(`wasm-${type}-${this.stats.allocated}`);
+        this.resources.set(token, {
+          ref: new WeakRef(resource),
+          entry: { type, entityId },
+        });
+        this.registry.register(resource, { token }, resource);
+        this.stats.allocated++;
+        return token;
+      }
+
+      release(token: symbol) {
+        const entry = this.resources.get(token);
+        if (!entry) return false;
+        const resource = entry.ref.deref();
+        if (resource) {
+          try {
+            resource.delete();
+            this.registry.unregister(resource);
+          } catch {}
+        }
+        this.resources.delete(token);
+        this.stats.released++;
+        return true;
+      }
+
+      releaseByEntity(entityId: number) {
+        let released = 0;
+        for (const [token, { entry }] of this.resources) {
+          if (entry.entityId === entityId) {
+            if (this.release(token)) released++;
+          }
+        }
+        return released;
+      }
+
+      flushCleanupQueue() {
+        const count = this.cleanupQueue.length;
+        for (const token of this.cleanupQueue) {
+          this.release(token);
+        }
+        this.cleanupQueue = [];
+        return count;
+      }
+
+      getStats() {
+        return {
+          totalAllocated: this.stats.allocated,
+          totalReleased: this.stats.released,
+          currentActive: this.resources.size,
+          leaked: this.stats.allocated - this.stats.released - this.resources.size,
+        };
+      }
+    }
+
+    (window as any).__VS_RESOURCE_MANAGER__ = new TestResourceManager();
+  });
+}
+
+async function runHMRStressTest(
+  page: Page,
+  cycles: number,
+): Promise<{ allocated: number; released: number; leaked: number }> {
+  return await page.evaluate(async (numCycles) => {
+    const manager = (window as any).__VS_RESOURCE_MANAGER__;
+    const renderer = (window as any).__VS_RENDERER__;
+
+    for (let i = 0; i < numCycles; i++) {
+      // Simulate HMR: add entities
+      const tokens: symbol[] = [];
+      for (let j = 0; j < 5; j++) {
+        const entityId = i * 5 + j;
+        const mock = {
+          deleted: false,
+          delete() { this.deleted = true; },
+          isDeleted() { return this.deleted; },
+        };
+        tokens.push(manager.register(mock, 'paint', entityId));
+      }
+
+      // Simulate HMR: remove entities (explicit release)
+      for (const token of tokens) {
+        manager.release(token);
+      }
+
+      // Yield to event loop periodically
+      if (i % 1000 === 0) {
+        await new Promise(r => setTimeout(r, 0));
+      }
+    }
+
+    return manager.getStats();
+  }, cycles);
+}
+
+async function forceGC(cdp: CDPSession): Promise<void> {
+  for (let i = 0; i < CONFIG.GC_ATTEMPTS; i++) {
+    await cdp.send('HeapProfiler.collectGarbage');
+    await new Promise(r => setTimeout(r, 100));
+  }
+}
+
+async function flushFinalizationRegistry(page: Page): Promise<number> {
+  return await page.evaluate(() => {
+    return (window as any).__VS_RESOURCE_MANAGER__.flushCleanupQueue();
+  });
+}
+
+async function measureMemory(page: Page, cdp: CDPSession): Promise<MemoryMetrics> {
+  const metrics = await cdp.send('Performance.getMetrics');
+  const jsHeapSizeUsed = metrics.metrics.find(m => m.name === 'JSHeapUsedSize')?.value ?? 0;
+  const jsHeapSizeTotal = metrics.metrics.find(m => m.name === 'JSHeapTotalSize')?.value ?? 0;
+
+  return {
+    jsHeapSizeUsed,
+    jsHeapSizeTotal,
+    wasmHeapEstimate: 0, // CDP doesn't directly expose WASM heap
+    timestamp: Date.now(),
+  };
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}