calminer/docs/testing.md

Testing Strategy

Overview

CalMiner will use a combination of unit, integration, and end-to-end tests to ensure quality.

Frameworks

• Backend: pytest for unit and integration tests.
• Frontend: (TBD) pytest with Selenium or Playwright.
• Database: pytest fixtures with psycopg2 for DB tests.

Test Types

• Unit Tests: Test individual functions/modules.
• Integration Tests: Test API endpoints and DB interactions.
• E2E Tests: (Future) Playwright for full user flows.

CI/CD

• Use GitHub Actions for CI.
• Run tests on pull requests.
• Code coverage target: 80% (using pytest-cov).

Running Tests

• Unit: pytest tests/unit/
• Integration: pytest tests/integration/
• All: pytest

Test Directory Structure

Organize tests under the tests/ directory mirroring the application structure:

tests/
  unit/
    test_<module>.py
  integration/
    test_<endpoint>.py
  fixtures/
    conftest.py

Writing Tests

• Name tests with the test_ prefix.
• Group related tests in classes or modules.
• Use descriptive assertion messages.

Fixtures and Test Data

• Define reusable fixtures in tests/fixtures/conftest.py.
• Use temporary in-memory databases or isolated schemas for DB tests.
• Load sample data via fixtures for consistent test environments.

Mocking and Dependency Injection

• Use unittest.mock to mock external dependencies.
• Inject dependencies via function parameters or FastAPI's dependency overrides in tests.

Code Coverage

• Install pytest-cov to generate coverage reports.
• Run with coverage: pytest --cov=calminer --cov-report=html.
• Ensure coverage meets the 80% threshold.

CI Integration

• Configure GitHub Actions workflow in .github/workflows/ci.yml to:
  • Install dependencies
  • Run pytest with coverage
  • Fail on coverage <80%
  • Upload coverage artifact