feat: Add comprehensive Python testing infrastructure

[llbbl]

Add Python Testing Infrastructure

Summary

This PR sets up a comprehensive testing infrastructure for the ABPTTS (A Black Path Toward The Sun) project using Poetry for dependency management and pytest as the testing framework.

Changes Made

Package Management

• Poetry Configuration: Created pyproject.toml with Poetry configuration in package-mode=false (since this is a script collection, not a distributable package)
• Dependencies: Added testing dependencies as development dependencies:
  • pytest (^8.3.4) - Core testing framework
  • pytest-cov (^5.0.0) - Coverage reporting
  • pytest-mock (^3.14.0) - Mocking utilities

Testing Configuration

• pytest Settings: Configured in pyproject.toml with:

  • Strict markers and configuration
  • Coverage reporting with HTML and XML output
  • Custom test markers: unit, integration, and slow
  • Test discovery patterns for test_*.py and *_test.py files

• Coverage Settings:

  • Source directory set to project root
  • Excluded test files, cache directories, and virtual environments
  • Detailed reporting with line precision and missing line indicators

Directory Structure

tests/
├── __init__.py
├── conftest.py          # Shared pytest fixtures
├── test_infrastructure.py # Validation tests
├── unit/
│   └── __init__.py
└── integration/
    └── __init__.py

Shared Fixtures (conftest.py)

Created comprehensive fixtures for common testing needs:

• temp_dir - Temporary directory management
• temp_file - Temporary file creation
• mock_config - Mock configuration objects
• mock_settings - Mock settings dictionary
• mock_http_response - Mock HTTP responses
• mock_socket - Mock socket objects
• sample_data_files - Sample data file generation
• mock_logger - Mock logger for testing logging
• reset_environment - Environment variable isolation
• isolated_filesystem - Isolated filesystem for tests
• capture_logs - Log capture utility

Additional Setup

• .gitignore: Updated with comprehensive Python testing patterns and Claude-specific entries
• run_tests.sh: Helper script for running tests with Poetry
• Validation Tests: Created test_infrastructure.py to verify the testing setup works correctly

How to Use

Install Dependencies

poetry install --with dev

Run Tests

Using Poetry directly:

poetry run pytest                    # Run all tests
poetry run pytest tests/unit        # Run only unit tests
poetry run pytest -m integration    # Run only integration tests
poetry run pytest --no-cov          # Run without coverage

Using the helper script:

./run_tests.sh                      # Run all tests
./run_tests.sh tests/unit           # Run specific directory
./run_tests.sh -v                   # Run with verbose output

Coverage Reports

After running tests, coverage reports are available in:

• Terminal output (automatically displayed)
• HTML report: htmlcov/index.html
• XML report: coverage.xml

Notes

• The project uses Poetry in non-package mode since ABPTTS is a collection of scripts rather than a distributable package
• Coverage threshold is not enforced by default to allow gradual test adoption
• The infrastructure is ready for immediate use - developers can start writing tests in the appropriate directories
• All test dependencies are isolated in the development group to keep production dependencies clean

Next Steps

With this infrastructure in place, the team can now:

1. Write unit tests for individual modules (libabptts.py, abpttsclient.py, etc.)
2. Create integration tests for the complete tunneling workflow
3. Add performance tests using the @pytest.mark.slow marker
4. Integrate testing into CI/CD pipelines using the generated coverage.xml