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.mdplugins/pyhouse-hex/skills/hex-test-application-handler/SKILL.md
GitHubHex 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 undertests/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) orhex-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
- Where the command carries
caller_id, add a module-level_CALLER— the issuer's opaque subject, astr— and passcaller_id=_CALLERin every construction. The templates carry none: a command hascaller_idonly where its entrypoint authenticates the caller (hex-application). - AAA structure follows
test-principles. Arrange — construct fake(s) and handler. Act — callhandler.execute(...). Assert — read state back through the fake or assert raised exception. - Read state back via fake's domain methods (
await repository.get_by_id(...)), not via attribute peeking onrepository._store. - A failure case pins the exception's context (
test-principlesAssert 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. - Compensation tests assert call-record state, not implementation details. For a storage capability,
storage.uploadsandstorage.deletesare 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. - One-off failure injection is
test-principlesrung 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. - A concrete domain-service dependency is the real service built on the fakes of its ports; a module-scope subclass overriding one method (
test-principlesrung 4) only injects a failure the fakes cannot produce — never a protocol extracted for the test, a# type: ignoreor a mock. - 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
updatedcall-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 (theFakesrules below), so a body that mutates the entity but never callsupdate()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 aUUID;get_by_idreturns 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 withexc_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, andget_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-deliveryrule 1;flat-test-entrypointrule 6, in thepyhouse-flatplugin, 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 raisesFooConflictError— only where Foo has a natural key.
delete handler
test_delete_removes— happy path;get_by_idafter delete raisesNotFoundError.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_RaiseInUseFooRepositoryraises the class, message andcontextthe 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 | NonereturnsNone;Entityreturns raisesNotFoundError).
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 ofresult.itemsis exactly the expected sequence.test_pagination_offset_limit— load N > limit entities; call withlimit=L, offset=O; assertlen(result.items) == Landresult.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. Atrythat 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-principlesowns the rule; here it bites because a handler that logs the right success event and never callsupdate()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
- No inheritance from the protocol. Structural matching is verified by the type checker — no
@runtime_checkableregistration, noisinstancecheck. - 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. - Constructor takes
items: list[<Entity>] | None = Nonewithor []fallback so the empty-fake call site is terse:FakeFooRepository(). - Every method is
async def, even when there's nothing to await — the protocol says async; the fake matches. list(*, filter: <FilterRecord>)is keyword-only and applies a deterministic sort matching the real repository'sORDER 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_storeby 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.
- A fake method MUST honour every filtering / scoping parameter it declares — never ignore one. If the filter declares
- The exception contract is copied verbatim from the real adapter. Copy the class, message and
contextkeys 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) raisesFooConflictError("foo name already exists", {"field": "name", "constraint": "uq_foos_name"})— context carriesfieldandconstraintand 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-persistenceREPOSITORY.mdrule 8), the fake'screatereturns without effect when the id is already stored, checked before any natural key, as the real adapter's insert does. - 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 itsdeletedrops 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. - Default-happy-path only. No
fail_next_create=Trueflags or_should_raiseknobs, 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.
- 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 explicitupdate(), 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 callsupdate()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 viadataclasses.replace, deep only when a field is itself mutable and the test mutates through it — and keep anupdated: list[UUID]call record. - 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.
- 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. Nevermyapp.infrastructure,myapp.application,myapp.restapi. - No IO — apply
test-principlesfor isolation and determinism. - No third-party imports other than what stdlib +
myapp.domain+pytestrequire. - No state retained across instances. No class variables, no module-level caches. Each
FakeFooRepository()constructs a fresh_store. - Packaging follows
python-packagingand the fake-specific inlined import rules below.
Inlined typing / import rules
- Fakes import the standard library and
myapp.domain.*only; handler tests addpytest,myapp.application.*andtests.unit.fakes, and nevermyapp.infrastructure.*ormyapp.restapi.*. Each fake module declares__all__andtests/unit/fakes/__init__.pyre-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(orhex-test-capability-adapterfor a capability); needs the HTTP surface — it constructs the app or importsmyapp.restapi.*→ stop, usehex-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-contractorhex-test-capability-adapter.