feat: Set up comprehensive Python testing infrastructure

[llbbl]

Set up Python Testing Infrastructure

Summary

This PR establishes a complete testing infrastructure for the Artie project, enabling developers to write and run tests with ease. The setup includes Poetry package management, pytest configuration with coverage reporting, and comprehensive test fixtures.

Changes Made

Package Management

• Added Poetry as package manager with pyproject.toml configuration
• Migrated dependencies from requirements.txt to Poetry format
• Configured development dependencies for testing (pytest, pytest-cov, pytest-mock, toml)

Testing Configuration

• Configured pytest with comprehensive settings in pyproject.toml:
  • Test discovery patterns for files, classes, and functions
  • Coverage reporting with 80% threshold requirement
  • HTML and XML coverage report generation
  • Strict configuration and marker validation
  • Custom markers: unit, integration, slow

Directory Structure

• Created testing directories:
  • tests/ - Main test directory
  • tests/unit/ - Unit tests
  • tests/integration/ - Integration tests
  • All with proper __init__.py files

Test Infrastructure

• Comprehensive test fixtures in tests/conftest.py:
  • temp_dir - Temporary directory creation
  • sample_config - Mock configuration data
  • config_file - Temporary config file creation
  • sample_rom_data - Mock ROM metadata
  • mock_rom_files - Mock ROM file structure
  • sample_image - PIL image fixtures
  • Mock objects for all major components (cache, logger, config, etc.)

Development Environment

• Updated .gitignore with testing-related entries:
  • Coverage files (.coverage, htmlcov/, coverage.xml)
  • pytest cache (.pytest_cache/)
  • Virtual environments, IDE files, build artifacts
  • Claude Code settings (.claude/*)

Validation

• Created infrastructure validation tests (tests/test_infrastructure.py):
  • Verify pytest functionality and markers
  • Test fixture availability and functionality
  • Validate project structure
  • Confirm pyproject.toml configuration

How to Run Tests

Using Poetry (Recommended)

# Install dependencies
poetry install

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=src

# Run specific test types
poetry run pytest -m unit
poetry run pytest -m integration
poetry run pytest -m slow

# Run tests with verbose output
poetry run pytest -v

Coverage Reports

• Terminal: Coverage summary displayed after test run
• HTML: Generated in htmlcov/ directory
• XML: Generated as coverage.xml for CI integration

Dependencies Added

Production Dependencies

• requests==2.32.4 (migrated from requirements.txt)
• Pillow==11.3.0 (migrated from requirements.txt)

Test Dependencies

• pytest ^8.0.0 - Testing framework
• pytest-cov ^5.0.0 - Coverage reporting
• pytest-mock ^3.12.0 - Mocking utilities
• toml ^0.10.2 - TOML parsing for configuration validation

Configuration Notes

• Python version requirement: Updated to ^3.9 (required by Pillow 11.3.0)
• Coverage threshold: Set to 80% (configurable in pyproject.toml)
• Test discovery: Automatic discovery of test_*.py and *_test.py files
• Strict mode: Enabled for markers and configuration validation

Ready for Development

This infrastructure provides everything needed to start writing comprehensive tests:

• ✅ Package management with Poetry
• ✅ Test framework with pytest
• ✅ Coverage reporting
• ✅ Mock and fixture utilities
• ✅ Organized test structure
• ✅ Development environment configuration

Developers can now immediately start writing unit and integration tests for the Artie codebase with full coverage tracking and professional testing practices.

[milouk]

Thank you for your contribution. Could you integrate it with the CI/CD pipeline ?

[llbbl]

Hey, Michael. This first PR is meant to just set up testing. But, okay. Are you running your CI/CD in GitHub Actions?

[milouk]

Yes. Also it is not clear to me how to run tests locally. Can you please add some instructions?

[llbbl]

Can you handle making a VM with MuOS? Seems with QEMU we can run it in a github action.

example:
https://github.com/etchdroid/qemu-kvm-action

From Gemini:

build vm

# 1. Start the emulator in the background. Redirect serial output for debugging.
qemu-system-x86_64 \
  -hda mustard_os.img \
  -virtfs local,path=./artie,mount_tag=host_share \
  -nographic \
  -serial file:serial.log &

# 2. Wait for the results file to appear, or for QEMU to exit.
echo "Waiting for tests to complete..."
while [ ! -f ./artie/results.txt ]; do
  sleep 2
done

# 3. Print results and clean up.
echo "Tests finished!"
cat ./artie/results.txt

# The VM should have shut itself down, or you can kill the process.

github action

# A name for your workflow, which will be displayed on the Actions tab
name: CI for Mustard OS Project

# Triggers the workflow on any push or pull request to the main branch
on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  # A single job in this workflow, called "build-and-test"
  build-and-test:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    steps:
      # Step 1: Check out your repository's code
      - name: Check out repository
        uses: actions/checkout@v4

      # Step 2: Install build dependencies for Mustard OS (e.g., GCC, make)
      - name: Install Build Dependencies
        run: sudo apt-get update && sudo apt-get install -y build-essential qemu-system-x86

      # Step 3: Cache the built OS image to speed up future runs
      # The cache is restored if the source files in 'mustard-os-source/' have not changed.
      - name: Cache Mustard OS Image
        id: cache-os-image
        uses: actions/cache@v4
        with:
          # The path to the file we want to cache
          path: mustard_os.img
          # The key that identifies the cache. If files in the source dir change,
          # the hash changes, invalidating the cache.
          key: ${{ runner.os }}-mustard-os-${{ hashFiles('mustard-os-source/**') }}

      # Step 4: Build the OS image *only if* it was not found in the cache
      - name: Build Mustard OS Image (if not cached)
        # This 'if' condition checks the output of the caching step above
        if: steps.cache-os-image.outputs.cache-hit != 'true'
        run: |
          echo "Cache not found. Building OS image from source..."
          # Replace with your actual build command
          ./scripts/build-os.sh

      # Step 5: Run the tests inside the QEMU virtual machine
      - name: Run tests inside QEMU
        uses: etchdroid/qemu-kvm-action@v1
        with:
          # The disk image created by the build step (or restored from cache)
          disk-image: mustard_os.img

          # The script to execute *inside* the running Mustard OS VM.
          # The action automatically shares your repo files into the VM.
          run: |
            echo "✅ VM booted successfully. Running tests..."

            # Navigate to the project directory inside the VM.
            # The exact path may depend on how the OS mounts the shared directory.
            # '/github/workspace' is the default for this action.
            cd /github/workspace

            # Run the Python unit tests.
            python3 -m unittest discover

            echo "✅ Tests finished. Shutting down VM."

            # Command to gracefully shut down the VM from within.
            # This is crucial for the action to complete successfully.
            # Replace with the correct command for Mustard OS if different.
            sudo shutdown -h now