# RAG System Test Suite

This directory contains the comprehensive test suite for the RAG System refactoring project.

## Directory Structure

```
tests/
├── unit/                    # Unit tests for individual components
│   ├── domain/             # Domain layer tests
│   ├── application/        # Application layer tests
│   └── infrastructure/     # Infrastructure layer tests
├── integration/            # Integration tests for component interactions
│   ├── api/               # API integration tests
│   └── database/          # Database integration tests
├── e2e/                   # End-to-end tests for complete workflows
├── fixtures/              # Test data and fixtures
│   └── documents/         # Sample documents for testing
├── logs/                  # Test execution logs
├── conftest.py           # Global pytest configuration and fixtures
└── README.md             # This file
```

## Running Tests

### Run All Tests
```bash
pytest
```

### Run Specific Test Categories
```bash
# Unit tests only
pytest -m unit

# Integration tests only
pytest -m integration

# End-to-end tests only
pytest -m e2e

# Run tests in a specific directory
pytest tests/unit/
pytest tests/integration/
pytest tests/e2e/
```

### Run with Coverage
```bash
# Generate coverage report
pytest --cov=src --cov-report=html --cov-report=term

# View HTML coverage report
# Open htmlcov/index.html in your browser

# Generate XML coverage report (for CI/CD)
pytest --cov=src --cov-report=xml
```

### Run Property-Based Tests
```bash
# Run all property tests
pytest -m property

# Run property tests with verbose output
pytest -m property -v

# Run property tests with more examples
pytest -m property --hypothesis-show-statistics
```

### Run Tests with Different Verbosity
```bash
# Minimal output
pytest -q

# Verbose output
pytest -v

# Very verbose output (show test names and results)
pytest -vv
```

### Run Specific Tests
```bash
# Run a specific test file
pytest tests/unit/domain/test_entities.py

# Run a specific test class
pytest tests/unit/domain/test_entities.py::TestDocument

# Run a specific test method
pytest tests/unit/domain/test_entities.py::TestDocument::test_update_content
```

### Run Tests with Markers
```bash
# Run only slow tests
pytest -m slow

# Run tests that don't require database
pytest -m "not requires_db"

# Run unit tests that don't require external services
pytest -m "unit and not requires_external_service"
```

### Run Tests in Parallel
```bash
# Install pytest-xdist first: pip install pytest-xdist
pytest -n auto
```

### Run Tests with Timeout
```bash
# Install pytest-timeout first: pip install pytest-timeout
pytest --timeout=300
```

## Test Markers

The following markers are available for categorizing tests:

- `@pytest.mark.unit` - Unit tests (automatically added for tests in unit/)
- `@pytest.mark.integration` - Integration tests (automatically added for tests in integration/)
- `@pytest.mark.e2e` - End-to-end tests (automatically added for tests in e2e/)
- `@pytest.mark.slow` - Tests that take > 1 second
- `@pytest.mark.requires_db` - Tests requiring database connection
- `@pytest.mark.requires_vector_db` - Tests requiring vector database connection
- `@pytest.mark.requires_external_service` - Tests requiring external services
- `@pytest.mark.property` - Property-based tests using Hypothesis

## Writing Tests

### Unit Test Example
```python
# tests/unit/domain/test_entities.py
import pytest
from domain.vector_search.entities import Document

class TestDocument:
    """Document entity unit tests"""
    
    def test_update_content_changes_content(self):
        """Test that updating content changes the document content"""
        # Arrange
        doc = Document(id="1", content="original", ...)
        
        # Act
        doc.update_content("new content")
        
        # Assert
        assert doc.content == "new content"
```

### Integration Test Example
```python
# tests/integration/infrastructure/test_repositories.py
import pytest

@pytest.mark.integration
@pytest.mark.requires_db
class TestDocumentRepository:
    """Document repository integration tests"""
    
    async def test_save_and_find(self, test_db_session):
        """Test saving and finding a document"""
        # Test implementation
        pass
```

### Property-Based Test Example
```python
# tests/unit/domain/test_properties.py
from hypothesis import given, strategies as st
import pytest

class TestVectorProperties:
    """Vector property-based tests"""
    
    @pytest.mark.property
    @given(st.lists(st.floats(allow_nan=False), min_size=1))
    def test_vector_dimension_count(self, dimensions):
        """Property: Vector dimension count equals list length"""
        vector = Vector(dimensions)
        assert vector.dimension_count == len(dimensions)
```

### End-to-End Test Example
```python
# tests/e2e/test_document_workflow.py
import pytest
from httpx import AsyncClient

@pytest.mark.e2e
class TestDocumentWorkflow:
    """Document workflow end-to-end tests"""
    
    async def test_complete_lifecycle(self, client):
        """Test complete document lifecycle"""
        # Create -> Search -> Update -> Delete
        pass
```

## Test Fixtures

Global fixtures are defined in `conftest.py`:

- `event_loop` - Async event loop for async tests
- `reset_singletons` - Resets singleton instances between tests
- `test_data_dir` - Path to test data directory
- `sample_documents_dir` - Path to sample documents
- `mock_settings` - Mock configuration settings
- `test_db_session` - Test database session (to be implemented)
- `mock_vector_db` - Mock vector database (to be implemented)
- `mock_embedding_service` - Mock embedding service (to be implemented)

## Coverage Goals

- **Overall**: ≥ 80%
- **Domain Layer**: ≥ 90%
- **Application Layer**: ≥ 85%
- **Infrastructure Layer**: ≥ 70%
- **Presentation Layer**: ≥ 75%

## Continuous Integration

Tests are automatically run in CI/CD pipeline on:
- Every push to main branch
- Every pull request
- Scheduled daily runs

See `.github/workflows/test.yml` for CI configuration.

## Troubleshooting

### Tests Fail with Import Errors
Make sure you have installed all dependencies:
```bash
pip install -r requirements.txt
pip install pytest pytest-asyncio pytest-cov hypothesis httpx
```

### Async Tests Don't Run
Make sure `pytest-asyncio` is installed and `asyncio_mode = auto` is set in `pytest.ini`.

### Coverage Report Not Generated
Run pytest with coverage flags:
```bash
pytest --cov=src --cov-report=html
```

### Tests Are Too Slow
Run tests in parallel:
```bash
pip install pytest-xdist
pytest -n auto
```

## Best Practices

1. **Test Isolation**: Each test should be independent and not rely on other tests
2. **Clear Names**: Use descriptive test names that explain what is being tested
3. **AAA Pattern**: Structure tests with Arrange, Act, Assert sections
4. **Mock External Dependencies**: Use mocks for external services in unit tests
5. **Test Edge Cases**: Don't just test the happy path
6. **Keep Tests Fast**: Unit tests should run in < 100ms
7. **Use Fixtures**: Reuse common setup code with fixtures
8. **Document Complex Tests**: Add docstrings explaining what the test validates

## Resources

- [pytest Documentation](https://docs.pytest.org/)
- [pytest-asyncio Documentation](https://pytest-asyncio.readthedocs.io/)
- [pytest-cov Documentation](https://pytest-cov.readthedocs.io/)
- [Hypothesis Documentation](https://hypothesis.readthedocs.io/)
- [Testing Best Practices](https://docs.python-guide.org/writing/tests/)