Backend Testing

Requirement A backend codebase MUST hold exactly the test suites its size requires: architecture and integration for small, adding acceptance for large.

Rationale Unit test suites are optional in both sizes. 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.

Example A backend codebase can contain:

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

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

Requirement A Domain test MUST use explicit inputs with no database, HTTP host, container, clock, or mock.

Rationale Domain tests cover factories, every lifecycle state, allowed and rejected transitions, invariants, value equality, collections, money rules, exceptions, and raised events.

Requirement An Application test MUST substitute repositories, clocks, actor accessors, and external ports, then assert the handler's coordination.

Rationale The assertion covers which aggregate was loaded, which Domain behavior ran, what was staged, and what was returned. Validator tests cover each structural rule separately.

Example For example, in the .NET stack a borrow-copy handler test substitutes the repositories with the clock, and asserts the coordination:

var handler = new BorrowCopyCommandHandler(loans, copies, clock);

var result = await handler.HandleAsync(
    new BorrowCopyCommand(copyId, readerId), CancellationToken.None);

Assert.NotEqual(Guid.Empty, result.LoanId);

The test asserts which aggregate was loaded, what was staged, and what was returned. A second test names an unavailable copy and asserts the failure/lending.copy_not_available refusal. Neither test opens a database connection, because the repositories are substitutes.

Requirement An HTTP integration test MUST run through the real application host with the real configuration, covering Problem Details, authentication, and resource authorization.

Rationale litespec/backend/persistence#test-persistence-against-postgresql covers persistence behavior against PostgreSQL. Both run on the harness that litespec/backend/testing#share-one-production-faithful-integration-harness owns.

Requirement An integration test MUST reset database state between cases through one documented strategy and depend on no test order.

Rationale Container and host fixtures may still be shared for cost, because only mutable business state must not leak.

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 database with CREATE DATABASE ... 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 cases instead records that strategy in its testing documentation.

Requirement An architecture test MUST assert the structural boundaries that litespec/backend/architecture#test-structural-boundaries names.

Rationale These are the boundaries a compiler does not enforce, so a review miss otherwise lands in the main branch.

Requirement Each Case MUST be proved by a test carrying its proves tag and calling its use case.

Rationale The tag is the claim; the model builder confirms it. The model builder confirms an acceptance scenario when its When step belongs to the use case steps class. It confirms an integration test when its body names the use case message type. You record a Case no test proves as a Known gap with owner and end date. The test asserts the result, and it asserts the Result code for a refusal.

A test carries no coverage tag. The proves tag is its only record citation. The latest test run marks each confirmed claim passing or failing.

Example An acceptance scenario for borrowing a library book carries its Case tag on the scenario method. In the library circulation product, BorrowCopyScenarios.Borrowing_an_available_copy_succeeds in apps/api/tests/Library.Acceptance.Tests/Lending/Loans/BorrowCopy/BorrowCopyScenarios.cs carries the tag for case/borrow-copy.borrowing-an-available-copy-succeeds, and its When step belongs to the BorrowCopySteps use case steps class:

/// <proves>case/borrow-copy.borrowing-an-available-copy-succeeds</proves>
public Task Borrowing_an_available_copy_succeeds() => Runner.RunScenarioAsync(
    given => new RegisterCopySteps().RegisterACopy("copy-1"),
    when => new BorrowCopySteps().BorrowACopy("reader-1", "copy-1"),
    then => new BorrowCopySteps().TheLoanIsActive());

The tag names the Case, the steps call the borrow-copy use case, and the model builder confirms the claim because the When step belongs to the use case steps class.

Requirement Each Rule MUST be proved at the point its enforcedBy names: governed Cases for validator and guard Rules, a proves tag otherwise.

Rationale A refused request proves a validator Rule. An integration test that provokes the refusal proves a store Rule. The Cases of its reacting use case prove a reaction Rule. The builder confirms an aggregate or store claim when the test body names the governed business record code type.

The validator enforces input shape as a checked-before Rule. The store enforces a persistence constraint as an always-true Rule.

Requirement A repository MUST NOT treat one coverage percentage as the definition of sufficient testing.

Rationale You collect line and branch coverage for review. Case proof, Domain negative cases, integration boundaries, security behavior, and architecture rules remain the evidence.

Requirement The integration suite MUST own one database container fixture, one application host factory, and one database isolation helper.

Rationale The fixture starts the pinned PostgreSQL once per test run. It supplies each test group its connection string before the host builds, so every test sees the same configuration. A container per test group multiplies the run time by the group count. It buys no isolation that a cloned database lacks.

"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.