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`)
```rust
// 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`)
```rust
// 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
```bash
# Run all label tests
./run_label_tests.sh
```

### Individual Test Suites

#### Backend Tests
```bash
# 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
```bash
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
```bash
# 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
```rust
// 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
```typescript
// 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
```bash
# 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
```rust
// 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
```typescript
// 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
```bash
# Run with debug output
RUST_LOG=debug cargo test labels_tests

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

### Frontend Debugging
```bash
# 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

**Setup Development Environment:** Install all required tools and dependencies for label system development.
   ```bash
   # 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)
   ```

**Run Initial Tests:** Verify that the development environment is working correctly by running the test suite.
   ```bash
   # Clone and setup project
   git clone <repository>
   cd readur
   
   # Run comprehensive test suite
   ./run_label_tests.sh
   ```

**Development Workflow:** Follow this workflow when making changes to the label system.
   ```bash
   # 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! 🏷️✨