flowCreate.solutions

Testing Structure

This document details the folder structure and organization of tests.

Mirror Pattern

Tests are organized to mirror the application structure. If a module exists in database/{module}/, a corresponding test folder should exist in tests/{module}/.

tests/
├── conftest.py                 # Shared fixtures + wiring (async client, db session, auth helpers)
├── docs/                       # Templates/guidance for module test documentation
│   ├── readme.md
│   └── template.md
├── companies/                  # Example module suite
│   ├── readme.md               # Module test documentation (based on tests/docs/template.md)
│   ├── fixtures.py             # Module fixtures only
│   ├── test_companies_data.py  # Canonical payloads/builders/constants for this module
│   ├── test_<feature>_<scenario>.py
│   └── ...
├── users/
│   ├── readme.md
│   ├── fixtures.py
│   ├── test_users_data.py
│   └── ...
└── [other modules]/

File Naming

  • Test Files: test_<feature>_<scenario>.py (feature/scenario focused) or test_<module>.py while suites are small.
  • Test Functions: test_* (e.g., test_create_entity, test_get_entity)
  • Fixtures: fixtures.py (module-specific fixtures only; compose shared fixtures from tests/conftest.py)
  • Data Helpers: test_<module>_data.py for canonical payloads/builders/constants (named to avoid pytest discovery conflicts and to be easy to import cross-module).

Conftest Hierarchy

  • Root tests/conftest.py: Defines global fixtures like client (ASGI-bound httpx.AsyncClient), db_session (async DB session), and auth_headers (authenticated request headers).
  • Module fixtures: Prefer tests/{module}/fixtures.py for module-only factories/fixtures. Use tests/{module}/conftest.py only when a sub-suite needs local fixture wiring.

Documentation requirement (per-module readme.md)

The reference backend keeps a readme.md inside each tests/{module}/ directory, using tests/docs/template.md as the starting point. This ensures test intent, fixtures, and critical assertions stay discoverable as suites grow.