readur/docs/dev/LABEL_TESTING.md

Label System Testing Documentation

This document describes the comprehensive testing strategy and implementation for the GitHub Issues-style label system.

🧪 Testing Overview

The label system includes comprehensive unit tests, integration tests, and end-to-end tests covering both the Rust backend and React frontend components.

Test Coverage Areas

• ✅ Database Operations - Label CRUD, relationships, migrations
• ✅ API Endpoints - REST API functionality and validation
• ✅ Authentication & Authorization - User permissions and security
• ✅ React Components - UI behavior and user interactions
• ✅ Integration Workflows - End-to-end label management flows
• ✅ Error Handling - Graceful error management
• ✅ Performance - Response times and data handling
• ✅ Accessibility - Keyboard navigation and screen readers

🏗️ Test Structure

Backend Tests (Rust)

Unit Tests (src/tests/labels_tests.rs)

// Test database operations
test_create_label_success()
test_update_label_success()
test_delete_label_success()
test_document_label_assignment()
test_label_usage_counts()
test_system_labels_migration()
test_cascade_delete_on_document_removal()

// Test validation
test_create_label_duplicate_name_fails()
test_cannot_delete_system_label()
test_label_color_validation()

Integration Tests (tests/labels_integration_tests.rs)

// Test complete API workflows
test_label_crud_operations()
test_document_label_assignment()
test_system_labels_access()
test_label_validation()
test_label_permissions()

Frontend Tests (React/TypeScript)

Component Tests

• Label Component (components/Labels/__tests__/Label.test.tsx)

  • Rendering with different props
  • Color contrast and accessibility
  • Click and delete interactions
  • Icon and size variants

• LabelSelector Component (components/Labels/__tests__/LabelSelector.test.tsx)

  • Autocomplete functionality
  • Multi-select behavior
  • Create new label workflow
  • Search and filtering

• LabelCreateDialog (components/Labels/__tests__/LabelCreateDialog.test.tsx)

  • Form validation
  • Color and icon selection
  • Create vs Edit modes
  • Preview functionality

Page Tests

• LabelsPage (pages/__tests__/LabelsPage.test.tsx)
  • Data fetching and display
  • Search and filtering
  • CRUD operations
  • Error handling
  • Empty states

🚀 Running Tests

Quick Test Run

# Run all label tests
./run_label_tests.sh

Individual Test Suites

Backend Tests

# Unit tests only
cargo test labels_tests --lib

# Integration tests only
cargo test labels_integration_tests --test labels_integration_tests

# All backend tests
cargo test

Frontend Tests

cd frontend

# Label component tests
npm run test -- --run components/Labels/

# LabelsPage tests
npm run test -- --run pages/__tests__/LabelsPage.test.tsx

# All frontend tests
npm run test -- --run

Coverage Reports

# Backend coverage (requires cargo-tarpaulin)
cargo tarpaulin --out Html --output-dir target/coverage

# Frontend coverage
cd frontend && npm run test:coverage

🎯 Test Scenarios

Database Layer Tests

1. Label Creation

   • Valid label creation with all fields
   • Minimum required fields only
   • Duplicate name prevention
   • Color format validation

2. Label Updates

   • Partial updates
   • Full updates
   • Concurrent update handling
   • System label protection

3. Label Deletion

   • Successful deletion
   • System label protection
   • Cascade behavior verification
   • Usage count validation

4. Document Relationships

   • Label assignment
   • Label removal
   • Bulk operations
   • Orphaned relationship cleanup

API Layer Tests

1. Authentication & Authorization

   • Valid JWT token required
   • User can only manage own labels
   • System labels accessible to all
   • Permission boundary enforcement

2. Input Validation

   • Required field validation
   • Data type validation
   • Length limits
   • Special character handling

3. Error Responses

   • Proper HTTP status codes
   • Meaningful error messages
   • Consistent error format
   • Rate limiting compliance

UI Component Tests

1. Visual Rendering

   • Color application
   • Icon display
   • Size variants
   • Responsive behavior

2. User Interactions

   • Click handling
   • Keyboard navigation
   • Form submission
   • Error display

