feat: Comprehensive Test Helpers Suite

[talkstream]

Summary

This PR introduces a comprehensive test helpers suite to simplify and standardize testing across TypeScript applications, especially those using Cloudflare Workers, D1 Database, KV storage, and messaging platforms.

Key Features:

• D1 Database Mocks - Query tracking, result configuration, and regex pattern matching
• Query Builder - Fluent API for constructing test SQL queries programmatically
• Fixture Generators - Type-safe factories for creating realistic test data
• KV Namespace Mocks - Full-featured mocks with expiration and metadata support
• Cache Service Mocks - Statistics tracking, tag-based purging, TTL simulation
• Worker Environment Mocks - Complete Cloudflare Workers environment simulation
• Async Testing Utilities - waitFor, retry, parallel execution, event emitters
• Comprehensive Documentation - Detailed usage guide with examples

Implementation Details:

• 100% TypeScript with minimal 'any' types (only where necessary for flexibility)
• All helpers are thoroughly tested (25 tests, all passing)
• Production-inspired patterns from the Kogotochki bot project
• Backwards compatible with existing test suites

Changes

New Files:

• src/test-helpers/ - Main test helpers directory
  • database/ - D1 mocks, query builder, fixtures
  • storage/ - KV and cache mocks
  • platform/ - Worker environment mocks
  • utils/ - Async utilities
• docs/TEST_HELPERS.md - Comprehensive documentation
• examples/test-helpers-example.ts - Real-world usage examples

Test Coverage:

• src/test-helpers/__tests__/test-helpers.test.ts - 25 comprehensive tests

Usage Example

import { 
  createMockD1Database,
  createMockKVNamespace,
  createUserFixture,
  waitFor,
  retry 
} from '@/test-helpers';

// Mock database with query tracking
const mockDb = createMockD1Database();
mockDb._setQueryResult('SELECT * FROM users', [
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' }
]);

// Generate test fixtures
const users = new FixtureGenerator(createUserFixture).createMany(10);

// Async testing utilities
await retry(async () => {
  const response = await fetch('/api/data');
  if (\!response.ok) throw new Error('Failed');
  return response.json();
}, { maxAttempts: 3 });

Benefits

• Reduced Boilerplate - Pre-built mocks for common services
• Better Type Safety - Full TypeScript support throughout
• Consistent Testing - Standardized patterns across projects
• Faster Development - Less time writing mocks, more time testing
• Production-Ready - Based on real-world patterns

Documentation

See docs/TEST_HELPERS.md for:

• Complete API reference
• Usage patterns
• Best practices
• Troubleshooting guide

Breaking Changes

None. This is additive functionality that doesn't affect existing code.

Checklist

• Tests pass (25/25)
• Documentation added
• Examples provided
• TypeScript compliant (minimal warnings)
• ESLint compliant
• Based on production patterns