analytics-stub-api · v1.1.0 · 2025-10-08 · sha256 22802b18c3d6e3b2

analytics-stub-api v1.1.0A

Immutable. This exact content never changes and is served at /api/v1/blob/22802b18c3d6e3b2.

---
globs: tests/utils/analytics-engine-stub.ts,tests/**/*analytics*.ts
description: AnalyticsEngineStub API patterns and usage
version: "1.1.0"
---

# AnalyticsEngineStub API Rules

## Core Interface

### AnalyticsCall Interface
```typescript

export interface AnalyticsCall {
  blobs: string[];
  doubles: number[];
  tags?: Record<string, string>;
  timestamp: number;
}
```

### AnalyticsEngineStub Class
```typescript

export class AnalyticsEngineStub {
  private calls: AnalyticsCall[] = [];
  private flushPromises: Promise<void>[] = [];

  async writeDataPoint(data: {
    blobs: string[];
    doubles: number[];
    tags?: Record<string, string>;
  }): Promise<void> {
    // Implementation
  }
}
```

## Core Methods

### writeDataPoint
```typescript

// ✅ CORRECT: Standard analytics call
await analytics.writeDataPoint({
  blobs: ['event_type', 'data_type'],
  doubles: [1.5, 1000],
  tags: { source: 'test', version: '1.0' }
});
```

### getCalls
```typescript

// ✅ CORRECT: Get all calls
const calls = analytics.getCalls();
expect(calls).toHaveLength(1);
expect(calls[0].blobs).toEqual(['event_type', 'data_type']);
```

### callCount
```typescript
// ✅ CORRECT: Count calls
expect(analytics.callCount()).toBe(1);
```

## Filtering Methods

### callsWithBlob
```typescript
// ✅ CORRECT: Filter by blob content
const eventCalls = analytics.callsWithBlob('event_type');
expect(eventCalls).toHaveLength(1);
```

### callsWithTag
```typescript
// ✅ CORRECT: Filter by tag
const sourceCalls = analytics.callsWithTag('source', 'test');
expect(sourceCalls).toHaveLength(1);
```

### wasCalledWith
```typescript
// ✅ CORRECT: Check specific call
expect(analytics.wasCalledWith({
  blobs: ['event_type', 'data_type'],
  doubles: [1.5, 1000]
})).toBe(true);
```

## Utility Methods

### clearCalls
```typescript
// ✅ CORRECT: Clear all calls
analytics.clearCalls();
expect(analytics.callCount()).toBe(0);
```

### getStats
```typescript
// ✅ CORRECT: Get call statistics
const stats = analytics.getStats();
expect(stats.totalCalls).toBe(1);
expect(stats.averageDoublesPerCall).toBe(2);
```

### flush
```typescript
// ✅ CORRECT: Flush analytics (auto-called)
analytics.flush();
```

## Helper Functions

### expectAnalyticsCall
```typescript
import { expectAnalyticsCall } from '../utils/test-helpers';

// ✅ CORRECT: Clean assertion
expectAnalyticsCall(analytics, {
  blobs: ['event_type', 'data_type'],
  doubles: [1.5, 1000]
});
```

### expectAnalyticsCallCount
```typescript
import { expectAnalyticsCallCount } from '../utils/test-helpers';

// ✅ CORRECT: Count assertion
expectAnalyticsCallCount(analytics, 1);
```

### expectAnalyticsDoubles
```typescript
import { expectAnalyticsDoubles } from '../utils/test-helpers';

// ✅ CORRECT: Doubles assertion with tolerance
expectAnalyticsDoubles(analytics, [1.5, 1000], 0.001);
```

## Test Patterns

### Basic Analytics Test
```typescript
test('should track analytics calls', async () => {
  setCurrentTestName('should track analytics calls');
  
  const { env: mockEnv, analytics } = createMockEnv();
  
  await mockEnv.ANALYTICS_ENGINE.writeDataPoint({
    blobs: ['test_event', 'line_movement'],
    doubles: [1.5, 1000],
    tags: { source: 'test' }
  });
  
  expect(analytics.callCount()).toBe(1);
  expect(analytics.getCalls()[0].blobs).toEqual(['test_event', 'line_movement']);
});
```

### Multiple Calls Test
```typescript
test('should track multiple analytics calls', async () => {
  setCurrentTestName('should track multiple analytics calls');
  
  const { env: mockEnv, analytics } = createMockEnv();
  
  // Make multiple calls
  await mockEnv.ANALYTICS_ENGINE.writeDataPoint({
    blobs: ['event1', 'type1'],
    doubles: [100, 200]
  });
  
  await mockEnv.ANALYTICS_ENGINE.writeDataPoint({
    blobs: ['event2', 'type2'],
    doubles: [300, 400]
  });
  
  expect(analytics.callCount()).toBe(2);
});
```

### Filtering Test
```typescript
test('should filter calls by event type', async () => {
  setCurrentTestName('should filter calls by event type');
  
  const { env: mockEnv, analytics } = createMockEnv();
  
  await mockEnv.ANALYTICS_ENGINE.writeDataPoint({
    blobs: ['nba_123', 'line_movement'],
    doubles: [1.5, 1000]
  });
  
  const nbaCalls = analytics.callsWithBlob('nba_123');
  expect(nbaCalls).toHaveLength(1);
});
```

## Anti-Patterns

### ❌ Don't Do These
```typescript
// Don't use generic mock assertions
expect(mockAnalytics.writeDataPoint).toHaveBeenCalledWith();

// Don't create duplicate stubs
const analytics1 = createAnalyticsEngineStub();
const analytics2 = createAnalyticsEngineStub();

// Don't forget to set test name
test('my test', async () => {
  // Missing setCurrentTestName()
});

// Don't use real Analytics Engine
const realAnalytics = env.ANALYTICS_ENGINE;
```

### ✅ Do These Instead
```typescript
// Use first-class analytics assertions
expect(analytics.getCalls()).toHaveLength(1);

// Use global stub
const { env: mockEnv, analytics } = createMockEnv();

// Set test name for auto-flush
test('my test', async () => {
  setCurrentTestName('my test');
});

// Use analytics stub
const analytics = getGlobalAnalyticsStub();
```

## Performance Characteristics

### Fast Execution
- Tests run in ~20ms (no network calls)
- No external dependencies
- Deterministic results

### Memory Efficient
- Calls stored in memory
- Auto-cleanup after tests
- No memory leaks

### Reliable
- No network flakes
- Consistent behavior
- Easy to debug

## Related Rules

- [Analytics Testing](mdc:.cursor/rules/analytics-testing.mdc) - Core analytics testing patterns
- [Test Setup Patterns](mdc:.cursor/rules/test-setup-patterns.mdc) - Test configuration patterns
- [Coverage Thresholds](mdc:.cursor/rules/coverage-thresholds.mdc) - Dual threshold system

## Related Files

- [analytics-engine-stub.ts](mdc:tests/utils/analytics-engine-stub.ts) - Core implementation
- [test-helpers.ts](mdc:tests/utils/test-helpers.ts) - Helper functions
- [analytics-testing-example.test.ts](mdc:tests/unit/analytics-testing-example.test.ts) - Examples
- [test-setup.ts](mdc:tests/setup/test-setup.ts) - Global configuration

---

**Status:** Production Ready ✅  
**Last Updated:** 2025-10-07  
**Score:** 9.5/10