v1.1.0 to v1.1.0

4 added, 2 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
- globs: tests/utils/analytics-engine-stub.ts,tests/**/*analytics*.ts
- description: AnalyticsEngineStub API patterns and usage
version: "1.1.0"
+ globs: tests/utils/analytics-engine-stub.ts,tests/**/*analytics*.ts
+ description: "AnalyticsEngineStub API patterns and usage"
+ lastUpdated: "2025-10-08"
+ dependencies: ["quality-standards", "testing-patterns"]
---
# 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