hex-test-application-handler

Use when unit-testing a CQRS command or query handler against in-memory fakes, or when writing one of those fakes — this skill owns `tests/unit/fakes/`, so a request for a fake repository or a fake `I

SKILL.md

GitHub

Hex Test — Application Handler (unit)

Consult test-principles for the testing constitution. Where this skill contradicts test-principles, the constitution wins.

Produces one unit-test file per handler module. Runs in milliseconds against in-memory fakes. Coverage targets the happy path plus every domain exception the handler propagates and — for compensating-transaction handlers — the post-failure undo, and, where a side effect follows the store write, a failed effect that leaves the command succeeded.

When to use vs. neighbours

  • A new or modified handler under application/<subdomain>/, or a fake it needs under tests/unit/fakes/ → this skill (write the fake first).
  • A fake for a capability port (ICan<Verb>) as much as for a repository (IFooRepository) → this skill; it owns both, which is why a bare "write me a fake" lands here and not on an adapter-test skill.
  • One-off failure injection for a single handler test → this skill — declare a _RaiseXxxRepository(FakeFooRepository) subclass at the handler test module scope instead of extending the fake.
  • A test that drives the handler through the HTTP surface → hex-test-restapi-endpoint (integration, not unit); as an authenticated caller → hex-test-restapi-auth.
  • A test for a domain entity, value object, enum or service → hex-test-domain.
  • A real-backend test of the repository the fake stands in for → hex-test-repository-contract; of a capability adapter → hex-test-capability-adapter. The fake's exception contract is copied verbatim from whichever of those pins it.
  • The real adapter itself → hex-persistence (relational), hex-store-repository (client store) or hex-capability-adapter.
  • The domain protocol the fake matches → hex-domain-ports; the handler under test → hex-application.
  • Any container, engine or session fixture — this layer has none and needs none → hex-test-integration-setup.
  • The substitution ladder that permits a fake at all, and the no-mocks rule → test-principles.

Template(s) — pytest, hand-written in-memory fakes

Handler unit-test file location

tests/unit/application/
└── test_<verb>_<noun>_handler.py        # mirrors the handler module's filename

One file per handler. Compensating-transaction assertions live in the file for the handler that performs the compensation, not in a separate file.

create handler

import pytest  # only where Foo has a natural key

from myapp.application.foos import CreateFooCommand, CreateFooHandler
from myapp.domain.exceptions import FooConflictError  # only where Foo has a natural key
from tests.unit.fakes import FakeFooRepository


async def test_assigns_uuid_and_stores() -> None:
    repository = FakeFooRepository()
    handler = CreateFooHandler(repository=repository)

    foo_id = await handler.execute(CreateFooCommand(name="alpha"))

    stored = await repository.get_by_id(foo_id)
    assert stored.name == "alpha"
    assert stored.id == foo_id


# only where Foo has a natural key
async def test_duplicate_name_raises_conflict() -> None:
    repository = FakeFooRepository()
    handler = CreateFooHandler(repository=repository)
    await handler.execute(CreateFooCommand(name="alpha"))

    with pytest.raises(FooConflictError) as exc_info:
        await handler.execute(CreateFooCommand(name="alpha"))

    assert exc_info.value.context["constraint"] == "uq_foos_name"  # only with a relational adapter

update handler — partial update, an absent field left as it was

import uuid

import pytest

from myapp.application.foos import UpdateFooCommand, UpdateFooHandler
from myapp.domain.exceptions import NotFoundError
from myapp.domain.foos import Foo
from tests.unit.fakes import FakeFooRepository


async def test_partial_update_leaves_unspecified_fields_untouched() -> None:
    foo_id = uuid.uuid4()
    repository = FakeFooRepository(items=[Foo(id=foo_id, name="alpha", note="kept")])

    await UpdateFooHandler(repository=repository).execute(UpdateFooCommand(id=foo_id, name="beta"))

    stored = await repository.get_by_id(foo_id)
    assert stored.name == "beta"
    assert stored.note == "kept"  # not given on the command, so left as it was
    assert repository.updated == [foo_id]


async def test_update_unknown_id_raises_not_found() -> None:
    handler = UpdateFooHandler(repository=FakeFooRepository())
    missing = uuid.uuid4()

    with pytest.raises(NotFoundError) as exc_info:
        await handler.execute(UpdateFooCommand(id=missing, name="beta"))

    assert exc_info.value.context["id"] == str(missing)

One-off failure injection

Only where another aggregate references Foo without a cascade, the delete handler's in-use case is driven by a module-scope _RaiseInUseFooRepository(FakeFooRepository) overriding delete alone (rule 6) and raising the class, message and context the real adapter's delete raises for that reference — a relational adapter's includes the FK constraint name (Fakes rule 6); the test asserts it propagates unchanged.

list query handler — sort + pagination

import uuid

from myapp.application.foos import ListFoosHandler, ListFoosQuery
from myapp.domain.foos import Foo, FooListFilter, FooSort
from tests.unit.fakes import FakeFooRepository


async def test_sorted_by_name() -> None:
    repository = FakeFooRepository(
        items=[
            Foo(id=uuid.uuid4(), name="b"),
            Foo(id=uuid.uuid4(), name="c"),
            Foo(id=uuid.uuid4(), name="a"),
        ]
    )
    handler = ListFoosHandler(repository=repository)

    result = await handler.execute(
        ListFoosQuery(filter=FooListFilter(sort=FooSort.NAME_ASC, limit=2)),
    )

    assert [foo.name for foo in result.items] == ["a", "b"]
    assert result.total == 3

Seed 3, page 2 — the page size is smaller than the seeded set on purpose. At limit=10 over three rows the page holds every match, so the same asserts pass a handler that never applies the bound and one that returns len(items) as total. 3 and 2 are the smallest pair that reds both. Each field the filter narrows by gets one more test that seeds a row the filter excludes and asserts it is absent from both items and total — which is also what proves the fake honours the filter (Fakes rule 5).

compensating-transaction handler

Where a handler undoes an external write when a later step fails (hex-application, Compensation), its tests live in that handler's file and drive it over the external write's call record. The template — two tests, the undo and a failed undo — sits beside the storage fake in FAKES.md.

Fake repository and capability templates

Produces one in-memory stand-in class for a domain protocol. Handler unit tests under tests/unit/application/ use this fake instead of the real infrastructure/ adapter. The fake satisfies the protocol structurally — no (IFooRepository) inheritance, no @runtime_checkable registration.

File location and naming

tests/unit/fakes/
├── __init__.py                                 # re-exports every fake (python-packaging)
└── fake_<aggregate_snake>_repository.py        # class FakeFooRepository

For capabilities the fake takes the name the real adapter takes after its technology prefix (hex-conventions): the capability's role noun when it has one — FakeFooStorage for ICanStoreFoos — and otherwise the protocol name minus ICan. The module is the class name snaked: fake_foo_storage.py.

tests/unit/fakes/ is a package like any other: each fake module declares __all__, the package __init__.py re-exports them under python-packaging's contract, and handler tests import from the package:

from tests.unit.fakes import FakeFooRepository

Living under tests/ is what keeps fakes out of production import graphs; the re-export only spares each test from knowing the file layout. tests.unit.fakes resolves against the distribution's own root — in a single distribution, through python-toolchain's [tool.pytest.ini_options] block; in a workspace, python-workspace.

Read FAKES.md in this skill's directory before writing or extending a fake under tests/unit/fakes/ — the CRUD repository fake and the test that pins its copy contract; its storage and compensation sections only where a handler compensates (hex-application, Compensation). Only SKILL.md is loaded automatically.

Rules

Consult test-principles for the testing constitution, naming for names, python-style for typing and comments, python-logging for logging, python-packaging for packaging and imports, and exception-catalog for the error catalogue and boundary translation.

Handler tests

  1. Where the command carries caller_id, add a module-level _CALLER — the issuer's opaque subject, a str — and pass caller_id=_CALLER in every construction. The templates carry none: a command has caller_id only where its entrypoint authenticates the caller (hex-application).
  2. AAA structure follows test-principles. Arrange — construct fake(s) and handler. Act — call handler.execute(...). Assert — read state back through the fake or assert raised exception.
  3. Read state back via fake's domain methods (await repository.get_by_id(...)), not via attribute peeking on repository._store.
  4. A failure case pins the exception's context (test-principles Assert strength recipe 6); the fake carries the real adapter's (Fakes rule 6), so asserting the class alone passes a fake with the wrong payload.
  5. Compensation tests assert call-record state, not implementation details. For a storage capability, storage.uploads and storage.deletes are the observation surface. Assert the right key was undone, in the right order, for the right reason — but never assert that a specific Python call site invoked them.
  6. One-off failure injection is test-principles rung 4 with the fake as its base — an inline _RaiseXxxRepository(FakeFooRepository) at module scope overriding exactly the method under test, never re-stubbing the whole protocol.
  7. A concrete domain-service dependency is the real service built on the fakes of its ports; a module-scope subclass overriding one method (test-principles rung 4) only injects a failure the fakes cannot produce — never a protocol extracted for the test, a # type: ignore or a mock.
  8. A handler test's stand-in is a fake from tests/unit/fakes/; where the one it needs does not exist, write it there first. Never improvise a stand-in at the test site, reach for a mock, or weaken the assertion so it is not needed — the fake's value is that its exception contract matches the real adapter's, and an improvised stub silently does not.

Assert strength on a handler over fakes

The recipes that hold for any test — assert a survivor rather than an empty result, seed a second row where one cannot prove scoping, pick a non-constant input for an echoed field, assert no side effect on a reject path, exercise a non-boundary case as well as the boundary, and expect the narrowest class on a raise path — are test-principles'. One is specific to a handler driven through in-memory fakes:

  • Pin PERSISTED state, not the in-memory entity. Assert the write happened via the fake's updated call-record (assert repository.updated == [id]) AND read the value back ((await repository.get_by_id(id)).name == "beta"). The fake returns a COPY and records updates (the Fakes rules below), so a body that mutates the entity but never calls update() reds. Asserting on the entity object the handler mutated in place pins nothing (it observes the in-memory mutation, not the persist).

Coverage checklist (one test_* per case — test-principles owns when not to parametrize)

create handler

  • test_assigns_uuid_and_stores — handler returns a UUID; get_by_id returns the entity with expected fields and that same id.
  • test_duplicate_<unique_field>_raises_conflict — for every uniqueness constraint enforced by the repository, assert the repository's conflict class (FooConflictError) on the second attempt with exc_info.value.context["constraint"] == "<full_constraint_name>" where the adapter is relational.
  • Field normalization (when applicable): assert the stored entity has the normalized form (strip, upper), not the raw input.

create handler a delivered unit drives

Only where a consumer or another inbound adapter calls the handler with a unit delivered at least once (at-least-once-delivery, rule 3; hex-architecture's consumer line) — there the command carries the id (hex-application command handler rule 6), so test_assigns_uuid_and_stores becomes test_stores_under_the_commands_id, asserting the returned and stored id equal the command's:

  • test_a_redelivered_create_changes_nothing — handle the same command, carrying the unit's id, twice; assert both calls return the unit's id, the second raises nothing, and get_by_id(<the unit's id>) returns the entity the first wrote. The fake resolves a conflict on its own id as the real adapter does (Fakes rule 6), so a fake that raises there, or a handler that mints its own id, reds.
  • The inbound adapter's own obligation — the unit acknowledged once the handler returns, returned unacknowledged when it raises — is tested where the project tests that adapter, through the adapter's function that handles one unit, never here (at-least-once-delivery rule 1; flat-test-entrypoint rule 6, in the pyhouse-flat plugin, is an example).

update handler

  • test_partial_update_leaves_unspecified_fields_untouched — set one field and leave another out; assert the one left out is unchanged and the one set is updated. This is the partial-update contract.
  • test_update_unknown_id_raises_not_found.
  • test_update_duplicate_<unique_field>_raises_conflict — renaming row B to row A's name raises FooConflictError — only where Foo has a natural key.

delete handler

  • test_delete_removes — happy path; get_by_id after delete raises NotFoundError.
  • test_delete_unknown_id_raises_not_found.
  • test_delete_<resource>_in_use_propagates — only where another aggregate references this one without a cascade. An inline _RaiseInUseFooRepository raises the class, message and context the real adapter's delete raises for that reference (a relational adapter's includes the FK constraint name); assert it propagates unchanged.

get / single-read query handler

  • test_returns_entity_when_present — load the fake with one entity; the handler returns it intact.
  • test_returns_none_or_raises_when_absent — match the handler's contract (Entity | None returns None; Entity returns raises NotFoundError).

list query handler

  • test_sorted_by_<order_key> — load the fake with deliberately unsorted entities (vary both primary and secondary sort keys); assert the order of result.items is exactly the expected sequence.
  • test_pagination_offset_limit — load N > limit entities; call with limit=L, offset=O; assert len(result.items) == L and result.total == N.

compensating-transaction handler

  • test_store_failure_undoes_the_<external_write> — the store write raises the catalogue exception its real adapter raises; assert the external write's call record shows each write that landed before the failure undone, and the caller receives that same failure.
  • test_failed_undo_still_raises_the_original_failure — the undo raises too; assert the original failure propagates, not the undo's, and the undo was still attempted. Both injected failures are catalogue classes (Fakes rules 6 and 8), so the test tells them apart by which call raised, never by class alone.

handler with a side effect after the store write

  • test_<effect>_failure_leaves_the_<command>_succeeded — only where the handler runs a side effect after the store write (hex-application, After the store write): an inline subclass, at module scope, of the fake the call after the write reaches — the effect's own, or the hand-off's where the effect is handed to something that retries it — raises the catalogue exception its real adapter raises; assert the handler returns normally (the id, for a create), the write reads back from the repository fake, and the call was attempted, on that fake's call record. The one log line the handler owes is not asserted (Hard prohibitions).
  • test_store_failure_skips_the_<effect> — same condition: the repository fake's write raises the catalogue exception its real adapter raises; assert that very failure propagates and the effect's call record is empty. A try that also covers the write, or an effect sent before it, reds here.

Hard prohibitions (across all handler-unit tests)

  • No assertions on what the handler logged — test-principles owns the rule; here it bites because a handler that logs the right success event and never calls update() would otherwise pass. Assert the returned value and the persisted state. Which layer may log at all → hex-architecture.
  • Timing and unit-test isolation follow test-principles. The whole file should run in well under a second.

Fakes

  1. No inheritance from the protocol. Structural matching is verified by the type checker — no @runtime_checkable registration, no isinstance check.
  2. One state field per collection — self._store: dict[UUID, <Entity>] keyed by id. No secondary indexes, no shadow caches. Queries scan the dict — the data set is tiny.
  3. Constructor takes items: list[<Entity>] | None = None with or [] fallback so the empty-fake call site is terse: FakeFooRepository().
  4. Every method is async def, even when there's nothing to await — the protocol says async; the fake matches.
  5. list(*, filter: <FilterRecord>) is keyword-only and applies a deterministic sort matching the real repository's ORDER BY. Handler tests assert exact order — sort, don't return insertion order.
    • A fake method MUST honour every filtering / scoping parameter it declares — never ignore one. If the filter declares name, a status set or a parent id, the fake filters _store by it. A fake that accepts a parameter and ignores it makes that contract uncatchable — the assert for it can never be strong. The fake's filtering need not be efficient, just correct: a wrong body that ignores the same parameter must produce a different result against the fake.
  6. The exception contract is copied verbatim from the real adapter. Copy the class, message and context keys the real adapter sets — for a relational adapter that includes the constraint name — and no more. Where the aggregate has a natural key, the relational adapter (hex-persistence) raises FooConflictError("foo name already exists", {"field": "name", "constraint": "uq_foos_name"}) — context carries field and constraint and nothing else, so the fake matches it exactly. Adding a key the real adapter never sets (e.g. "value") is the silent drift this rule exists to prevent: a handler test asserting that key passes against the fake and fails against the real adapter. Where a create a delivered unit drives resolves a conflict on its own id as nothing to do (hex-persistence REPOSITORY.md rule 8), the fake's create returns without effect when the id is already stored, checked before any natural key, as the real adapter's insert does.
  7. Cascades match the schema. When the real schema has ON DELETE CASCADE, the fake removes the dependent rows: it holds the owned children in a second dict keyed by id, and its delete drops every child whose parent id matches before dropping the parent. Skipping the cascade in the fake produces a green unit test that a failing integration test then catches — defeats the point.
  8. Default-happy-path only. No fail_next_create=True flags or _should_raise knobs, and no failure the default fake cannot know about — an in-use rejection needs a cross-aggregate reference the in-memory fake does not model. A one-off failure is an inline subclass at the handler test's module scope (handler rule 6):
class _RaiseUpstreamFooRepository(FakeFooRepository):
    async def create(self, foo: Foo) -> None:
        raise UpstreamError("the datastore could not complete the operation", {"id": str(foo.id)})

Call records — updated, a capability fake's call list, a storage fake's uploads / deletes — observe; they never inject failure.

  1. Never hand back the object the caller passed in — copy on write and on read, and record every update(). The real repository round-trips through the database: a mutation is persisted only by an explicit update(), and a later read returns the persisted row, not the caller's object. A fake that stores and returns the same instance aliases it, so a handler that mutates the entity in place and never calls update() still sees its change on the next read — the mutate-but-never-persist bug passes green and no persistence assertion can pin it. So copy on write (self._store[id] = replace(foo)) and on read (return replace(self._store[id])) — a shallow copy via dataclasses.replace, deep only when a field is itself mutable and the test mutates through it — and keep an updated: list[UUID] call record.
  2. A handler that takes a unit of work is tested with a fake unit of work that hands out the fake repositories and records whether it committed. Writes made through it are visible outside the unit of work only on commit — inside it, reads see its own writes, as the real session does — and leaving the block without a commit discards them. The test asserts that the writes read back from outside the unit of work only once it has committed, and that an exception raised inside the block leaves nothing committed — a fake whose repositories write straight through passes a handler that never commits, or commits half its writes before failing.
  3. The fake declares exactly the methods its port declares; a narrower port gets a narrower fake, and the list, count and conflict branches go with the methods that need them.

What a fake must not do

  • No production imports beyond myapp.domain. Fakes import domain entities, value objects, enums, and exceptions. Never myapp.infrastructure, myapp.application, myapp.restapi.
  • No IO — apply test-principles for isolation and determinism.
  • No third-party imports other than what stdlib + myapp.domain + pytest require.
  • No state retained across instances. No class variables, no module-level caches. Each FakeFooRepository() constructs a fresh _store.
  • Packaging follows python-packaging and the fake-specific inlined import rules below.

Inlined typing / import rules

  • Fakes import the standard library and myapp.domain.* only; handler tests add pytest, myapp.application.* and tests.unit.fakes, and never myapp.infrastructure.* or myapp.restapi.*. Each fake module declares __all__ and tests/unit/fakes/__init__.py re-exports it (python-packaging); tests import from the package.
  • X | None, full annotations on every fake method, builder and inline subclass.
  • No from __future__ import annotations.

Hard stops

  • A handler test needs a real database → stop, use hex-test-repository-contract (or hex-test-capability-adapter for a capability); needs the HTTP surface — it constructs the app or imports myapp.restapi.* → stop, use hex-test-restapi-endpoint.
  • The real adapter's exception contract cannot be located → stop, the fake's contract is copied, not invented; pin it first with hex-test-repository-contract or hex-test-capability-adapter.