`TEST_DOCUMENTATION.md`

338 lines
# LUXVAULT Auction System - Test Documentation

## Overview

This document describes the comprehensive test suite for the LUXVAULT auction system. The test suite includes unit tests, integration tests, end-to-end tests, and performance tests for both the Node.js API server and Python scraper.

## Test Coverage

### JavaScript/Node.js Tests
- **Location**: `/root/Projects/handbag-auth-nextjs/auction-viewer/tests/`
- **Test Runner**: Jest
- **Coverage Target**: 80%+

### Python Tests
- **Location**: `/root/Projects/handbag-auth-nextjs/scripts/tests/`
- **Test Runner**: pytest
- **Coverage Target**: 80%+

## Running Tests

### Quick Start

```bash
# Run all JavaScript tests
cd /root/Projects/handbag-auth-nextjs/auction-viewer
npm test

# Run all Python tests
cd /root/Projects/handbag-auth-nextjs/scripts
./run-tests.sh
```

### JavaScript Test Commands

```bash
# Run all tests with coverage
npm test

# Run unit tests only
npm run test:unit

# Run integration tests only
npm run test:integration

# Run E2E tests only
npm run test:e2e

# Run performance tests only
npm run test:performance

# Run tests in watch mode (for development)
npm run test:watch

# Run all test suites sequentially
npm run test:all

# Run tests in CI mode
npm run test:ci
```

### Python Test Commands

```bash
# Run all tests
pytest

# Run specific test file
pytest tests/test_scraper.py

# Run tests with coverage
pytest --cov=. --cov-report=html

# Run tests with verbose output
pytest -v

# Run specific test class
pytest tests/test_scraper.py::TestDatabaseInitialization

# Run specific test
pytest tests/test_scraper.py::TestDatabaseInitialization::test_database_creation
```

## Test Structure

### Unit Tests (`tests/unit/`)

**Database Tests** (`database.test.js`)
- Database initialization and schema validation
- Data insertion and retrieval
- Unique constraints and data integrity
- Savings calculations
- Filtering and sorting operations
- Statistics and aggregations
- Performance with large datasets

**Calculation Tests** (`calculations.test.js`)
- Percentage savings calculations
- Dollar amount savings calculations
- Value ranking algorithms
- Price validation
- Data formatting
- Statistical calculations

### Integration Tests (`tests/integration/`)

**API Tests** (`api.test.js`)
- GET /api/auctions - Retrieve all auctions
- GET /api/best-values - Best value auctions
- GET /api/stats - Statistics and analytics
- GET /api/logs - System logs
- GET /api/csv - CSV data export
- GET /api/status - System health check
- Error handling
- CORS configuration

### End-to-End Tests (`tests/e2e/`)

**System Tests** (`system.test.js`)
- Complete data pipeline (insert → query → export)
- Data consistency across operations
- Search and filter workflows
- Data export and reporting
- System health checks
- Error recovery
- Performance under load

### Performance Tests (`tests/performance/`)

**Load Tests** (`load-test.js`)
- Response time benchmarks
- Concurrent request handling (10, 50, 100+ requests)
- Large dataset performance (2000+ records)
- Database query performance
- Memory usage and leak detection
- Throughput testing
- Connection management

### Python Tests (`scripts/tests/`)

**Scraper Tests** (`test_scraper.py`)
- Database initialization
- Schema validation
- Data insertion and retrieval
- CSV export functionality
- Logging
- Error handling
- Search term configuration

## Test Fixtures

### Mock Data (`tests/fixtures/test-data.js`)
- Small dataset (5 auctions)
- Large dataset generator (1000+ auctions)
- Edge case data (zero prices, negative savings, missing data)

### Test Database (`tests/fixtures/test-database.js`)
- Database initialization utilities
- Seed data functions
- Cleanup functions
- Helper methods

## Coverage Requirements

