analytics-testing

Analytics Testing Rules

Core Principles

Analytics Engine calls are first-class citizens in tests

• No network dependencies
• No flakes
• No waiting

Required Patterns

1. Use AnalyticsEngineStub for All Analytics Testing

// ✅ CORRECT: Use the global stub
import { createMockEnv } from '../utils/test-helpers';

const { env: mockEnv, analytics } = createMockEnv();

// Make analytics calls
await mockEnv.ANALYTICS_ENGINE.writeDataPoint({
  blobs: ['event_type', 'data'],
  doubles: [value1, value2],
  tags: { source: 'test' }
});

// Assert with analytics.getCalls()
expect(analytics.callCount()).toBe(1);
expect(analytics.getCalls()[0].blobs).toEqual(['event_type', 'data']);

2. Never Use toHaveBeenCalledWith for Analytics

// ❌ WRONG: Generic mock assertions
expect(mockAnalytics.writeDataPoint).toHaveBeenCalledWith({
  blobs: ['event_type', 'data']
});

// ✅ CORRECT: First-class analytics assertions
expect(analytics.wasCalledWith({
  blobs: ['event_type', 'data']
})).toBe(true);

3. Use Helper Functions for Common Assertions

import { 
  expectAnalyticsCall, 
  expectAnalyticsCallCount,
  expectAnalyticsDoubles 
} from '../utils/test-helpers';

// Clean, readable assertions
expectAnalyticsCall(analytics, {
  blobs: ['event_type', 'data'],
  doubles: [1.5, 1000]
});

expectAnalyticsCallCount(analytics, 1);
expectAnalyticsDoubles(analytics, [1.5, 1000], 0.001);

4. Test Name Detection for Auto-Flush

// ✅ CORRECT: Set test name for auto-flush
test('should track analytics calls with stub', async () => {
  setCurrentTestName('should track analytics calls with stub');
  // Test implementation
});

File Organization

Analytics Test Files

• Location: tests/unit/analytics-*.test.ts
• Pattern: analytics-[feature].test.ts
• Example: analytics-tracking.test.ts

Test Utilities

• tests/utils/analytics-engine-stub.ts - Core stub implementation
• tests/utils/test-helpers.ts - Helper functions and assertions
• tests/setup/test-setup.ts - Global test configuration