testing

Testing Rules

Test Organization

• Test directories should mirror the source code structure.

• If the source has core/, models/, routes/, or services/, keep the corresponding unit/ and integration/ folders aligned with those boundaries.

• Place tests next to the source subdomain they verify, not in a loosely related folder.

• Name a test module for the single source file it covers, prefixed with test_. Drop generated revision or timestamp prefixes from migration test names and retain the descriptive remainder. Name tests that span a subsystem for that subsystem.

• Proto conversion round-trip tests are unit tests. Keep tests of the serialization layer itself in a dedicated proto/ test folder; gateway, runtime, and servicer tests that merely consume proto messages stay beside their owning source subdomain.

• Use pytest async tests (async def test_...).

• Group tests in classes named TestXxx.

• Use fixtures for setup (defined in conftest.py or fixture modules).

• Register custom pytest markers in pyproject.toml under [tool.pytest.ini_options].markers instead of adding them dynamically in pytest_configure(...) inside conftest.py.

• Add a single-line docstring to every test class and test function.

• Test docstrings must start with Test that ... (example: """Test that when no credentials are provided an exception is raised""").

• Do not include numeric HTTP status codes in test function names; use semantic status names instead (for example, bad_request, not_found, forbidden).

• Keep ALL imports at the top of test files.

• Never import inside test functions or methods.

Fixtures and Test Data

• Use clearly synthetic data that is unique to each test or parametrized case unless an exact protocol or catalog literal is the contract under test; never paste exact user-provided examples into tests, and preserve only the shape or edge case being verified when inventing replacements.
• Define test helper functions at module level.
• Keep helper docstrings to a single line.
• Use Polyfactory for structured Pydantic and SQLAlchemy test data. Define concrete ModelFactory or SQLAlchemyFactory classes in the nearest shared factories.py, set __model__, provide deterministic domain defaults, and call .build(**overrides) directly from tests.
• Let Polyfactory generate incidental valid values. Express domain constraints and cross-field relationships without replacing its generation with a large manual build() implementation.
• Do not wrap Polyfactory classes in callable pytest fixtures solely for dependency injection, and do not use Protocol to describe them.
• Use pytest factory fixtures for setup or construction that Polyfactory does not cover, including persisted flows, filesystem materialization, dependency lifecycles, and multi-object scenarios. Put reusable pytest builders in the nearest shared conftest.py, not in test modules.
• Keep pytest factory names domain-focused. Name ORM persistence fixtures for their action, such as create_order or create_customer; never use an *_orm_factory suffix or encode persistence mechanics in the name.
• Use explicit shared materialization helpers for filesystem and other I/O artifacts; accept typed factory-built models and explicit target paths.
• Module-level helpers are allowed only for trivial, non-construction utilities scoped to one file (predicates, small formatters, to_comparable_string-style assertion adapters). When in doubt, move it to conftest.py.