Testing Guide

This guide covers the testing practices and requirements for AIMQ.

Test Structure

Tests are organized to mirror the source code structure:

tests/
├── aimq/
│   ├── test_worker.py
│   ├── test_queue.py
│   ├── test_job.py
│   ├── clients/
│   │   └── test_supabase_client.py
│   └── tools/
│       ├── ocr/
│       │   └── test_image_ocr.py
│       └── pdf/
│           └── test_pdf_processor.py
└── conftest.py

Running Tests

Run all tests:

poetry run pytest

Run with coverage:

poetry run pytest --cov=src

Run specific test file:

poetry run pytest tests/aimq/test_worker.py

Run tests matching a pattern:

poetry run pytest -k "test_process"

Writing Tests

Test Requirements

1. Coverage Requirements
2. Minimum 80% code coverage for new code
3. Critical components require 90%+ coverage

4. Integration tests required for public APIs

5. Test Types

6. Unit Tests: Test individual components in isolation
7. Integration Tests: Test component interactions
8. Functional Tests: Test complete features
9. Async Tests: Use pytest-asyncio for async code

Test Structure

Use pytest fixtures for test setup:

import pytest
from aimq import Worker

@pytest.fixture
def worker():
    worker = Worker()
    worker.register_queue("test_queue")
    return worker

def test_process_job(worker):
    result = worker.process({"data": "test"})
    assert result["status"] == "success"

Mocking

Use pytest's monkeypatch for mocking:

def test_supabase_client(monkeypatch):
    mock_client = MockSupabaseClient()
    monkeypatch.setattr("aimq.clients.supabase.client", mock_client)
    # Test code here

CI/CD Pipeline

Our GitHub Actions pipeline runs tests on:

• Pull requests to main branch
• Push to main branch
• Release tags

The pipeline:

1. Runs all tests
2. Generates coverage report
3. Checks code style
4. Builds documentation