feat: Add complete Python testing infrastructure with Poetry

[llbbl]

Add Python Testing Infrastructure

Summary

This PR sets up a complete testing infrastructure for the shootback project using Poetry as the package manager and pytest as the testing framework. The infrastructure is ready for developers to immediately start writing unit and integration tests.

Changes Made

Package Management

• Poetry Setup: Created pyproject.toml with Poetry configuration as the project's package manager
• Package Mode: Configured as dependency-only mode (package-mode = false) since shootback uses only standard library
• Python Version: Set to ^3.7 to ensure compatibility with modern testing tools

Testing Dependencies

Added as development dependencies:

• pytest (^7.4.0) - Main testing framework
• pytest-cov (^4.1.0) - Coverage reporting
• pytest-mock (^3.11.1) - Mocking utilities

Testing Configuration

Configured in pyproject.toml:

• Test Discovery: Looks for test_*.py and *_test.py files
• Coverage Settings:
  • 80% coverage threshold
  • HTML and XML report generation
  • Excludes test files, virtual environments, and build artifacts
• Custom Markers:
  • unit - For unit tests
  • integration - For integration tests
  • slow - For slow-running tests

Directory Structure

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

Shared Fixtures (conftest.py)

• temp_dir - Temporary directory for test files
• mock_socket - Mock socket object
• mock_ssl_context - Mock SSL context
• free_port - Find available port for testing
• mock_config - Sample configuration dictionary
• mock_logger - Mock logger for testing
• thread_cleanup - Ensure threads are cleaned up
• mock_threading_event - Mock threading Event
• sample_binary_data / sample_text_data - Test data
• mock_server_socket - Mock server socket
• reset_modules - Reset singleton modules between tests

Poetry Scripts

• poetry run test - Run all tests
• poetry run tests - Alternative command (both work)

Updated .gitignore

Added entries for:

• Testing artifacts (.pytest_cache/, .coverage, htmlcov/, etc.)
• Claude settings (.claude/*)
• Virtual environments and IDE files
• Note: poetry.lock is NOT ignored (should be committed)

How to Use

1. Install dependencies:

   poetry install
   

2. Run all tests:

   poetry run pytest
   # or
   poetry run test
   

3. Run specific test types:

   # Unit tests only
   poetry run pytest -m unit
   
   # Integration tests only
   poetry run pytest -m integration
   
   # Without coverage
   poetry run pytest --no-cov
   

4. View coverage report:

   • HTML report: Open htmlcov/index.html in browser
   • XML report: coverage.xml (for CI/CD integration)

Validation

The setup includes test_setup_validation.py which verifies:

• All testing dependencies are properly installed
• Project modules can be imported
• Pytest fixtures are available
• Test markers work correctly
• Coverage is configured
• Python path includes project root

All validation tests pass successfully.

Notes

• The project maintains its "no external dependencies" philosophy for runtime code
• Testing dependencies are isolated to development only
• Coverage threshold is set to 80% but can be adjusted in pyproject.toml
• The infrastructure is compatible with Python 3.7+ to support modern testing tools