claude-os/tests/README.md

Claude OS Test Suite

Comprehensive tests for the Claude OS RAG system.

Setup

1. Install test dependencies:

   pip install -r requirements.txt
   

2. Set environment variables (optional):

   export TEST_OLLAMA_HOST=http://localhost:11434
   

   Note: Tests use SQLite database which is automatically created in the test environment.

Running Tests

Run all tests:

pytest

Run specific test categories:

# Unit tests only (fast, no external dependencies)
pytest -m unit

# Integration tests (require database, Ollama)
pytest -m integration

# Vector operation tests
pytest -m vector

# RAG engine tests
pytest -m rag

# API endpoint tests
pytest -m api

Run specific test files:

pytest tests/test_pg_vector.py
pytest tests/test_rag_engine.py
pytest tests/test_api.py

Run with coverage:

pytest --cov=app --cov-report=html
# Open htmlcov/index.html to view coverage report

Run with verbose output:

pytest -v

Run and stop on first failure:

pytest -x

Test Structure

• conftest.py - Shared fixtures and configuration
• test_rag_engine.py - RAG engine functionality
• test_embeddings.py - Embedding generation
• test_document_processing.py - Document ingestion and chunking
• test_api.py - FastAPI endpoints

Test Markers

Tests are categorized with markers:

• @pytest.mark.unit - Fast unit tests, no external dependencies
• @pytest.mark.integration - Integration tests requiring database/Ollama
• @pytest.mark.slow - Tests that may take several seconds
• @pytest.mark.embeddings - Tests involving embedding generation
• @pytest.mark.vector - Tests involving vector operations
• @pytest.mark.rag - Tests involving RAG engine
• @pytest.mark.api - Tests involving API endpoints

Fixtures

Common fixtures available in all tests:

• test_db_config - Database configuration
• db_connection - Test database connection (session-scoped)
• clean_db - Clean database before each test
• sample_kb - Sample knowledge base
• sample_embedding - Sample 768-dimensional embedding
• sample_documents - Sample documents with embeddings
• mock_ollama_embedding - Mock Ollama embedding model
• mock_ollama_llm - Mock Ollama LLM
• sample_text_file - Sample text file
• sample_pdf_file - Sample PDF file
• sample_markdown_file - Sample Markdown file
• api_client - FastAPI test client

CI/CD Integration

Tests can be run in CI/CD pipelines:

# Example GitHub Actions workflow
- name: Run tests
  run: |
    pytest --cov=app --cov-report=xml
    
- name: Upload coverage
  uses: codecov/codecov-action@v3

Troubleshooting

Ollama connection errors:

• Ensure Ollama is running: curl http://localhost:11434/api/tags
• Check TEST_OLLAMA_HOST environment variable

Import errors:

• Ensure you're in the project root directory
• Install all dependencies: pip install -r requirements.txt