feat: set up complete Python testing infrastructure with Poetry

[llbbl]

Set Up Python Testing Infrastructure

Summary

This PR establishes a complete testing infrastructure for the Python project using Poetry as the package manager and pytest as the testing framework. The setup provides a ready-to-use environment for writing and running tests with comprehensive tooling and configuration.

Changes Made

Package Management

• Migrated to Poetry: Created pyproject.toml with Poetry configuration
• Migrated dependencies: Transferred all dependencies from requirements.txt to Poetry
• Added test dependencies: pytest, pytest-cov, pytest-mock, pytest-asyncio

Testing Configuration

• pytest configuration in pyproject.toml:

  • Test discovery patterns for test_*.py and *_test.py files
  • Coverage settings with 80% threshold
  • HTML and XML coverage report generation
  • Custom markers: unit, integration, slow
  • Strict mode enabled for better error detection

• Coverage configuration:

  • Source directories: app, lib, task, util
  • Excluded: test files, cache, virtual environments, __init__.py files
  • Reports: terminal, HTML (htmlcov/), and XML (coverage.xml)

Directory Structure

tests/
├── __init__.py
├── conftest.py          # Shared fixtures
├── test_setup_validation.py  # Infrastructure validation
├── unit/
│   ├── __init__.py
│   └── test_example.py  # Example unit tests
└── integration/
    ├── __init__.py
    └── test_example_integration.py  # Example integration tests

Test Fixtures (conftest.py)

• temp_dir: Temporary directory for file operations
• mock_env_vars: Mock environment variables
• mock_config: Test configuration dictionary
• mock_discord_client: Mocked Discord client
• mock_fastapi_client: Mocked FastAPI client
• sample_discord_message: Sample Discord message data
• sample_api_response: Sample API response data
• reset_environment: Auto-reset environment variables
• mock_async_context: Mock async context manager
• capture_logs: Log capture utility

Development Commands

• poetry run test - Run all tests
• poetry run tests - Alternative command (both work)
• All standard pytest options are available

Additional Updates

• Updated .gitignore with:
  • Testing artifacts (.pytest_cache/, .coverage, htmlcov/, etc.)
  • Claude settings (.claude/*)
  • Poetry lock file is NOT ignored (as per best practices)
  • Build artifacts and IDE files

How to Use

1. Install dependencies:

   poetry install

2. Run all tests:

   poetry run test
   # or
   poetry run tests

3. Run specific test categories:

   # Unit tests only
   poetry run test -m unit
   
   # Integration tests only
   poetry run test -m integration
   
   # Exclude slow tests
   poetry run test -m "not slow"

4. Run with coverage:

   poetry run test  # Coverage is enabled by default
   # View HTML report at htmlcov/index.html

5. Run without coverage:

   poetry run test --no-cov

Validation

The setup includes validation tests (test_setup_validation.py) that verify:

• Python version compatibility (3.8+)
• Project structure integrity
• Fixture functionality
• Test markers registration
• Async test support
• Testing tools installation

All validation tests pass successfully, confirming the infrastructure is properly configured.

Notes

• The 80% coverage threshold is currently not enforced for validation/example tests but will apply to actual application code
• Example test files demonstrate various testing patterns including mocking, fixtures, async tests, and parametrization
• The infrastructure supports both sync and async testing out of the box
• All test dependencies are isolated in the dev dependency group to keep production dependencies clean