test: add pytest test suite for rotator_library core modules (64 tests)

.github/workflows/tests.yml

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: LGPL-3.0-only
+# Copyright (c) 2026 Mirrowel
+
+name: Tests
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+    paths:
+      - 'src/rotator_library/**'
+      - 'tests/**'
+      - 'pytest.ini'
+      - 'requirements.txt'
+      - '.github/workflows/tests.yml'
+  pull_request:
+    paths:
+      - 'src/rotator_library/**'
+      - 'tests/**'
+      - 'pytest.ini'
+      - 'requirements.txt'
+      - '.github/workflows/tests.yml'
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ['3.12', '3.13']
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        shell: bash
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest pytest-asyncio
+          # Install rotator_library dependencies (skip editable install line)
+          grep -v -- '-e src/rotator_library' requirements.txt > temp_requirements.txt
+          pip install -r temp_requirements.txt
+          pip install -e src/rotator_library
+          rm -f temp_requirements.txt
+
+      - name: Run tests
+        shell: bash
+        run: pytest -v

CONTRIBUTING.md

@@ -60,13 +60,37 @@ All new source files **must** include the appropriate license header:
 - Use type hints where practical
 - Keep functions focused and well-documented
 
+### Running Tests
+
+The project uses `pytest` for testing. The test suite covers self-contained modules
+in the resilience library (`rotator_library`).
+
+```bash
+# Install test dependencies
+pip install pytest pytest-asyncio
+
+# Run the full test suite
+pytest
+
+# Run a specific test module
+pytest tests/test_request_sanitizer.py
+
+# Run with verbose output
+pytest -v
+```
+
+When adding new features or fixing bugs, include tests in the `tests/` directory.
+Follow the existing test file naming convention (`test_*.py`) and use descriptive
+class names to group related tests.
+
 ## Pull Requests
 
 1. Fork the repository and create a feature branch
 2. Make your changes with clear commit messages
 3. Reference related issues in commits: `feat(providers): add X provider (#123)`
 4. Open a PR with a clear description of what changed and why
 5. Ensure your changes include necessary documentation updates
+6. Add or update tests for any changed behavior
 
 ## Reporting Issues
 

pytest.ini

@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: LGPL-3.0-only
+# Copyright (c) 2026 Mirrowel
+
+[pytest]
+testpaths = tests
+asyncio_mode = auto
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_*

tests/conftest.py

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: LGPL-3.0-only
+# Copyright (c) 2026 Mirrowel
+
+"""
+Pytest configuration and shared fixtures for the rotator_library test suite.
+
+This conftest adds the source directories to sys.path so that both
+standalone modules (request_sanitizer, session_tracking, etc.) and
+package-qualified modules (rotator_library.core.utils) can be imported
+without requiring a full editable install of every dependency.
+"""
+
+import sys
+from pathlib import Path
+
+# Resolve the repository root (tests/ -> parent)
+_REPO_ROOT = Path(__file__).resolve().parent.parent
+_SRC_ROOT = _REPO_ROOT / "src"
+_LIB_ROOT = _SRC_ROOT / "rotator_library"
+
+# Prepend source paths so that:
+#   - `import rotator_library.X` works  (via _SRC_ROOT)
+#   - `from request_sanitizer import ...` works  (via _LIB_ROOT)
+for _path in (_SRC_ROOT, _LIB_ROOT):
+    _str = str(_path)
+    if _str not in sys.path:
+        sys.path.insert(0, _str)

tests/test_cooldown_manager.py

