Backend (pytest)
================

Configuration: ``agency-django/pyproject.toml`` → ``[tool.pytest.ini_options]``.

Collection is limited to ``tests/test_*.py`` — Django management commands named ``*_test.py`` are never picked up.

Settings
--------

+---------------------------+--------------------------------------------------+
| Context                   | ``DJANGO_SETTINGS_MODULE``                       |
+===========================+==================================================+
| Local / CI pytest         | ``tests.settings`` (SQLite, in-memory Channels)  |
+---------------------------+--------------------------------------------------+
| ``./dev test`` in Docker  | ``server.settings`` (Postgres, Redis, …)         |
+---------------------------+--------------------------------------------------+

CI checks out **agency-django only** (private repos — no ``agency-server`` submodule).

Layout
------

+-----------------------------+------------------------------------------------+
| Path                        | Role                                           |
+=============================+================================================+
| ``tests/settings.py``       | Standalone Django settings                     |
| ``tests/urls.py``           | Routes ``agency.urls`` for API/WS tests        |
| ``tests/conftest.py``       | Celery eager, LLM mocks, fixtures              |
| ``tests/factories.py``      | Domain builders                                |
| ``tests/support/mocks.py``  | LangGraph / chat doubles                       |
+-----------------------------+------------------------------------------------+

Markers
-------

- ``@pytest.mark.unit`` — default fast tests
- ``@pytest.mark.integration`` — multi-component flows, mocked LLM
- ``@pytest.mark.docker`` — real stack smoke (deselected unless ``-m docker``)

Default ``addopts`` excludes ``docker`` (``-m "not docker"``).

Commands
--------

.. list-table::
   :header-rows: 1
   :widths: 28 72

   * - Command
     - Description
   * - ``cd agency-django && pytest``
     - Local SQLite suite (no Docker)
   * - ``./dev test``
     - pytest inside ``agency_django`` container
   * - ``./dev test -m integration -v``
     - Runtime / HITL / Celery (mocked LLM)
   * - ``./dev test-docker``
     - ``AGENCY_DOCKER_TESTS=1`` — hits localhost nginx/Redis/Postgres

Coverage
--------

``pytest --cov=agency`` with ``fail_under = 35`` in ``pyproject.toml``.

GitHub Actions (~36% on ubuntu-latest; ~44% in Docker dev stack). Target **40%**.

Workflow: ``agency-django/.github/workflows/tests.yml`` — see :doc:`ci`.