cfsa-antigravity 2.0.0 → 2.2.0

package/template/.agent/skills/tdd-workflow/references/typescript.md

@@ -0,0 +1,231 @@
+# TypeScript TDD Patterns
+
+Language-specific patterns for the `tdd-workflow` skill. Read `SKILL.md` first for universal methodology.
+
+---
+
+## Test Frameworks
+
+| Tool | Purpose |
+|------|---------|
+| **Jest** or **Vitest** | Unit + integration test runner |
+| **React Testing Library** | Component testing (user-centric) |
+| **Playwright** | E2E browser automation |
+
+## Commands
+
+```bash
+# Run tests
+npm test
+
+# Watch mode
+npm test -- --watch
+
+# Coverage report
+npm run test:coverage
+
+# E2E tests
+npx playwright test
+```
+
+## Unit Test Pattern (Jest/Vitest)
+
+```typescript
+import { render, screen, fireEvent } from '@testing-library/react'
+import { Button } from './Button'
+
+describe('Button Component', () => {
+  it('renders with correct text', () => {
+    render(<Button>Click me</Button>)
+    expect(screen.getByText('Click me')).toBeInTheDocument()
+  })
+
+  it('calls onClick when clicked', () => {
+    const handleClick = jest.fn()
+    render(<Button onClick={handleClick}>Click</Button>)
+
+    fireEvent.click(screen.getByRole('button'))
+
+    expect(handleClick).toHaveBeenCalledTimes(1)
+  })
+
+  it('is disabled when disabled prop is true', () => {
+    render(<Button disabled>Click</Button>)
+    expect(screen.getByRole('button')).toBeDisabled()
+  })
+})
+```
+
+## API Integration Test Pattern
+
+```typescript
+import { NextRequest } from 'next/server'
+import { GET } from './route'
+
+describe('GET /api/markets', () => {
+  it('returns markets successfully', async () => {
+    const request = new NextRequest('http://localhost/api/markets')
+    const response = await GET(request)
+    const data = await response.json()
+
+    expect(response.status).toBe(200)
+    expect(data.success).toBe(true)
+    expect(Array.isArray(data.data)).toBe(true)
+  })
+
+  it('validates query parameters', async () => {
+    const request = new NextRequest('http://localhost/api/markets?limit=invalid')
+    const response = await GET(request)
+
+    expect(response.status).toBe(400)
+  })
+
+  it('handles database errors gracefully', async () => {
+    // Mock database failure
+    const request = new NextRequest('http://localhost/api/markets')
+    // Test error handling
+  })
+})
+```
+
+## E2E Test Pattern (Playwright)
+
+```typescript
+import { test, expect } from '@playwright/test'
+
+test('user can search and filter markets', async ({ page }) => {
+  await page.goto('/')
+  await page.click('a[href="/markets"]')
+
+  await expect(page.locator('h1')).toContainText('Markets')
+
+  await page.fill('input[placeholder="Search markets"]', 'election')
+  await page.waitForTimeout(600)
+
+  const results = page.locator('[data-testid="market-card"]')
+  await expect(results).toHaveCount(5, { timeout: 5000 })
+
+  const firstResult = results.first()
+  await expect(firstResult).toContainText('election', { ignoreCase: true })
+
+  await page.click('button:has-text("Active")')
+  await expect(results).toHaveCount(3)
+})
+```
+
+## File Organization
+
+```
+src/
+├── components/
+│   ├── Button/
+│   │   ├── Button.tsx
+│   │   ├── Button.test.tsx          # Unit tests
+│   │   └── Button.stories.tsx       # Storybook
+│   └── MarketCard/
+│       ├── MarketCard.tsx
+│       └── MarketCard.test.tsx
+├── app/
+│   └── api/
+│       └── markets/
+│           ├── route.ts
+│           └── route.test.ts         # Integration tests
+└── e2e/
+    ├── markets.spec.ts               # E2E tests
+    ├── trading.spec.ts
+    └── auth.spec.ts
+```
+
+## Mocking External Services
+
+```typescript
+// Supabase mock
+jest.mock('@/lib/supabase', () => ({
+  supabase: {
+    from: jest.fn(() => ({
+      select: jest.fn(() => ({
+        eq: jest.fn(() => Promise.resolve({
+          data: [{ id: 1, name: 'Test Market' }],
+          error: null
+        }))
+      }))
+    }))
+  }
+}))
+
+// Redis mock
+jest.mock('@/lib/redis', () => ({
+  searchMarketsByVector: jest.fn(() => Promise.resolve([
+    { slug: 'test-market', similarity_score: 0.95 }
+  ])),
+  checkRedisHealth: jest.fn(() => Promise.resolve({ connected: true }))
+}))
+
+// OpenAI mock
+jest.mock('@/lib/openai', () => ({
+  generateEmbedding: jest.fn(() => Promise.resolve(
+    new Array(1536).fill(0.1) // Mock 1536-dim embedding
+  ))
+}))
+```
+
+## Coverage Thresholds
+
+```json
+{
+  "jest": {
+    "coverageThresholds": {
+      "global": {
+        "branches": 80,
+        "functions": 80,
+        "lines": 80,
+        "statements": 80
+      }
+    }
+  }
+}
+```
+
+## CI/CD Integration
+
+```yaml
+# GitHub Actions
+- name: Run Tests
+  run: npm test -- --coverage
+- name: Upload Coverage
+  uses: codecov/codecov-action@v3
+```
+
+## Assertion Examples
+
+### ❌ Shallow (BANNED)
+```typescript
+expect(result).toBeDefined()
+expect(result).toBeTruthy()
+expect(response.status).toBe(200)  // alone — doesn't verify body
+```
+
+### ✅ Deep (REQUIRED)
+```typescript
+expect(result).toEqual({
+  id: expect.any(String),
+  name: 'Test Market',
+  status: 'active',
+  trades: expect.arrayContaining([
+    expect.objectContaining({ amount: 100 })
+  ])
+})
+```
+
+## Selector Guidance
+
+### ❌ Brittle
+```typescript
+await page.click('.css-class-xyz')
+```
+
+### ✅ Semantic
+```typescript
+await page.click('button:has-text("Submit")')
+await page.click('[data-testid="submit-button"]')
+```