@littlebearapps/platform-admin-sdk 2.0.0 → 2.1.0

package/templates/shared/tests/unit/telemetry-sampling.test.ts

@@ -0,0 +1,401 @@
+/**
+ * Unit Tests for Reservoir Sampling
+ *
+ * Tests Algorithm R implementation for O(1) memory latency percentile tracking.
+ *
+ * @module tests/unit/telemetry-sampling
+ * @created 2026-01-23
+ * @task Intelligent Degradation for Platform Usage
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  createReservoirState,
+  addSample,
+  addSamples,
+  calculatePercentiles,
+  getPercentiles,
+  mergeReservoirs,
+  resetReservoir,
+  estimateMemoryUsage,
+  formatPercentiles,
+  checkLatencyThresholds,
+  DEFAULT_RESERVOIR_CONFIG,
+} from '../../workers/lib/telemetry-sampling';
+
+describe('Reservoir Sampling', () => {
+  describe('createReservoirState', () => {
+    it('creates fresh state with empty samples', () => {
+      const state = createReservoirState();
+
+      expect(state.samples).toEqual([]);
+      expect(state.totalSeen).toBe(0);
+      expect(state.lastUpdate).toBeGreaterThan(0);
+      expect(state.percentiles).toBeUndefined();
+    });
+  });
+
+  describe('addSample', () => {
+    it('adds samples directly when reservoir is not full', () => {
+      const state = createReservoirState();
+
+      addSample(state, 10);
+      addSample(state, 20);
+      addSample(state, 30);
+
+      expect(state.samples).toEqual([10, 20, 30]);
+      expect(state.totalSeen).toBe(3);
+    });
+
+    it('maintains fixed size when reservoir is full', () => {
+      const state = createReservoirState();
+      const config = { maxSamples: 5 };
+
+      // Add more samples than reservoir can hold
+      for (let i = 1; i <= 10; i++) {
+        addSample(state, i, config);
+      }
+
+      expect(state.samples.length).toBe(5);
+      expect(state.totalSeen).toBe(10);
+    });
+
+    it('clears cached percentiles on new sample', () => {
+      const state = createReservoirState();
+      addSample(state, 10);
+      calculatePercentiles(state); // Cache percentiles
+
+      expect(state.percentiles).toBeDefined();
+
+      addSample(state, 20);
+      expect(state.percentiles).toBeUndefined();
+    });
+
+    it('uses Algorithm R probability for replacement', () => {
+      // Statistical test: after many samples, each value should have equal probability
+      // This is a smoke test - full statistical validation would require more samples
+      const state = createReservoirState();
+      const config = { maxSamples: 100 };
+
+      // Add 1000 samples
+      for (let i = 1; i <= 1000; i++) {
+        addSample(state, i, config);
+      }
+
+      // Verify basic properties
+      expect(state.samples.length).toBe(100);
+      expect(state.totalSeen).toBe(1000);
+
+      // Check that samples span the range (not just first 100)
+      const maxSample = Math.max(...state.samples);
+      const minSample = Math.min(...state.samples);
+      expect(maxSample).toBeGreaterThan(500); // Should have late samples
+      expect(minSample).toBeLessThan(500); // Should have early samples
+    });
+  });
+
+  describe('addSamples', () => {
+    it('adds multiple samples efficiently', () => {
+      const state = createReservoirState();
+
+      addSamples(state, [10, 20, 30, 40, 50]);
+
+      expect(state.totalSeen).toBe(5);
+      expect(state.samples.length).toBe(5);
+    });
+  });
+
+  describe('calculatePercentiles', () => {
+    it('returns undefined for empty reservoir', () => {
+      const state = createReservoirState();
+      const percentiles = calculatePercentiles(state);
+      expect(percentiles).toBeUndefined();
+    });
+
+    it('calculates correct percentiles for known data', () => {
+      const state = createReservoirState();
+      // Add values 1-100
+      for (let i = 1; i <= 100; i++) {
+        addSample(state, i);
+      }
+
+      const percentiles = calculatePercentiles(state);
+
+      expect(percentiles).toBeDefined();
+      expect(percentiles!.p50).toBe(50);
+      expect(percentiles!.p90).toBe(90);
+      expect(percentiles!.p95).toBe(95);
+      expect(percentiles!.p99).toBe(99);
+      expect(percentiles!.min).toBe(1);
+      expect(percentiles!.max).toBe(100);
+      expect(percentiles!.avg).toBe(50.5);
+    });
+
+    it('caches percentiles in state', () => {
+      const state = createReservoirState();
+      addSamples(state, [10, 20, 30]);
+
+      const p1 = calculatePercentiles(state);
+      const p2 = state.percentiles;
+
+      expect(p1).toBe(p2); // Same object reference
+    });
+
+    it('handles single sample', () => {
+      const state = createReservoirState();
+      addSample(state, 42);
+
+      const percentiles = calculatePercentiles(state);
+
+      expect(percentiles!.p50).toBe(42);
+      expect(percentiles!.p99).toBe(42);
+      expect(percentiles!.min).toBe(42);
+      expect(percentiles!.max).toBe(42);
+    });
+  });
+
+  describe('getPercentiles', () => {
+    it('returns cached percentiles if available', () => {
+      const state = createReservoirState();
+      addSamples(state, [10, 20, 30]);
+      calculatePercentiles(state);
+
+      const cached = state.percentiles;
+      const result = getPercentiles(state);
+
+      expect(result).toBe(cached);
+    });
+
+    it('computes percentiles if not cached', () => {
+      const state = createReservoirState();
+      addSamples(state, [10, 20, 30]);
+
+      expect(state.percentiles).toBeUndefined();
+
+      const result = getPercentiles(state);
+
+      expect(result).toBeDefined();
+      expect(state.percentiles).toBeDefined();
+    });
+  });
+
+  describe('mergeReservoirs', () => {
+    it('returns copy of non-empty reservoir when other is empty', () => {
+      const a = createReservoirState();
+      addSamples(a, [10, 20, 30]);
+
+      const b = createReservoirState();
+
+      const merged = mergeReservoirs(a, b);
+
+      expect(merged.samples).toEqual([10, 20, 30]);
+      expect(merged.totalSeen).toBe(3);
+    });
+
+    it('returns copy of non-empty reservoir when first is empty', () => {
+      const a = createReservoirState();
+
+      const b = createReservoirState();
+      addSamples(b, [40, 50]);
+
+      const merged = mergeReservoirs(a, b);
+
+      expect(merged.samples).toEqual([40, 50]);
+      expect(merged.totalSeen).toBe(2);
+    });
+
+    it('combines samples when total fits in reservoir', () => {
+      const a = createReservoirState();
+      addSamples(a, [10, 20]);
+
+      const b = createReservoirState();
+      addSamples(b, [30, 40]);
+
+      const merged = mergeReservoirs(a, b, { maxSamples: 10 });
+
+      expect(merged.samples.length).toBe(4);
+      expect(merged.totalSeen).toBe(4);
+      expect(merged.samples).toContain(10);
+      expect(merged.samples).toContain(40);
+    });
+
+    it('randomly selects when combined exceeds reservoir size', () => {
+      const a = createReservoirState();
+      addSamples(a, [1, 2, 3, 4, 5]);
+
+      const b = createReservoirState();
+      addSamples(b, [6, 7, 8, 9, 10]);
+
+      const merged = mergeReservoirs(a, b, { maxSamples: 5 });
+
+      expect(merged.samples.length).toBe(5);
+      expect(merged.totalSeen).toBe(10);
+    });
+
+    it('preserves latest timestamp', () => {
+      const a = createReservoirState();
+      a.lastUpdate = 1000;
+
+      const b = createReservoirState();
+      b.lastUpdate = 2000;
+
+      const merged = mergeReservoirs(a, b);
+
+      expect(merged.lastUpdate).toBe(2000);
+    });
+  });
+
+  describe('resetReservoir', () => {
+    it('clears all samples and resets counters', () => {
+      const state = createReservoirState();
+      addSamples(state, [10, 20, 30]);
+      calculatePercentiles(state);
+
+      resetReservoir(state);
+
+      expect(state.samples).toEqual([]);
+      expect(state.totalSeen).toBe(0);
+      expect(state.percentiles).toBeUndefined();
+    });
+
+    it('updates lastUpdate timestamp', () => {
+      const state = createReservoirState();
+      const before = state.lastUpdate;
+
+      // Small delay to ensure timestamp difference
+      resetReservoir(state);
+
+      expect(state.lastUpdate).toBeGreaterThanOrEqual(before);
+    });
+  });
+
+  describe('estimateMemoryUsage', () => {
+    it('estimates memory based on sample count', () => {
+      const state = createReservoirState();
+      const emptySize = estimateMemoryUsage(state);
+
+      addSamples(state, [10, 20, 30, 40, 50]);
+      const withSamplesSize = estimateMemoryUsage(state);
+
+      expect(withSamplesSize).toBeGreaterThan(emptySize);
+      // 5 samples * 8 bytes = 40 bytes more
+      expect(withSamplesSize - emptySize).toBe(40);
+    });
+
+    it('stays under 1KB for default config', () => {
+      const state = createReservoirState();
+      for (let i = 0; i < DEFAULT_RESERVOIR_CONFIG.maxSamples; i++) {
+        addSample(state, Math.random() * 1000);
+      }
+
+      const memoryUsage = estimateMemoryUsage(state);
+      expect(memoryUsage).toBeLessThan(1024);
+    });
+  });
+
+  describe('formatPercentiles', () => {
+    it('formats percentiles as readable string', () => {
+      const state = createReservoirState();
+      for (let i = 1; i <= 100; i++) {
+        addSample(state, i);
+      }
+      const percentiles = calculatePercentiles(state)!;
+
+      const formatted = formatPercentiles(percentiles);
+
+      expect(formatted).toContain('p50=');
+      expect(formatted).toContain('p95=');
+      expect(formatted).toContain('p99=');
+      expect(formatted).toContain('max=');
+      expect(formatted).toContain('n=100/100');
+    });
+  });
+
+  describe('checkLatencyThresholds', () => {
+    it('returns undefined when within thresholds', () => {
+      const state = createReservoirState();
+      for (let i = 1; i <= 50; i++) {
+        addSample(state, i); // Max 50ms
+      }
+      const percentiles = calculatePercentiles(state)!;
+
+      const warning = checkLatencyThresholds(percentiles);
+      expect(warning).toBeUndefined();
+    });
+
+    it('returns warning when p95 exceeds threshold', () => {
+      const state = createReservoirState();
+      for (let i = 1; i <= 100; i++) {
+        addSample(state, i * 2); // Max 200ms, p95 = 190ms
+      }
+      const percentiles = calculatePercentiles(state)!;
+
+      const warning = checkLatencyThresholds(percentiles, { p95Warning: 100, p99Warning: 500 });
+      expect(warning).toBeDefined();
+      expect(warning).toContain('p95');
+    });
+
+    it('returns warning when p99 exceeds threshold', () => {
+      const state = createReservoirState();
+      for (let i = 1; i <= 100; i++) {
+        addSample(state, i * 6); // Max 600ms, p99 = 594ms
+      }
+      const percentiles = calculatePercentiles(state)!;
+
+      const warning = checkLatencyThresholds(percentiles, { p95Warning: 1000, p99Warning: 500 });
+      expect(warning).toBeDefined();
+      expect(warning).toContain('p99');
+    });
+
+    it('returns multiple warnings when both thresholds exceeded', () => {
+      const state = createReservoirState();
+      for (let i = 1; i <= 100; i++) {
+        addSample(state, i * 10); // Max 1000ms
+      }
+      const percentiles = calculatePercentiles(state)!;
+
+      const warning = checkLatencyThresholds(percentiles, { p95Warning: 100, p99Warning: 500 });
+      expect(warning).toContain('p95');
+      expect(warning).toContain('p99');
+    });
+  });
+
+  describe('Statistical Properties', () => {
+    it('maintains representative sample for uniform distribution', () => {
+      // Add many samples and verify the reservoir maintains distribution characteristics
+      const state = createReservoirState();
+
+      // Add 10,000 samples from uniform distribution [0, 1000]
+      for (let i = 0; i < 10000; i++) {
+        addSample(state, Math.random() * 1000);
+      }
+
+      const percentiles = calculatePercentiles(state)!;
+
+      // For uniform distribution, p50 should be around 500, p90 around 900, etc.
+      // Allow generous tolerance since this is a statistical test
+      expect(percentiles.p50).toBeGreaterThan(350);
+      expect(percentiles.p50).toBeLessThan(650);
+      expect(percentiles.p90).toBeGreaterThan(750);
+      expect(percentiles.p90).toBeLessThan(980);
+    });
+
+    it('maintains representative sample for skewed distribution', () => {
+      const state = createReservoirState();
+
+      // Add 10,000 samples with exponential-like distribution (many small, few large)
+      for (let i = 0; i < 10000; i++) {
+        // Exponential-like: -ln(U) * scale
+        const sample = -Math.log(Math.random()) * 100;
+        addSample(state, sample);
+      }
+
+      const percentiles = calculatePercentiles(state)!;
+
+      // Median should be around 69 (ln(2) * 100), p99 should be much larger
+      expect(percentiles.p50).toBeLessThan(percentiles.p90);
+      expect(percentiles.p90).toBeLessThan(percentiles.p99);
+      expect(percentiles.p99).toBeGreaterThan(percentiles.p50 * 3);
+    });
+  });
+});