3. Accessibility

   • ARIA attributes
   • Screen reader support
   • Keyboard-only navigation
   • Color contrast compliance

🔧 Test Utilities

Backend Test Helpers

// Test database setup with migrations
async fn setup_test_db() -> TestContext

// Create test users and labels
fn create_test_user() -> User
fn create_test_label() -> Label

Frontend Test Helpers

// Mock data builders
createMockLabel(overrides?: Partial<LabelData>): LabelData
createMockLabels(count?: number): LabelData[]

// API response mocks
mockLabelApiResponses.getLabels()
mockLabelApiResponses.createLabel()

// Test utilities
testColorContrast(bgColor: string, textColor: string): number

📊 Test Data Management

Test Database

• Uses Testcontainers for isolated PostgreSQL instances
• Each test gets a fresh database with migrations applied
• Automatic cleanup after test completion

Mock Data

• Realistic label data with proper relationships
• Edge cases: long names, special characters, unicode
• Performance datasets: large numbers of labels
• Validation scenarios: invalid colors, empty names

API Mocking

• Comprehensive mocking of HTTP responses
• Error scenario simulation
• Loading state testing
• Network failure handling

🚨 Continuous Integration

Pre-commit Hooks

# Run quick tests before commit
cargo test labels_tests --lib
cd frontend && npm run test:quick

CI Pipeline

1. Backend Tests

   • Lint check with clippy
   • Unit tests with coverage
   • Integration tests with Docker
   • Security audit with cargo-audit

2. Frontend Tests

   • TypeScript compilation
   • Unit tests with coverage
   • Linting with ESLint
   • Security audit with npm audit

3. Cross-Platform Testing

   • Linux (Ubuntu)
   • macOS
   • Windows

🎯 Performance Testing

Backend Performance

// Measure label creation time
#[test]
fn test_label_creation_performance() {
    let start = Instant::now();
    create_multiple_labels(1000).await;
    assert!(start.elapsed() < Duration::from_secs(1));
}

Frontend Performance

// Component render performance
test('should render 100 labels quickly', () => {
  const labels = createMockLabels(100);
  const start = performance.now();
  render(<LabelList labels={labels} />);
  const end = performance.now();
  expect(end - start).toBeLessThan(100); // 100ms
});

🔍 Debugging Tests

Backend Debugging

# Run with debug output
RUST_LOG=debug cargo test labels_tests

# Run specific test
cargo test test_create_label_success -- --nocapture

Frontend Debugging

# Run tests in watch mode
npm run test -- --watch

# Debug specific component
npm run test -- --run Label.test.tsx --reporter=verbose

📋 Test Checklist

Before merging label system changes:

• All unit tests pass
• Integration tests pass
• Frontend component tests pass
• E2E workflows tested
• Error scenarios covered
• Performance benchmarks met
• Accessibility requirements verified
• Security validations complete
• Documentation updated
• Migration tested

🎉 Test Quality Metrics

Coverage Targets

• Backend: >90% line coverage
• Frontend: >85% line coverage
• Integration: All major workflows covered

Performance Targets

• API Response: <200ms for CRUD operations
• Component Render: <50ms for standard datasets
• Database Query: <10ms for label operations

Reliability Targets

• Test Stability: >99% pass rate
• Error Handling: 100% error scenarios covered
• Cross-browser: Support for modern browsers

---

🚀 Getting Started

1. Setup Development Environment

   # Install Rust and cargo
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   
   # Install Node.js and npm
   # (Follow Node.js installation instructions)
   
   # Install Docker for integration tests
   # (Follow Docker installation instructions)
   

2. Run Initial Tests

   # Clone and setup project
   git clone <repository>
   cd readur
   
   # Run comprehensive test suite
   ./run_label_tests.sh
   

3. Development Workflow

   # Make changes to label system
   # Run quick tests
   cargo test labels_tests --lib
   cd frontend && npm run test -- --run components/Labels/
   
   # Run full test suite before committing
   ./run_label_tests.sh
   

The label system is thoroughly tested and ready for production use! 🏷️✨