Skip to content

rlaope/oh-my-hermes / .claude/agent-skills/omh-backend

omh-backend

Verified

[omh] Designing an API, server, or data-layer change.

references/contract-tests.md

View on GitHub
# Backend Contract Tests

Load this when a backend handoff asks for tests. The contract tables say what the surface promises; this page ties each promise to the test that proves it, so the test plan in `backend_implementation_handoff/v1` is derived from the rows rather than improvised after the code exists.

The shapes every test must have -- the seam named first, the questions before a new test, tests that guard nothing, tests coupled to internals, and fakes only at system boundaries -- live in one shared page: read `../../omh-verification-gate/references/test-authoring.md`. This page does not repeat them.

OMH writes no test and runs none. The plan is prepared; only an executor's observed run is evidence.

## 1. One test per contract row

| Contract row | The test | Seam |
| --- | --- | --- |
| each `auth_boundary_map/v1` row | a negative test: the caller that lacks the identity or the permission is refused with the status the row names | the HTTP or job interface |
| the object-level authorization row | always written as "caller A requests B's id", asserting the not-found or not-permitted status the error table chose | the HTTP interface |
| each `error_path_table/v1` row | status, machine code, and envelope shape asserted together, plus the retry hint on a retryable row | the HTTP interface |
| an idempotency key | the same request sent twice with one key produces one effect, read back through the interface | the HTTP interface |

A status-only assertion lets the envelope drift unseen, and a happy-path test alone proves none of the rows above. A row with no test is listed in the plan as untested with the reason, not left out.

## 2. Logic through its module interface

Logic behind a handler is tested through the interface of the module that owns it, not through private helpers and not only through HTTP. Handler tests then cover parsing, the auth check, and the mapping of results and errors to the envelope.

## 3. Stand-ins by dependency category

Pick every stand-in from the dependency table in section 5 of the shared page. What a backend adds to it:

- The database runs at the version production runs wherever behaviour differs between versions. A managed-only store or a host with no container runtime falls back to the vendor's emulator, with what the emulator does not model named in the plan.
- A third-party API (payments, email, identity) is faked below the service's own client wrapper, at the transport or vendor client the wrapper is given, and the fake records what was sent; the wrapper's parsing, retry, and error mapping run real, and no test reaches the real vendor.

A repository class replaced by a mock, or an assertion that `save` was called, is a test coupled to internals: the shared page says how to rewrite it.

## 4. Writes are read back through the interface

Check a write by reading it back the way a caller would -- the read endpoint, or the module's read function -- not by querying the table. A table read passes while the read path is broken and fails when the storage layout changes without any behaviour change. The exception is a table another consumer reads directly -- change-data capture, an outbox relay, a reporting job: there the stored shape is itself a contract, and a test asserts it alongside the read-back.

## 5. Migrations run on populated data

A migration test applies the migration to a database that already holds rows in the previous shape, including the null, empty, and boundary values the old shape allowed, never only to an empty schema. It asserts that the migration completes, that backfilled values are right, that code still running against the previous shape keeps working through expand, backfill, and switch until the contract step, and that each step's rollback point (`references/schema-migration.md`) restores a readable state.

## 6. What the plan records

Per test: the contract row it proves, the seam, the stand-ins, and the command the executor runs. A planned test is `prepared_not_observed`; passing tests, applied migrations, and integration runs are recorded only from observed executor output.

## Attribution

One test per contract row, reading writes back through the interface, and stand-ins chosen by dependency category adapt ideas from Matt Pocock's `tdd` and `codebase-design` skills at `mattpocock/skills@49dd158d1076134a641b33efb035946536778336`, MIT License, Copyright 2026 Matt Pocock. No upstream text is reproduced; the contract-row mapping and the `prepared_not_observed` boundary are OMH's own.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall