README.md

Test Suite Documentation

Overview

Sentinal uses pytest for testing. The suite covers unit tests for core components and integration tests for major workflows.

Prerequisites

Install development dependencies:

pip install -r requirements-dev.txt

Running Tests

Run all tests:

pytest

Run specific category:

pytest tests/unit
pytest tests/integration

Generate coverage report:

pytest --cov=src --cov-report=html

Test Architecture

The Sentinal test suite is built on pytest and follows a layered architecture to ensure isolation and reliability.

1. Structure

• Unit Tests (tests/unit/): Test individual components in isolation. External dependencies (ArXiv API, Google Gemini, Database) are always mocked.
• Integration Tests (tests/integration/): Test the flow between components. These use a temporary local database (SQLite) and mock external network calls, but verify that components interact correctly (e.g., Researcher -> Database -> RAG).
• Fixtures (tests/conftest.py): Shared setup code.
  • mock_settings: Overrides src.core.config.settings to prevent loading real .env files.
  • managed_db: Creates a temporary SQLite database for integration tests.

2. Mocking Strategy

We use unittest.mock and pytest-mock to detach from external systems:

• ArXiv Client: Mocked to return predefined Result objects.
• LLM (Gemini): Mocked to return static JSON strings avoiding API costs.
• Database: Unit tests mock the DB calls; Integration tests use a fresh DB file per session.

Development Guidelines

• No External Calls: Tests must run without internet access (except for installing deps).
• Speed: Unit tests should execute in milliseconds.
• Coverage: New features must include tests. Run pytest --cov=src to verify.

CI/CD

Tests are configured to run on every PR. Ensure 60% coverage minimum.