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