Skip to content

TESTING.md

Latest commit

 

History

History
277 lines (243 loc) · 16.8 KB

TESTING.md

File metadata and controls

277 lines (243 loc) · 16.8 KB
Raw

Testing Guide

🏗️ Testing Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        SYNAPSE TESTING STACK                     │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ Layer 3: End-to-End Tests (Playwright)                          │
├─────────────────────────────────────────────────────────────────┤
│  • Full user workflows in real browser                          │
│  • Tests: smoke.spec.ts, workspace.spec.ts, demos.spec.ts       │
│  • Coverage: Complete user journeys, multi-page flows           │
│                                                                  │
│  User → Browser → Full App → Chrome AI → Validation             │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Layer 2: Integration Tests (Vitest + RTL)                       │
├─────────────────────────────────────────────────────────────────┤
│  • Component + Hook interactions                                │
│  • Tests: component-integration.test.tsx                        │
│  • Coverage: State management, context providers, API calls     │
│                                                                  │
│  Component → Context → Hooks → State → Assertions               │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Layer 1: Unit Tests (Vitest + RTL + MSW)                        │
├─────────────────────────────────────────────────────────────────┤
│  • Individual functions, components, utilities                  │
│  • Tests: 40+ test files across codebase                        │
│  • Coverage: Pure logic, rendering, error handling              │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │  Components  │  │   Libraries  │  │  Utilities   │          │
│  │  *.test.tsx  │  │  *.test.ts   │  │  *.test.ts   │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                      SUPPORTING INFRASTRUCTURE                   │
├─────────────────────────────────────────────────────────────────┤
│  Test Utilities          │  Fixtures & Mocks   │  Configuration │
│  • Custom render()       │  • Test data        │  • vitest.config│
│  • MSW handlers          │  • Mock content     │  • playwright   │
│  • Test constants        │  • Sample metadata  │  • tsconfig.test│
└─────────────────────────────────────────────────────────────────┘

📊 Test Coverage Map

┌────────────────────────────────────────────────────────────────────┐
│                         SYNAPSE APPLICATION                        │
├────────────────────────────────────────────────────────────────────┤
│                                                                    │
│  ┌──────────────────────────────────────────────────────────┐     │
│  │ Chrome AI Integration (Browser API)                      │     │
│  │ ✓ browserCompatibility.test.ts                           │     │
│  │ ✓ RewriterError.test.ts, errorGuards.test.ts            │     │
│  └──────────────────────────────────────────────────────────┘     │
│                           ↓                                        │
│  ┌──────────────────────────────────────────────────────────┐     │
│  │ Content Processing Layer                                 │     │
│  │ ✓ content-fetcher.test.ts (URL fetching)                │     │
│  │ ✓ readability-parser.test.ts (HTML parsing)             │     │
│  │ ✓ index.test.ts (extraction orchestration)              │     │
│  │ ✓ fileProcessor.test.ts (file handling)                 │     │
│  └──────────────────────────────────────────────────────────┘     │
│                           ↓                                        │
│  ┌──────────────────────────────────────────────────────────┐     │
│  │ UI Components                                            │     │
│  │ ✓ URLInput.test.tsx (user input)                        │     │
│  │ ✓ ExtractedContent.test.tsx (content display)           │     │
│  │ ✓ ComparisonView.test.tsx (before/after)                │     │
│  │ ✓ FormatSection.test.tsx (format selection)             │     │
│  │ ✓ 6+ UI primitive components                            │     │
│  └──────────────────────────────────────────────────────────┘     │
│                           ↓                                        │
│  ┌──────────────────────────────────────────────────────────┐     │
│  │ Configuration & Constants                                │     │
│  │ ✓ formats.test.ts (output formats)                      │     │
│  │ ✓ writingTools.test.ts (AI tools config)                │     │
│  └──────────────────────────────────────────────────────────┘     │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

Legend: ✓ = Comprehensive test coverage

🔄 Test Execution Flow

