Hatch Usage Guide

This document explains how to use Hatch for development and testing of the ibutsu-server backend.

Prerequisites

  • Python 3.9+ installed

  • Hatch installed (pip install hatch)

Available Environments

Default Environment

The default environment uses Python 3.9 and includes basic dependencies for development:

# Create and activate the default environment
hatch shell

# Run tests
hatch run test

# Run tests with coverage
hatch run test-cov

# Generate coverage report
hatch run cov-report

# Generate XML coverage report (for CI/codecov)
hatch run cov-xml

# Generate HTML coverage report
hatch run cov-html

# Run all coverage commands together
hatch run cov

# Run linting with pre-commit
hatch run lint

# Run linting with diff output
hatch run lint-check

Test Environment Matrix

The test environment supports multiple Python versions (3.9, 3.10, 3.11) with additional test dependencies:

# Run tests on all Python versions
hatch run test:run

# Run tests with coverage on all Python versions
hatch run test:run-cov

# Run tests on specific Python version
hatch run test.py3.9:run
hatch run test.py3.10:run
hatch run test.py3.11:run

# Generate coverage reports in test environment
hatch run test:cov-report
hatch run test:cov-xml
hatch run test:cov-html

# Run full coverage workflow
hatch run test:cov

Common Commands

Running Tests

# Run all tests (uses pytest with -n 4 for parallel execution)
hatch run test

# Run specific test file
hatch run test tests/test_health_controller.py

# Run tests with specific options
hatch run test -x -v  # Stop on first failure, verbose output

# Run tests without parallel execution
hatch run test -n 0

Development Workflow

# Enter development shell
hatch shell

# Run linting before committing (uses pre-commit)
hatch run lint

# Run tests with coverage and generate reports
hatch run test-cov
hatch run cov-report

# Or run the full coverage workflow
hatch run cov

Environment Management

# Show available environments
hatch env show

# Remove all environments (clean slate)
hatch env prune

# Create specific environment
hatch env create test.py3.9
hatch env create test.py3.10
hatch env create test.py3.11

Configuration Details

Default Environment

  • Python Version: 3.9

  • Extra Dependencies: psycopg2-binary

  • Scripts: test, test-cov, cov-report, cov-xml, cov-html, cov, lint, lint-check

Test Environment

  • Python Versions: 3.9, 3.10, 3.11 (matrix)

  • Extra Dependencies: psycopg2-binary, Flask-Testing, coverage[toml], pytest-xdist

  • Scripts: run, run-cov, cov-report, cov-xml, cov-html, cov

Test Configuration (pytest)

  • Test Paths: tests/

  • Parallel Execution: 4 workers by default (pytest-xdist)

  • Traceback Style: short

Coverage Configuration

  • Source: ibutsu_server

  • Branch Coverage: Enabled

  • Omit: tests, __pycache__, migrations

  • XML Output: coverage.xml

  • HTML Output: htmlcov/

Linting Configuration

  • Tool: pre-commit (runs Ruff and other checks)

  • Ruff Line Length: 100

  • Enabled Rules: E, W, F, I, UP, B, C4, N, S, T20, PT, RET, SIM, ARG, PTH, ERA, PL, RUF

Notes

  • The configuration automatically uses psycopg2-binary to avoid compilation issues

  • All test dependencies are automatically installed when using hatch environments

  • The existing test_env virtual environment can still be used alongside hatch

  • Hatch environments are isolated and don’t interfere with your system Python

  • Tests run with 4 parallel workers by default for faster execution

  • Pre-commit hooks are used for linting (install with pre-commit install)