analytics-testing · git:20251008.4bc6fc5 · 2025-10-08 · sha256 a5a7c49b210057f6

analytics-testing git:20251008.4bc6fc5A

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

---
alwaysApply: true
description: Analytics testing patterns and best practices
---

# Analytics Testing Rules

## Core Principles

**Analytics Engine calls are first-class citizens in tests** - no network, no flakes, no waiting.

## Required Patterns

### 1. Use AnalyticsEngineStub for All Analytics Testing

```typescript
// ✅ 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

```typescript
// ❌ 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

```typescript
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

```typescript
// ✅ 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

## Configuration

### Dual Coverage Thresholds
- **Main suite**: 80% coverage threshold (enforced)
- **Analytics suite**: 0% coverage threshold (flexible)

### Package.json Scripts
```json
{
  "analytics:test": "bun test tests/unit/analytics-testing-example.test.ts --randomize",
  "analytics:test:coverage": "bun test --coverage --randomize tests/unit/analytics-testing-example.test.ts --config bunfig.analytics.toml",
  "analytics:ci": "CI=true bun run analytics:test:coverage"
}
```

## Best Practices

### 1. Test Isolation
- Each test gets a fresh analytics stub
- Auto-flush only on analytics tests
- No test pollution between runs

### 2. Performance
- Tests run in ~20ms (no network calls)
- Use `--randomize` for reliability
- Coverage calculation is fast with stub

### 3. CI Integration
- Analytics tests use `--config bunfig.analytics.toml`
- Main suite enforces 80% coverage
- Nightly jobs validate real binding

### 4. Documentation
- Reference [ANALYTICS_TESTING_GUIDE.md](mdc:docs/testing/ANALYTICS_TESTING_GUIDE.md)
- Use descriptive test names
- Document complex analytics scenarios

## Anti-Patterns

### ❌ Don't Do These
```typescript
// Don't use real Analytics Engine in tests
const realAnalytics = env.ANALYTICS_ENGINE;

// Don't use generic mock assertions
expect(mockAnalytics).toHaveBeenCalledWith();

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

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

### ✅ Do These Instead
```typescript
// Use the global stub
const { env: mockEnv, analytics } = createMockEnv();

// Use first-class analytics assertions
expect(analytics.getCalls()).toHaveLength(1);

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

// Use the global stub consistently
const analytics = getGlobalAnalyticsStub();
```

## Related Files

- [analytics-engine-stub.ts](mdc:tests/utils/analytics-engine-stub.ts) - Core stub implementation
- [test-helpers.ts](mdc:tests/utils/test-helpers.ts) - Helper functions
- [test-setup.ts](mdc:tests/setup/test-setup.ts) - Global configuration
- [bunfig.analytics.toml](mdc:bunfig.analytics.toml) - Analytics-specific config
- [ANALYTICS_TESTING_GUIDE.md](mdc:docs/testing/ANALYTICS_TESTING_GUIDE.md) - Complete guide

---

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