@@ -0,0 +1,128 @@
+# SPDX-License-Identifier: LGPL-3.0-only
+# Copyright (c) 2026 Mirrowel
+
+"""
+Tests for cooldown_manager.CooldownManager.
+
+CooldownManager tracks per-provider cooldown periods to handle
+IP-based rate limiting. When a 429 is received, all requests to
+that provider are paused for a configurable duration.
+"""
+
+import asyncio
+import time
+from unittest.mock import patch
+
+import pytest
+
+from cooldown_manager import CooldownManager
+
+
+class TestCooldownBasics:
+    """Basic functionality tests."""
+
+    @pytest.mark.asyncio
+    async def test_provider_not_cooling_down_initially(self):
+        cm = CooldownManager()
+        assert await cm.is_cooling_down("openai") is False
+
+    @pytest.mark.asyncio
+    async def test_start_cooldown_makes_provider_cooling(self):
+        cm = CooldownManager()
+        await cm.start_cooldown("openai", 60)
+        assert await cm.is_cooling_down("openai") is True
+
+    @pytest.mark.asyncio
+    async def test_different_providers_independent(self):
+        cm = CooldownManager()
+        await cm.start_cooldown("openai", 60)
+        assert await cm.is_cooling_down("openai") is True
+        assert await cm.is_cooling_down("anthropic") is False
+
+
+class TestCooldownRemaining:
+    """Tests for remaining time calculations."""
+
+    @pytest.mark.asyncio
+    async def test_remaining_cooldown_positive(self):
+        cm = CooldownManager()
+        await cm.start_cooldown("openai", 100)
+        remaining = await cm.get_cooldown_remaining("openai")
+        # Should be close to 100 but slightly less due to execution time
+        assert 90 <= remaining <= 100
+
+    @pytest.mark.asyncio
+    async def test_remaining_cooldown_zero_if_not_cooling(self):
+        cm = CooldownManager()
+        remaining = await cm.get_cooldown_remaining("openai")
+        assert remaining == 0
+
+    @pytest.mark.asyncio
+    async def test_remaining_cooldown_after_expiry(self):
+        cm = CooldownManager()
+        await cm.start_cooldown("openai", 0)
+        # With duration=0, the cooldown is set to exactly now
+        # By the time we check, time has advanced
+        await asyncio.sleep(0.01)
+        remaining = await cm.get_cooldown_remaining("openai")
+        assert remaining == 0
+
+    @pytest.mark.asyncio
+    async def test_get_remaining_cooldown_alias(self):
+        """get_remaining_cooldown is a backward-compatible alias."""
+        cm = CooldownManager()
+        await cm.start_cooldown("openai", 50)
+        r1 = await cm.get_cooldown_remaining("openai")
+        r2 = await cm.get_remaining_cooldown("openai")
+        assert abs(r1 - r2) < 1  # Should be nearly identical
+
+
+class TestCooldownExpiry:
+    """Tests for cooldown expiration behavior."""
+
+    @pytest.mark.asyncio
+    async def test_cooldown_expires(self):
+        cm = CooldownManager()
+        await cm.start_cooldown("openai", 1)
+        assert await cm.is_cooling_down("openai") is True
+        # Patch the clock to advance past expiry without real sleeping
+        with patch("cooldown_manager.time.time", return_value=time.time() + 1.1):
+            assert await cm.is_cooling_down("openai") is False
+
+    @pytest.mark.asyncio
+    async def test_cooldown_extends_on_new_start(self):
+        cm = CooldownManager()
+        await cm.start_cooldown("openai", 5)
+        r1 = await cm.get_cooldown_remaining("openai")
+
+        await cm.start_cooldown("openai", 100)
+        r2 = await cm.get_cooldown_remaining("openai")
+
+        assert r2 > r1
+
+
+class TestCooldownConcurrency:
+    """Tests for concurrent access safety."""
+
+    @pytest.mark.asyncio
+    async def test_concurrent_start_and_check(self):
+        cm = CooldownManager()
+        # Multiple concurrent operations should not cause issues
+        await asyncio.gather(
+            cm.start_cooldown("openai", 10),
+            cm.start_cooldown("anthropic", 20),
+            cm.is_cooling_down("openai"),
+            cm.is_cooling_down("anthropic"),
+            cm.is_cooling_down("gemini"),
+        )
+        assert await cm.is_cooling_down("openai") is True
+        assert await cm.is_cooling_down("anthropic") is True
+        assert await cm.is_cooling_down("gemini") is False
+
+    @pytest.mark.asyncio
+    async def test_concurrent_reads(self):
+        cm = CooldownManager()
+        await cm.start_cooldown("openai", 10)
+        # Many concurrent reads
+        results = await asyncio.gather(*[cm.is_cooling_down("openai") for _ in range(100)])
+        assert all(results)