# CI/CD Pipeline Documentation

## Overview

This directory contains GitHub Actions workflows for continuous integration and continuous deployment (CI/CD) of the RAG System.

## Workflows

### Test Workflow (`test.yml`)

The main testing workflow that runs on every push and pull request to `main` and `develop` branches.

#### Jobs

1. **Test Job**
   - Runs on: Ubuntu Latest
   - Python versions: 3.11, 3.12
   - Steps:
     - Checkout code
     - Set up Python environment
     - Install dependencies
     - Run unit tests with coverage
     - Run integration tests with coverage
     - Run end-to-end tests with coverage
     - Upload coverage to Codecov
     - Upload coverage and test logs as artifacts

2. **Lint Job**
   - Runs code quality checks:
     - `flake8`: Python linting
     - `black`: Code formatting check
     - `isort`: Import sorting check
     - `mypy`: Static type checking

3. **Security Job**
   - Runs security scans:
     - `safety`: Checks for known security vulnerabilities in dependencies
     - `bandit`: Scans code for common security issues

4. **Build Status Job**
   - Aggregates results from all jobs
   - Fails if test job fails

## Test Execution

### Unit Tests
```bash
pytest tests/unit -v --cov=src --cov-report=xml --cov-report=term -m unit
```

### Integration Tests
```bash
pytest tests/integration -v --cov=src --cov-append --cov-report=xml --cov-report=term -m integration
```

### End-to-End Tests
```bash
pytest tests/e2e -v --cov=src --cov-append --cov-report=xml --cov-report=term -m e2e
```

## Coverage Requirements

- **Minimum Coverage**: 80%
- **Coverage Report**: Uploaded to Codecov
- **Coverage Artifacts**: Stored for 30 days

## Test Markers

Tests are organized using pytest markers:

- `unit`: Unit tests (isolated component tests)
- `integration`: Integration tests (component interaction tests)
- `e2e`: End-to-end tests (complete workflow tests)
- `slow`: Tests that take > 1 second
- `requires_db`: Tests requiring database connection
- `requires_vector_db`: Tests requiring vector database
- `requires_external_service`: Tests requiring external services
- `property`: Property-based tests using Hypothesis

## Running Tests Locally

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

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

# Integration tests only
pytest -m integration

# E2E tests only
pytest -m e2e

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

### With Coverage
```bash
# Generate HTML coverage report
pytest --cov=src --cov-report=html

# Generate terminal coverage report
pytest --cov=src --cov-report=term

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

## Codecov Integration

### Setup

1. Sign up at [codecov.io](https://codecov.io)
2. Add your repository
3. Get the upload token
4. Add the token as a GitHub secret:
   - Go to repository Settings → Secrets and variables → Actions
   - Add new secret: `CODECOV_TOKEN`

### Coverage Badge

Add to your README.md:
```markdown
[![codecov](https://codecov.io/gh/YOUR_USERNAME/YOUR_REPO/branch/main/graph/badge.svg)](https://codecov.io/gh/YOUR_USERNAME/YOUR_REPO)
```

## Artifacts

### Coverage Reports
- **Retention**: 30 days
- **Contents**: 
  - `coverage.xml`: XML coverage report
  - `htmlcov/`: HTML coverage report

### Test Logs
- **Retention**: 7 days
- **Contents**: 
  - `tests/logs/pytest.log`: Detailed test execution logs

### Security Reports
- **Retention**: 30 days
- **Contents**:
  - `bandit-report.json`: Security scan results

## Troubleshooting

### Tests Failing Locally but Passing in CI

1. Check Python version compatibility
2. Ensure all dependencies are installed
3. Check for environment-specific issues
4. Review test logs in artifacts

### Coverage Not Uploading to Codecov

1. Verify `CODECOV_TOKEN` is set correctly
2. Check if `coverage.xml` is generated
3. Review Codecov upload logs in workflow

### Slow Test Execution

1. Use test markers to run specific test suites
2. Consider parallel test execution with `pytest-xdist`
3. Review and optimize slow tests

## Best Practices

1. **Write Fast Tests**: Keep unit tests under 100ms
2. **Use Markers**: Tag tests appropriately for selective execution
3. **Mock External Dependencies**: Use mocks for external services in unit tests
4. **Maintain Coverage**: Keep coverage above 80%
5. **Review Artifacts**: Check test logs and coverage reports regularly
6. **Fix Failing Tests Immediately**: Don't let broken tests accumulate

## Future Enhancements

- [ ] Add deployment workflow
- [ ] Add performance benchmarking
- [ ] Add Docker image building
- [ ] Add automated dependency updates
- [ ] Add release automation
- [ ] Add notification integration (Slack, Discord)
- [ ] Add parallel test execution
- [ ] Add test result visualization

## References

- [GitHub Actions Documentation](https://docs.github.com/en/actions)
- [pytest Documentation](https://docs.pytest.org/)
- [Codecov Documentation](https://docs.codecov.com/)
- [Coverage.py Documentation](https://coverage.readthedocs.io/)