/python-pypi-package-builder

Testing and Code Quality

Table of Contents

1. conftest.py
2. Unit tests
3. Backend unit tests
4. Running tests
5. Code quality tools
6. Pre-commit hooks

1. conftest.py

Use conftest.py to define shared fixtures. Keep fixtures focused — one fixture per concern. For async tests, use pytest-asyncio with asyncio_mode = "auto" in pyproject.toml.

# tests/conftest.py
import pytest
from your_package.core import YourClient
from your_package.backends.memory import MemoryBackend


@pytest.fixture
def memory_backend() -> MemoryBackend:
    return MemoryBackend()


@pytest.fixture
def client(memory_backend: MemoryBackend) -> YourClient:
    return YourClient(
        api_key="test-key",
        backend=memory_backend,
    )

2. Unit Tests

Test both the happy path and the edge cases (e.g. invalid inputs, error conditions).

# tests/test_core.py
import pytest
from your_package import YourClient
from your_package.exceptions import YourPackageError


def test_client_creates_with_valid_key():
    client = YourClient(api_key="sk-test")
    assert client is not None


def test_client_raises_on_empty_key():
    with pytest.raises(ValueError, match="api_key"):
        YourClient(api_key="")


def test_client_raises_on_invalid_timeout():
    with pytest.raises(ValueError, match="timeout"):
        YourClient(api_key="sk-test", timeout=-1)


@pytest.mark.asyncio
async def test_process_returns_expected_result(client: YourClient):
    result = await client.process({"input": "value"})
    assert "output" in result


@pytest.mark.asyncio
async def test_process_raises_on_invalid_input(client: YourClient):
    with pytest.raises(YourPackageError):
        await client.process({})  # empty input should fail

3. Backend Unit Tests

Test each backend independently, in isolation from the rest of the library. This makes failures easier to diagnose and ensures your abstract interface is actually implemented correctly.

# tests/test_backends.py
import pytest
from your_package.backends.memory import MemoryBackend


@pytest.mark.asyncio
async def test_set_and_get():
    backend = MemoryBackend()
    await backend.set("key1", "value1")
    result = await backend.get("key1")
    assert result == "value1"


@pytest.mark.asyncio
async def test_get_missing_key_returns_none():
    backend = MemoryBackend()
    result = await backend.get("nonexistent")
    assert result is None


@pytest.mark.asyncio
async def test_delete_removes_key():
    backend = MemoryBackend()
    await backend.set("key1", "value1")
    await backend.delete("key1")
    result = await backend.get("key1")
    assert result is None


@pytest.mark.asyncio
async def test_ttl_expires_entry():
    import asyncio
    backend = MemoryBackend()
    await backend.set("key1", "value1", ttl=1)
    await asyncio.sleep(1.1)
    result = await backend.get("key1")
    assert result is None


@pytest.mark.asyncio
async def test_different_keys_are_independent():
    backend = MemoryBackend()
    await backend.set("key1", "a")
    await backend.set("key2", "b")
    assert await backend.get("key1") == "a"
    assert await backend.get("key2") == "b"
    await backend.delete("key1")
    assert await backend.get("key2") == "b"

4. Running Tests

pip install -e ".[dev]"
pytest                           # All tests
pytest --cov --cov-report=html   # With HTML coverage report (opens in browser)
pytest -k "test_middleware"      # Filter by name
pytest -x                        # Stop on first failure
pytest -v                        # Verbose output

Coverage config in pyproject.toml enforces a minimum threshold (fail_under = 80). CI will fail if you drop below it, which catches coverage regressions automatically.

5. Code Quality Tools

Ruff (linting — replaces flake8, pylint, many others)

pip install ruff
ruff check .           # Check for issues
ruff check . --fix     # Auto-fix safe issues

Ruff is extremely fast and replaces most of the Python linting ecosystem. Configure it in pyproject.toml — see references/pyproject-toml.md for the full config.

Black (formatting)

pip install black
black .                # Format all files
black . --check        # CI mode — reports issues without modifying files

isort (import sorting)

pip install isort
isort .                # Sort imports
isort . --check-only   # CI mode

Always set profile = "black" in [tool.isort] — otherwise black and isort conflict.

mypy (static type checking)

pip install mypy
mypy your_package/   # Type-check your package source only

Common fixes:

• ignore_missing_imports = true — ignore untyped third-party deps
• from __future__ import annotations — enables PEP 563 deferred evaluation (Python 3.9 compat)
• pip install types-redis — type stubs for the redis library

Run all at once

ruff check . && black . --check && isort . --check-only && mypy your_package/

6. Pre-commit Hooks

Pre-commit runs all quality tools automatically before each commit, so issues never reach CI. Install once per clone with pre-commit install.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.4.4
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  - repo: https://github.com/psf/black
    rev: 24.4.2
    hooks:
      - id: black

  - repo: https://github.com/pycqa/isort
    rev: 5.13.2
    hooks:
      - id: isort

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.10.0
    hooks:
      - id: mypy
        additional_dependencies: [types-redis]  # Add stubs for typed dependencies

  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-toml
      - id: check-merge-conflict
      - id: debug-statements
      - id: no-commit-to-branch
        args: [--branch, master, --branch, main]

pip install pre-commit
pre-commit install           # Install once per clone
pre-commit run --all-files   # Run all hooks manually (useful before the first install)

The no-commit-to-branch hook prevents accidentally committing directly to main/master, which would bypass CI checks. Always work on a feature branch.