Testing Overview

Introduction

Testing ensures code quality, prevents regressions, and builds confidence in deployments. Our testing strategy uses Jest for unit tests and Cypress for E2E tests, providing comprehensive coverage from individual functions to complete user flows.

Current Status: ⚠️ Testing infrastructure is actively being developed. This documentation covers the current setup and planned improvements.

---

Testing Philosophy

Test What Matters

const TESTING_PRIORITIES = {
  critical: [
    'Authentication flows',
    'Data mutations (create, update, delete)',
    'Permission checks',
    'Payment processing',
  ],
  
  important: [
    'Entity CRUD operations',
    'API endpoints',
    'Form validations',
    'Navigation flows',
  ],
  
  nice_to_have: [
    'UI component rendering',
    'Utility functions',
    'Edge cases',
  ],
}

Focus: Test critical paths thoroughly, important features adequately, nice-to-haves minimally.

---

Testing Pyramid

Three Layers of Testing

         /\
        /  \         E2E Tests (Cypress)
       /    \        • Slow, expensive
      /      \       • Critical user flows
     /________\      • ~10% of tests
    
    /          \     Integration Tests
   /            \    • Medium speed
  /              \   • API + DB + Logic
 /________________\  • ~30% of tests

/                  \ Unit Tests (Jest)
____________________• Fast, cheap
                     • Pure functions
                     • ~60% of tests

Strategy: Many fast unit tests, fewer integration tests, minimal E2E tests.

---

Current Test Setup

Jest (Unit Testing)

# Run all unit tests
pnpm test

# Run specific test file
pnpm test -- lib/utils.test.ts

# Run with coverage
pnpm test -- --coverage

# Watch mode for development
pnpm test -- --watch

Configuration: jest.config.cjs

Test Location: test/jest/**/*.test.ts

Key Features:

• ts-jest for TypeScript
• React Testing Library for components
• jsdom environment for DOM testing

Cypress (E2E Testing)

# Open Cypress UI (development)
pnpm cypress:open

# Run all E2E tests (CI)
pnpm cypress:run

# Run specific test
pnpm cypress:run --spec "test/cypress/e2e/auth/login.cy.ts"

Configuration: test/cypress.config.js

Test Location: test/cypress/e2e/**/*.cy.ts

Key Features:

• Real browser testing
• Video recording
• Screenshot on failure
• Allure reporting

---

What's Currently Tested

Unit Tests (Jest)

// Tested areas
const JEST_COVERAGE = {
  utils: 'Core utilities and helpers',
  hooks: 'React hooks (partial)',
  lib: 'Business logic functions (partial)',
  validation: 'Form validations (minimal)',
}

// Example test structure
describe('sanitizeInput', () => {
  it('should remove HTML tags', () => {
    expect(sanitizeInput('<script>alert("xss")</script>'))
      .toBe('alert("xss")')
  })
})

Status: ~30% coverage on core utilities

E2E Tests (Cypress)

// Tested flows
const CYPRESS_COVERAGE = {
  auth: 'Login, logout, OAuth (partial)',
  tasks: 'CRUD operations (partial)',
  api: 'API endpoints (good coverage)',
  navigation: 'Dashboard navigation (basic)',
}

// Example test structure
describe('Task CRUD', () => {
  it('should create a new task', () => {
    cy.visit('/dashboard/tasks')
    cy.get('[data-cy="create-task-btn"]').click()
    cy.get('[data-cy="task-title"]').type('Test Task')
    cy.get('[data-cy="submit"]').click()
    cy.contains('Task created successfully')
  })
})

Status: ~40% coverage of critical flows

---

Test Organization

Directory Structure

test/
├── jest/                     # Unit tests
│   ├── api/                  # API logic tests
│   ├── components/           # React component tests
│   ├── hooks/                # Custom hooks tests
│   ├── lib/                  # Utility function tests
│   └── __mocks__/            # Mock implementations
│
├── cypress/                  # E2E tests
│   ├── e2e/                  # Test specifications
│   │   ├── auth/             # Authentication tests
│   │   ├── api/              # API endpoint tests
│   │   └── tasks/            # Task feature tests
│   ├── support/              # Custom commands
│   └── fixtures/             # Test data
│
└── cases/                    # Test case definitions (CSV)
    ├── auth/
    ├── tasks/
    └── api/

