betting-brain-v3 / rules

---
version: "1.1.0"
alwaysApply: true
description: "Analytics testing patterns and best practices"
lastUpdated: "2025-10-08"
dependencies: ["quality-standards", "testing-patterns"]
---

# 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

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

- [Test Setup Patterns](mdc:.cursor/rules/test-setup-patterns.mdc) - Test configuration and setup
- [Analytics Stub API](mdc:.cursor/rules/analytics-stub-api.mdc) - AnalyticsEngineStub API reference
- [Coverage Thresholds](mdc:.cursor/rules/coverage-thresholds.mdc) - Dual threshold system
- [CI Integration](mdc:.cursor/rules/ci-integration.mdc) - CI/CD automation patterns

## 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