Backend Testing

Each suite owns one boundary and one harness, so a project that keeps exactly its suites knows where each new test belongs. A missing suite pushes its tests into another suite's harness, where they run with the wrong fixtures, and an extra unnamed suite collects the tests nobody placed. Unit suites stay optional in both sizes, and acceptance stays optional for small. An acceptance suite without the executable BDD extension is an unnamed baseline suite: select the extension, or name the suite for what it actually is.

A backend codebase holds these suite folders:

architecture-tests/
integration-tests/
acceptance-tests/

A small codebase holds the first two. Acceptance appears when the executable BDD extension activates.

Reviewed forWhich test folders miss a required suite, or hold an extra unnamed one? Look at the test folders beside the declared project size.

Marked guidance: a reviewer answers this question.

Domain behavior is deterministic: explicit inputs in, new state or a refusal out. A database, host, container, clock, or mock in a Domain test hides nondeterminism behind the call, so the same test passes and fails without a code change. The suite covers factories, every lifecycle state, allowed and rejected transitions, invariants, value equality, collections, money rules, exceptions, and raised events.

Reviewed forWhich Domain tests take more than explicit inputs? Look at the Domain test files for database, host, container, clock, or mock use.

Marked guidance: a reviewer answers this question.

A handler's job is coordination: load the right aggregates, call Domain behavior, stage the result. Substitutes for repositories, clocks, actor accessors, and ports isolate that coordination, so a failure names the handler rather than the database or the provider. The assertion covers which aggregate was loaded, which Domain behavior ran, what was staged, and what was returned, and validator tests cover each structural rule separately.

A handler test for submitting an expense substitutes the expense and policy repositories, sends a command carrying an expense identifier, an employee identifier, an amount, and a receipt, and asserts the returned expense identifier alongside what was loaded and staged. A second test sends an expense above the threshold with no receipt and asserts the spending.receipt-missing refusal. Both tests run with no database connection, because the repositories are substitutes.

Reviewed forWhich Application tests skip a substitute, or miss a coordination assertion? Look at each Application test file.

Marked guidance: a reviewer answers this question.

Only the real host wires the real routing, serialization, authentication, and authorization. A test that bypasses the host proves the handler again and misses the boundary where status codes, Problem Details shapes, and policy denials are actually produced. Persistence behavior is covered against PostgreSQL under litespec/backend/persistence#test-persistence-against-postgresql, and both run on the harness that litespec/backend/testing#share-one-production-faithful-integration-harness owns.

Reviewed forWhich HTTP integration tests bypass the real host factory or production configuration, or skip Problem Details, authentication, or authorization? Look at the HTTP integration tests.

Marked guidance: a reviewer answers this question.

When two tests share mutable business state, each passes or fails depending on which ran first, and the failure disappears when one test runs alone. One documented reset strategy removes that coupling. Container and host fixtures stay shared for cost, because only mutable business state leaks between tests.

The default strategy is one database per test class, cloned from a migrated template. The harness applies the schema once per run to a template database. Each test class then receives its own database cloned from that template and drops that database when the class finishes. A clone takes milliseconds, so every class starts from an empty migrated schema without a second container. A project that resets tables between tests instead records that strategy in its testing documentation.

Reviewed forWhich integration tests share mutable business state across runs, or which reset strategies stay undocumented? Look at the tests beside the testing documentation.

Marked guidance: a reviewer answers this question.

A scenario states one behavior the product shows, and the proves mark is the test's claim that it shows it. A test that drives the use case through its steps, its message, or its endpoint exercises the public boundary; a test that constructs a handler, an aggregate, or a repository reaches past it and proves nothing. The assertion names the result: the success fields for a success, the refusal code inside an assertion for a refusal. A reaction or job scenario is proved the same way: its test fires the trigger and asserts the result of the use case the reaction or job runs. A scenario no test proves is recorded as a gap exception with owner and expiry date. The latest test run marks each confirmed claim passing or failing.

An acceptance scenario for submitting an expense carries the mark for scenario/submit-expense.submitting-with-a-receipt-succeeds, drives the submit-expense steps, and asserts the submitted expense. An integration test for the same scenario constructs the submit-expense message, sends it through the host, and asserts the same result. The mark names the scenario, the call crosses the public boundary, and the model builder confirms the claim from the test body.

Reviewed forWhich scenarios lack a proving test with its mark, boundary call, and passing run? Look at the book beside the test bodies.

Marked guidance: a reviewer answers this question.

Each rule holds where its kind says: an invariant inside the aggregate, a precondition at the guard, a calculation in its pure evaluation, a cross-aggregate rule at the store or the reacting use case. A scenario that walks through that point exercises the rule, so the rule claim rides on the scenario proof instead of carrying its own enforcement-point mark. A calculation rule earns its proof from a scenario carrying the examples table that litespec/core/domain-model#tabulate-every-calculation-with-examples requires.

A test proving the scenario for an expense above the threshold with no receipt claims the receipt rule alongside the scenario. The scenario sends the command and asserts the spending.receipt-missing refusal, and the rule claim confirms because the same test proves the scenario. No separate mark names the validator or the store.

Reviewed forWhich rule claims stand without a proved scenario claim on the same test? Look at each rule claim.

Marked guidance: a reviewer answers this question.

A result file names each test with its namespace, its containing types joined with dots, and its method, without data-row arguments. A renamed test then matches nothing instead of matching another test's same-named method, so the rename fails loudly instead of lingering as an awaited run. Short-name matching hides the rename behind a passing name it no longer owns.

Renaming a submit-expense test leaves the old qualified name with no matching result, and the scenario shows unproven until the new name runs and passes.

Reviewed forWhich test results match outside fully qualified names, or carry data-row arguments? Look at the test result files.

Marked guidance: a reviewer answers this question.

Expected values read from the code under test restate what the code does, so the test passes with the code whatever the specification says. The scenario's Then holds the expected ending, and the test asserts exactly that ending. The agent obligation behind this rule lives in litespec/core/agent#take-expected-values-from-the-scenario, with held-back example rows checked after implementation under litespec/core/agent#verify-refusals-and-calculations-against-held-back-examples.

A scenario whose Then says the expense is submitted asserts the submitted state and the returned identifier from the scenario text. The test author reads no handler code to learn the expected values.

Reviewed forWhich test assertions repeat values outside the Then of their scenarios? Look at each assertion beside its scenario text.

Marked guidance: a reviewer answers this question.

A single coverage percentage rewards tests that execute lines without asserting behavior: a suite reaches the target while proving no scenario. Coverage stays useful as review input, so the project collects line and branch numbers without treating any value as sufficient. The evidence is scenario proof, domain edge cases, integration boundaries, security behavior, and architecture rules, with mutation results on changed lines under litespec/backend/testing#refuse-surviving-mutants-on-changed-lines.

Reviewed forWhich build gates name a coverage percentage as sufficient? Look at the build gates beside the coverage numbers.

Marked guidance: a reviewer answers this question.

One fixture, one host factory, and one reset helper give every integration test the same database and configuration. A container per test group multiplies the run time by the group count, and it buys no isolation that a cloned database lacks. The fixture starts the pinned PostgreSQL once per test run, and it supplies each test group its connection string before the host builds.

One harness binds the integration suite. An activated BDD extension brings its own host for the acceptance suite, because the two suites run different lifetimes. That second host reuses this fixture's container and reset helper rather than starting another database.

Reviewed forWhich integration suites miss the one container fixture, host factory, or isolation helper, or hold a second of one? Look at the integration suite.

Marked guidance: a reviewer answers this question.