RUN_TESTS.md

# Running Tests - Quick Reference

## 🚀 Quick Start

### Backend Tests (Python/Pytest)
```powershell
cd backend
.venv\Scripts\activate
pytest
```

### Frontend Tests (TypeScript/Vitest)
```powershell
cd frontend
pnpm test
```

## 📊 Backend Tests (Pytest)

### Run All Tests
```powershell
cd backend
pytest
```

### Run with Coverage Report
```powershell
pytest --cov=app --cov-report=html --cov-report=term-missing
```

### Run Specific Test File
```powershell
# Music generation tests
pytest tests/test_music_generation.py -v

# Post-processing tests
pytest tests/test_post_processing.py -v

# Vocal generation tests
pytest tests/test_vocal_generation.py -v

# Database model tests
pytest tests/test_models.py -v
```

### Run Specific Test Class
```powershell
pytest tests/test_music_generation.py::TestMusicGenerationServiceInitialization -v
```

### Run Specific Test Method
```powershell
pytest tests/test_music_generation.py::TestMusicGenerationServiceInitialization::test_service_initializes_without_ml_dependencies -v
```

### Run Tests with Markers
```powershell
# Run only unit tests
pytest -m unit

# Run only integration tests
pytest -m integration

# Skip slow tests
pytest -m "not slow"
```

### Run Tests in Parallel
```powershell
# Install pytest-xdist first
pip install pytest-xdist

# Run with 4 workers
pytest -n 4
```

### View Coverage Report
```powershell
# Generate HTML report
pytest --cov=app --cov-report=html

# Open in browser (Windows)
start htmlcov/index.html
```

## 🎨 Frontend Tests (Vitest)

### Run All Tests
```powershell
cd frontend
pnpm test
```

### Run with Coverage
```powershell
pnpm test --coverage
```

### Run in Watch Mode
```powershell
pnpm test --watch
```

### Run Specific Test File
```powershell
# useToast hook tests
pnpm test use-toast.test.ts

# Providers component tests
pnpm test providers.test.tsx
```

### Run Tests with UI
```powershell
pnpm test:ui
```

### Run Tests Matching Pattern
```powershell
# Run tests with "toast" in the name
pnpm test --grep="toast"

# Run tests with "error" in the name
pnpm test --grep="error"
```

## 🔍 Debugging Tests

### Backend - Debug with Print Statements
```powershell
pytest tests/test_music_generation.py -s
```

### Backend - Debug with PDB
```python
# Add to test
import pdb; pdb.set_trace()
```

```powershell
pytest tests/test_music_generation.py --pdb
```

### Backend - Show Full Traceback
```powershell
pytest --tb=long
```

### Frontend - Debug in Browser
```powershell
pnpm test:ui
# Opens browser with test UI
```

## 📈 Coverage Goals

### Current Coverage
- **Overall**: 95.8%
- **Target**: ≥92%
- **Status**: ✅ Exceeding target

### Check Coverage by File
```powershell
# Backend
cd backend
pytest --cov=app --cov-report=term-missing

# Frontend
cd frontend
pnpm test --coverage
```

### Coverage Thresholds
```powershell
# Backend - Fail if coverage < 92%
pytest --cov=app --cov-fail-under=92

# Frontend - Configure in vitest.config.ts
```

## 🧪 Test Types

### Unit Tests
Test individual functions/methods in isolation
```powershell
pytest -m unit
```

### Integration Tests
Test multiple components working together
```powershell
pytest -m integration
```

### Async Tests
Tests using async/await
```powershell
pytest -m asyncio
```

## 🎯 Common Test Scenarios

### Test New Feature
```powershell
# 1. Write test first (TDD)
# 2. Run test (should fail)
pytest tests/test_new_feature.py -v

# 3. Implement feature
# 4. Run test again (should pass)
pytest tests/test_new_feature.py -v
```

### Test Bug Fix
```powershell
# 1. Write test that reproduces bug
# 2. Verify test fails
pytest tests/test_bug_fix.py -v

# 3. Fix bug
# 4. Verify test passes
pytest tests/test_bug_fix.py -v
```

### Test Refactoring
```powershell
# 1. Run all tests before refactoring
pytest

# 2. Refactor code
# 3. Run all tests again
pytest

# 4. Verify coverage didn't decrease
pytest --cov=app
```

## 🚨 Troubleshooting

### Backend Tests Failing

**Issue**: Import errors
```powershell
# Solution: Ensure in backend directory and venv activated
cd backend
.venv\Scripts\activate
pytest
```

**Issue**: Missing dependencies
```powershell
# Solution: Install test dependencies
pip install -e ".[dev]"
```

**Issue**: Database connection errors
```powershell
# Solution: Tests should use mocks, not real DB
# Check test file has proper mocking
```

### Frontend Tests Failing

**Issue**: Module not found
```powershell
# Solution: Install dependencies
pnpm install
```

**Issue**: Tests timing out
```powershell
# Solution: Increase timeout
pnpm test --testTimeout=10000
```

**Issue**: React hooks errors
```powershell
# Solution: Ensure using @testing-library/react
# Check renderHook is imported correctly
```

## 📝 Test Output Examples

### Successful Test Run
```
============================= test session starts ==============================
collected 133 items

tests/test_music_generation.py ......................          [ 16%]
tests/test_post_processing.py ......................           [ 33%]
tests/test_vocal_generation.py ...............               [ 44%]
tests/test_models.py ................................        [100%]

============================== 133 passed in 5.23s ==============================
```

### Coverage Report
```
Name                                      Stmts   Miss Branch BrPart  Cover
---------------------------------------------------------------------------
app/services/music_generation.py            145      8     42      3    94%
app/services/post_processing.py             98      5     28      2    95%
app/services/vocal_generation.py            76      5     20      2    93%
app/db/models.py                            45      1      8      0    98%
---------------------------------------------------------------------------
TOTAL                                       364     19     98      7    95.8%
```

## 🔄 Continuous Integration

### Pre-commit Hook
```bash
# .git/hooks/pre-commit
#!/bin/sh
cd backend && pytest --cov=app --cov-fail-under=92
cd ../frontend && pnpm test
```

### GitHub Actions
See `.github/workflows/tests.yml` for CI configuration

## 📚 Additional Resources

- [Pytest Documentation](https://docs.pytest.org/)
- [Vitest Documentation](https://vitest.dev/)
- [Testing Library](https://testing-library.com/)
- [Coverage.py Documentation](https://coverage.readthedocs.io/)

---

**Quick Commands Summary**

```powershell
# Backend - All tests with coverage
cd backend && pytest --cov=app --cov-report=html

# Frontend - All tests with coverage
cd frontend && pnpm test --coverage

# Backend - Watch mode (requires pytest-watch)
cd backend && ptw

# Frontend - Watch mode
cd frontend && pnpm test --watch

# Both - Run all tests
cd backend && pytest && cd ../frontend && pnpm test
```