tests/README.md

TradeFlow AI Test Suite

Overview

Comprehensive test suite covering critical security and reliability fixes implemented in the audit remediation.

Test Files

conftest.py

Shared fixtures for all tests:

• test_client: FastAPI test client
• mock_current_user: Authenticated operator user
• mock_admin_user: Authenticated admin user
• mock_supabase: Mocked Supabase AsyncClient
• Sample file bytes (PDF, PNG, malicious)

test_config.py

Configuration and environment variable tests:

• ✅ GEMINI_API_KEY is required (not hardcoded)
• ✅ GEMINI_API_KEY must come from environment variable
• ✅ CORS origins are controlled (not wildcard)

test_routers_batches.py

File upload validation tests:

• File magic number validation (detects spoofed files)
• File size limits (50MB max)
• MIME type validation
• Filename path traversal protection
• Batch creation with invalid files (rollback)
• Maximum 3 files per batch
• doc_types validation

test_routers_blockchain.py

Authorization and access control tests:

• ✅ Authentication required for blockchain endpoints
• ✅ Users can only access their company's batches
• ✅ Admins can access any batch
• ✅ Non-existent batch handling
• ✅ Batch ownership verification

test_ai_nodes_extract.py

AI node error handling tests:

• ✅ Validates required document fields (doc_id, pages)
• ✅ Handles empty document lists
• ✅ Catches only specific exceptions (ValueError, KeyError)
• ✅ Re-raises unexpected exceptions
• ✅ Correctly combines data from multiple documents

test_dependencies.py

JWT and authentication tests:

• ✅ Keycloak JWKS cached with TTL (1 hour)
• ✅ JWKS refreshes after TTL expires
• ✅ HTTP errors in JWKS fetch are handled
• ✅ CurrentUser stores all required fields

test_storage_service.py

Storage security tests:

• ✅ MinIO bucket created with private policy
• ✅ Bucket policy denies public access
• ✅ Existing buckets are handled correctly
• ✅ File upload paths are sanitized

Running Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=src --cov-report=html

# Run specific test file
pytest tests/test_config.py -v

# Run specific test
pytest tests/test_config.py::test_gemini_api_key_required -v

Coverage Goals

Target: 70% code coverage (as per pyproject.toml)

Current coverage baseline: 0% → Target: 70%+ after implementation

Critical Security Tests (Must Pass)

1. Config Tests - Ensure API keys are not hardcoded

   pytest tests/test_config.py -v
   

2. Authorization Tests - Ensure cross-company access is blocked

   pytest tests/test_routers_blockchain.py::test_get_blockchain_receipt_requires_ownership -v
   

3. File Validation Tests - Ensure spoofed files are rejected

   pytest tests/test_routers_batches.py::test_file_magic_number_validation -v
   

4. Error Handling Tests - Ensure exceptions are properly caught

   pytest tests/test_ai_nodes_extract.py::test_extraction_node_reraises_unknown_exceptions -v
   

5. Storage Security Tests - Ensure bucket policy is private

   pytest tests/test_storage_service.py::test_minio_bucket_policy_denies_public_access -v
   

Next Steps

1. Implement missing test bodies - The test structure is in place, implementation code needs to be added
2. Add integration tests - Test full pipeline (upload → extract → validate → blockchain)
3. Add performance tests - Ensure large file uploads are handled efficiently
4. Add stress tests - Test behavior under load (rate limiting, timeouts)
5. CI/CD integration - Add to GitHub Actions for automatic testing on PRs

Integration Testing

• Integration tests are marked with @pytest.mark.integration and should run against real service instances.
• Use docker-compose.integration.yml to start the required local services: Redis, MinIO, and ChromaDB.
• Run integration tests with:

cd apps/api
.venv/bin/python -m pytest -m integration tests/integration -q

Deterministic E2E Testing

When you want reliable end-to-end pipeline validation without external LLM variability, enable deterministic mode:

set DETERMINISTIC_E2E=1&&set RUN_KEYCLOAK=1&&set RUN_FULL_E2E=1&&python -m pytest tests/integration -q

The deterministic mode uses a stable LLM stub for apps/api/src/ai/nodes/extract.py, so the extraction and review flow can be validated without Gemini or other external model dependencies.

Keycloak E2E Provisioning

The repo includes scripts/keycloak/provision_e2e.py to provision a Keycloak E2E client/user and emit a .env.e2e file with an E2E_BEARER_TOKEN.

set KEYCLOAK_SERVER_URL=http://localhost:8080
set KEYCLOAK_ADMIN=admin
set KEYCLOAK_ADMIN_PASSWORD=admin1234
python scripts\keycloak\provision_e2e.py

Then run the guarded auth/E2E tests:

set RUN_KEYCLOAK=1&&set RUN_FULL_E2E=1&&python -m pytest tests/integration -q

The CI workflow .github/workflows/e2e.yml runs the full E2E flow with DETERMINISTIC_E2E=1 so the test pipeline remains stable without requiring a live LLM.

Notes

• All tests use pytest with pytest-asyncio for async support
• Tests use mocks to avoid external dependencies (Supabase, Gemini API)
• Tests follow AAA pattern: Arrange, Act, Assert