feat: Set up comprehensive Python testing infrastructure with Poetry

[llbbl]

Set Up Python Testing Infrastructure

Summary

This PR establishes a comprehensive testing infrastructure for the SQLFlow client Python project using Poetry as the package manager and pytest as the testing framework. The setup provides a ready-to-use testing environment where developers can immediately start writing unit and integration tests.

Changes Made

Package Management

• Initialized Poetry with pyproject.toml configuration
• Migrated dependencies from requirements.txt (mkdocs, mkdocs-material, etc.)
• Added testing dependencies as development dependencies:
  • pytest ^7.4.3 - Main testing framework
  • pytest-cov ^4.1.0 - Coverage reporting
  • pytest-mock ^3.12.0 - Mocking utilities

Testing Configuration

• Configured pytest in pyproject.toml with:

  • Test discovery patterns for test_*.py and *_test.py files
  • Coverage reporting with HTML, XML, and terminal output
  • Custom test markers: unit, integration, slow
  • Strict mode and verbose output by default
  • Coverage threshold set to 0% for validation (should be changed to 80% when adding real tests)

• Configured coverage settings:

  • Source directory: api/
  • Exclusions for test files, virtual environments, and build artifacts
  • Report generation in htmlcov/ and coverage.xml

Directory Structure

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

Testing Fixtures (conftest.py)

Created comprehensive fixtures for common testing needs:

• temp_dir - Temporary directory management
• sample_sql_query - Sample SQL for testing
• mock_config - Configuration dictionary
• config_file - Temporary config file creation
• mock_http_client - HTTP client mocking
• mock_database_connection - Database connection mocking
• sample_api_response - API response examples
• sql_file - SQL file creation
• mock_env_vars - Environment variable setup
• mock_file_system - File system structure creation
• mock_logger - Logger mocking

Poetry Scripts

Added convenient test commands:

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

.gitignore Updates

Added entries for:

• Testing artifacts (.pytest_cache/, .coverage, htmlcov/, etc.)
• Poetry/build artifacts (dist/, *.egg-info/, build/)
• Claude settings (.claude/*)
• IDE files (.vscode/, .idea/, vim swap files)

How to Use

1. Install dependencies:

   poetry install

2. Run tests:

   poetry run test      # or poetry run tests

3. Run specific test categories:

   poetry run pytest -m unit         # Run only unit tests
   poetry run pytest -m integration  # Run only integration tests
   poetry run pytest -m "not slow"   # Skip slow tests

4. Run tests without coverage:

   poetry run pytest --no-cov

5. View coverage report:

   • HTML report: Open htmlcov/index.html in a browser
   • XML report: Available at coverage.xml for CI integration

Validation

The infrastructure has been validated with 14 passing tests that verify:

• pytest is working correctly
• All fixtures are accessible and functional
• Test markers are recognized
• Coverage tracking is operational
• Both poetry run test and poetry run tests commands work

Notes

• The coverage threshold is currently set to 0% for infrastructure validation. This should be changed to 80% in pyproject.toml (both in pytest options and coverage settings) when real tests are added.
• The api/ directory is configured as the source for coverage tracking, assuming this is where the main Python code will reside.
• All standard pytest options remain available when using the Poetry scripts.

Next Steps

Developers can now:

1. Write unit tests in tests/unit/
2. Write integration tests in tests/integration/
3. Use the provided fixtures for common testing scenarios
4. Adjust coverage thresholds as the test suite grows