┌─────────────────────────────────────────────────────────────┐
│                    npm test (Unit Tests)                     │
└─────────────────────────────────────────────────────────────┘
                            ↓
        ┌───────────────────────────────────┐
        │  1. Vitest Setup (vitest.setup.ts)│
        │     • Load @testing-library/jest-dom│
        │     • Configure test environment   │
        └───────────────────────────────────┘
                            ↓
        ┌───────────────────────────────────┐
        │  2. Test Discovery                │
        │     • Find **/*.test.{ts,tsx}     │
        │     • Load 42 test files          │
        └───────────────────────────────────┘
                            ↓
        ┌───────────────────────────────────┐
        │  3. Test Execution                │
        │     • Run 1,568 tests             │
        │     • MSW mocks API calls         │
        │     • Custom render() for React   │
        └───────────────────────────────────┘
                            ↓
        ┌───────────────────────────────────┐
        │  4. Results & Coverage            │
        │     • Pass/Fail summary           │
        │     • Coverage report (optional)  │
        └───────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                  npm run test:e2e (E2E Tests)                │
└─────────────────────────────────────────────────────────────┘
                            ↓
        ┌───────────────────────────────────┐
        │  1. Playwright Launch             │
        │     • Start Chromium browser      │
        │     • Navigate to localhost:5173  │
        └───────────────────────────────────┘
                            ↓
        ┌───────────────────────────────────┐
        │  2. Run User Scenarios            │
        │     • smoke.spec.ts (critical)    │
        │     • workspace.spec.ts (AI flow) │
        │     • demos.spec.ts (all tools)   │
        │     • preferences.spec.ts (config)│
        └───────────────────────────────────┘
                            ↓
        ┌───────────────────────────────────┐
        │  3. Assertions & Validation       │
        │     • Check DOM elements          │
        │     • Verify user interactions    │
        │     • Validate page navigation    │
        └───────────────────────────────────┘
                            ↓
        ┌───────────────────────────────────┐
        │  4. Test Report                   │
        │     • Pass/Fail with screenshots  │
        │     • Trace files for debugging   │
        └───────────────────────────────────┘

🛠️ Test Utilities Architecture

src/test-utils/
├── render.tsx                  Custom render with providers
│   └── Usage: render(<Component />)
│   └── Provides: QueryClient, Router context
│
├── vitest.setup.ts            Test environment configuration
│   └── Loads: @testing-library/jest-dom matchers
│   └── Configures: Global test settings
│
├── msw-handlers.ts            API mocking handlers
│   └── Mocks: fetch, Chrome AI APIs
│   └── Usage: server.use(...handlers)
│
├── test-constants.ts          Shared test data
│   └── Exports: URLs, configurations, defaults
│
└── fixtures/
    ├── content.ts             Mock content data
    ├── metadata.ts            Mock metadata
    └── errors.ts              Mock error responses

📋 Quick Reference

Running Tests

# Unit tests (fast)
npm test                    # Run all unit tests
npm run test:watch         # Watch mode
npm run test:ui            # Interactive UI
npm run test:coverage      # With coverage report

# E2E tests (slower, requires dev server)
npm run dev                # Terminal 1: Start dev server
npm run test:e2e          # Terminal 2: Run E2E tests
npm run test:e2e:ui       # Interactive E2E UI

Writing Tests

Unit Test Template:

import { describe, it, expect } from 'vitest'
import { render, screen } from '@/test-utils/render'

describe('ComponentName', () => {
  it('should render correctly', () => {
    render(<ComponentName />)
    expect(screen.getByText('Expected Text')).toBeInTheDocument()
  })
})

E2E Test Template:

import { test, expect } from '@playwright/test'

test.describe('Feature Name', () => {
  test('should complete user flow', async ({ page }) => {
    await page.goto('/')
    await page.getByRole('button', { name: 'Submit' }).click()
    await expect(page.getByText('Success')).toBeVisible()
  })
})

Test Organization Principles

  1. Co-location: Tests live next to the code they test
  2. Naming: *.test.ts for unit, *.spec.ts for E2E
  3. Grouping: Use describe() blocks for logical grouping
  4. Isolation: Each test should be independent
  5. AAA Pattern: Arrange, Act, Assert

🎯 Coverage Goals

Category Target Current Status
Chrome AI APIs 90% 95% ✅
Content Extraction 85% 92% ✅
UI Components 80% 88% ✅
Error Handling 100% 100% ✅
Critical User Flows 100% 100% ✅

🔍 Test Debugging

Unit Tests

# Run specific test file
npm test -- src/path/to/file.test.ts

# Run tests matching pattern
npm test -- --grep "pattern"

# Debug with UI
npm run test:ui

E2E Tests

# Run specific test file
npm run test:e2e -- tests/smoke.spec.ts

# Debug mode (headed browser)
npm run test:e2e -- --debug

# View test traces
npx playwright show-trace trace.zip

📚 Additional Resources