---

Writing Tests

Jest Unit Test Template

// test/jest/lib/utils.test.ts
import { myFunction } from '@/core/lib/utils'

describe('myFunction', () => {
  it('should handle valid input', () => {
    const result = myFunction('valid')
    expect(result).toBe('expected')
  })

  it('should handle invalid input', () => {
    expect(() => myFunction('')).toThrow()
  })

  it('should return default for null', () => {
    expect(myFunction(null)).toBe('default')
  })
})

Cypress E2E Test Template

// test/cypress/e2e/feature/flow.cy.ts
describe('Feature Flow', () => {
  beforeEach(() => {
    // Login before each test
    cy.visit('/')
    // Add login logic or use custom command
  })

  it('should complete user flow', () => {
    cy.visit('/dashboard/feature')
    cy.get('[data-cy="action-btn"]').click()
    cy.get('[data-cy="input"]').type('test data')
    cy.get('[data-cy="submit"]').click()
    cy.contains('Success message')
  })
})

---

Coverage Goals

Target Coverage

const COVERAGE_TARGETS = {
  critical_paths: '90%+',    // Auth, payments, data mutations
  important_features: '80%+', // Entity CRUD, APIs
  general_code: '70%+',       // Utils, helpers
  total: '75%+',              // Overall project
}

Current Coverage: ~35% overall (actively improving)

---

Running Tests in CI/CD

GitHub Actions Integration

# .github/workflows/test.yml (example)
name: Tests

on: [push, pull_request]

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: pnpm install
      - run: pnpm test --coverage

  e2e-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: pnpm install
      - run: pnpm build
      - run: pnpm start & pnpm cypress:run

---

Known Limitations

Current Gaps

• ⚠️ Component tests: Minimal React component test coverage
• ⚠️ Integration tests: Limited API + DB integration tests
• ⚠️ Entity tests: Entity system needs comprehensive testing
• ⚠️ Edge cases: Many edge cases not yet covered
• ⚠️ Performance tests: No performance regression tests

Planned Improvements

• ✅ Increase unit test coverage to 70%+
• ✅ Add comprehensive entity CRUD tests
• ✅ Improve authentication flow tests
• ✅ Add API integration tests
• ✅ Performance regression testing

---

Best Practices

✅ DO

// Use descriptive test names
it('should create task with valid title and description', () => {})

// Test one thing per test
it('should validate email format', () => {})
it('should reject empty email', () => {})

// Use data-cy attributes for E2E
<button data-cy="submit-btn">Submit</button>

// Clean up after tests
afterEach(() => {
  // Reset state, clear mocks
})

❌ DON'T

// Vague test names
it('should work', () => {})

// Test multiple things
it('should create, update, and delete task', () => {})

// Use fragile selectors
cy.get('.btn-primary.submit')  // Breaks if CSS changes

// Leave side effects
// Always clean up database, state, etc.

---

Quick Reference

Jest Commands

pnpm test                    # Run all tests
pnpm test -- --watch         # Watch mode
pnpm test -- --coverage      # Coverage report
pnpm test -- utils.test.ts   # Specific file

Cypress Commands

pnpm cypress:open            # Interactive mode
pnpm cypress:run             # Headless mode
pnpm cypress:run --spec "**/auth/*.cy.ts"  # Specific tests

---

Next Steps

This testing section covers:

1. Testing Overview (this document) - Strategy and setup
2. Unit Testing with Jest - Jest configuration and patterns
3. E2E Testing with Cypress - Cypress best practices
4. Testing API Endpoints - API testing strategies
5. Mocking Strategies - Mocks and stubs
6. Test Data Management - Test fixtures and factories
7. Integration Testing - Integration test patterns
8. Test Coverage - Coverage analysis and goals

Note: Testing infrastructure is actively being improved. Documentation will be updated as new patterns and tools are implemented.

---

Last Updated: 2025-11-20
Version: 1.0.0
Status: In Development
Current Coverage: ~35% overall