Python Testing Strategy #

This doc outlines how we test our Python libraries and apps.

• Unit tests: fast, pure Python tests for code that doesn’t need middleware.
• Integration tests: run real middleware (RabbitMQ, Redis, S3, Postgres) using Docker containers.

Test Directory Structure #

Tests are organized to mirror the source code structure:

• Each package has a test/ folder at the same level as src/
• Test files mirror the directory structure of src/
• Test files are prefixed with test_

Example Structure #

libs/python/bonsai-hinoki/hinoki/
├── src/
│   └── hinoki/
│       ├── llm/
│       │   ├── __init__.py
│       │   └── llm_client.py
│       └── utils/
│           └── image.py
└── test/
    └── hinoki/
        ├── llm/
        │   ├── __init__.py
        │   └── test_llm_client.py
        └── utils/
            └── test_image.py

Naming Convention #

• Source file: src/hinoki/llm/llm_client.py
• Test file: test/hinoki/llm/test_llm_client.py

What goes where #

• Unit tests (test/**/test_*.py)

  • Pure logic, helpers, formatters, parsers, validators, etc.
  • No network, no containers.
  • Fast and deterministic.

• Integration tests (test/**/test_*_integration.py)

  • Exercise public APIs that talk to middleware (database, cache, message queue, S3, etc.)
  • Use Docker containers for real services.
  • Suffix with _integration.py to distinguish from unit tests.