### JavaScript Coverage Thresholds
```javascript
{
  global: {
    branches: 80,
    functions: 80,
    lines: 80,
    statements: 80
  }
}
```

### Python Coverage Thresholds
- Minimum 80% line coverage
- Reports generated in HTML and JSON formats

## Performance Benchmarks

### Response Time Targets
- GET /api/auctions: < 200ms
- GET /api/best-values: < 300ms
- GET /api/stats: < 250ms

### Concurrent Request Handling
- 10 concurrent requests: < 2 seconds
- 50 concurrent requests: < 5 seconds
- 100 concurrent requests: < 10 seconds

### Database Performance
- Simple SELECT queries: < 10ms average
- Complex analytical queries: < 100ms
- Large dataset operations (2000+ records): < 500ms

### Throughput
- Minimum 20 requests/second under sustained load

## Test Data

### Mock Auctions
All test data uses realistic auction data:
- Hermes Birkin bags
- Chanel Classic Flap bags
- Louis Vuitton Neverfull
- Dior Lady Dior
- Gucci Dionysus

### Price Ranges
- Current prices: $800 - $15,000
- Estimates: $1,200 - $22,000
- Savings: 10% - 50%

## Continuous Integration

### CI Configuration (`test:ci` script)
```bash
npm run test:ci
```

Features:
- Runs in CI mode (non-interactive)
- Generates coverage reports
- Limits workers to 2 for stability
- Fails on coverage threshold violations

### GitHub Actions Integration

Create `.github/workflows/test.yml`:
```yaml
name: Test Suite

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: cd auction-viewer && npm ci
      - run: cd auction-viewer && npm test
      - uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - run: pip install pytest pytest-cov
      - run: cd scripts && pytest
```

## Debugging Tests

### Enable Verbose Output
```bash
# JavaScript
npm test -- --verbose

# Python
pytest -vv
```

### Run Specific Tests
```bash
# JavaScript - run specific test file
npm test tests/unit/database.test.js

# JavaScript - run specific test suite
npm test -- -t "Database Operations"

# Python - run specific test
pytest tests/test_scraper.py::TestDatabaseInitialization::test_database_creation
```

### View Coverage Reports
```bash
# JavaScript - open HTML coverage report
open auction-viewer/coverage/lcov-report/index.html

# Python - open HTML coverage report
open scripts/htmlcov/index.html
```

## Common Issues and Solutions

### Issue: Tests Timeout
**Solution**: Increase timeout in jest.config.js or use `jest.setTimeout()`

### Issue: Database Lock Errors
**Solution**: Ensure all database connections are properly closed in afterEach/afterAll hooks

### Issue: Port Already in Use
**Solution**: Tests use in-memory databases and don't require server to be running

### Issue: Coverage Below Threshold
**Solution**: Add tests for uncovered code paths or adjust thresholds temporarily

## Best Practices

1. **Test Isolation**: Each test should be independent and not rely on others
2. **Cleanup**: Always clean up test databases and files in afterEach/afterAll
3. **Mock External Dependencies**: Don't make real HTTP requests in tests
4. **Descriptive Names**: Test names should clearly describe what they test
5. **Arrange-Act-Assert**: Follow AAA pattern in all tests
6. **Fast Tests**: Unit tests should run in milliseconds, not seconds
7. **Deterministic**: Tests should always produce the same results

## Test Metrics

### Current Coverage
Run `npm test` to see current coverage metrics.

### Test Count
- Unit Tests: ~60 tests
- Integration Tests: ~30 tests
- E2E Tests: ~25 tests
- Performance Tests: ~15 tests
- Python Tests: ~25 tests

**Total: ~155 comprehensive tests**

## Contributing

When adding new features:
1. Write tests first (TDD)
2. Ensure all tests pass
3. Maintain 80%+ coverage
4. Update this documentation if adding new test suites

## Support

For issues with tests:
1. Check test output for specific error messages
2. Review test fixtures and mock data
3. Ensure all dependencies are installed
4. Check database permissions and file paths