The team has written its first order test. Later sprints add refusals, review outcomes, retries, registration, and concurrent requests. The suite must stay readable and isolated while continuing to verify earlier obligations.
About the examples: Meridian Ordering is a private training reference project. The inline listings illustrate the techniques; the full C# and Python repositories are not currently public.
Daily organization affects that trust. A developer should be able to find a feature, identify a scenario, see its defining arrangement, locate Act, and read which actual results are compared. A failed CI run should provide enough information to investigate without guessing what the test intended.
Organize by feature and scenario family
Meridian groups Place Order scenarios into classes for expected paths, rejected paths, failures, edge cases, technical requirements, rollback, and specific provider-data problems. Customer Registration has its own families. Test support contains generators, builders, observations, and comparisons.
The name states operation, condition, and outcome:
/// Scenario name: the feature, its condition, and the required outcome.
public async Task PlaceOrder_WhenCustomerDoesNotExist_ThenOrderIsRejectedAndLeavesNoTrace()This is the signature of the complete refusal test. The body must still establish that condition and verify that outcome. A descriptive name and requirement reference cannot supply a missing comparison.
Use a theory when several data rows exercise the same rule with the same arrangement and expectations. Quantities one and one hundred verify the inclusive allowed boundaries. Invalid quantities zero and one hundred and one verify refusal. A different state policy or different side effect deserves its own scenario when sharing a method would hide the distinction.
Make Arrange, Act, and Assert easy to find
Arrange creates the records and request, establishes expectations, and opens observations. Act calls the public operation. Assert gathers produced values and compares them. An Arrange guard checks a premise; an outcome assertion follows Act.
Builders remove repetition in irrelevant defaults while keeping scenario values visible. Reusable asserters hide comparison mechanics behind names identifying the obligations. Keep the public invocation visible rather than putting the whole operation inside a setup helper.
The arrangement article explains default delegates and owned identities. The assertion article explains pure comparisons and accumulated reports. These conventions are supported by the PWI structure chapter and naming chapter.
Own records, observations, and teardown
The class reserves identities before work starts. Teardown uses those values:
/// Cleanup: remove only the records reserved for this scenario.
public ValueTask DisposeAsync()
{
DataManagerForTest.DeleteOrderPlacementTestRecords(
customerId: _expectedOrderPlacementIdentifiers.CustomerId,
orderReference: _expectedOrderPlacementIdentifiers.OrderReference);
return ValueTask.CompletedTask;
}Subscriber lifetime is scoped with await using. Each facade is paired with its own email capture and logger. Each independent scenario gets independent captures. Random record identities do not substitute for private broker queues or disjoint subscriptions.
The disposable runner owns a whole database for the run. Per-test teardown owns records within it. Private fault scenarios own their separate hydrated databases. The infrastructure article explains these different scopes and cancellation. Abrupt process termination may prevent normal teardown; preserve diagnosable cleanup and a deliberate orphan-cleanup procedure instead of treating every leftover object as safe to delete.
Review tests against established requirements
For every changed feature, review:
- Whether its business, acceptance, functional, and non-functional obligations are established and represented by correct scenarios.
- Whether each arrangement creates the claimed condition.
- Whether expected values come from the approved rule and suitable reference data.
- Whether the test gathers each required actual effect independently.
- Whether comparisons cover fields, counts, absence, state, and diagnostics.
- Whether cleanup remains scoped under failure as well as success.
The obligation map provides a repeatable format. Registration’s corresponding map shows how a no-return operation still has substantial stored-state obligations.
Keep failures useful outside the debugger
Comparison reports need obligation names and expected and actual values. Domain failures need precise classification, context, and original causes where relevant. Safe diagnostic checks protect credentials and bound provider data. The failure article connects those contracts to the resulting state.
When CI reports an error, start with the named scenario and its failed observation or comparison. Reproduce the arrangement, check its defining guard, and debug from the visible Act. A shared total wrong in several effects can suggest common upstream calculation trouble, but the report does not automatically identify the faulty line.
Use focused feedback and the full regression gate
During development, select the scenario being changed and nearby rule cases. Before advancing a release, run the required complete suite against its intended infrastructure. A feature subset helps iteration; the full suite protects previous functionality outside the current change.
These are workflow choices, not a measured claim that every boundary suite has the same speed. Control repeated hydration, unnecessary waits, data ownership, and diagnostic quality. An absence window is a requirement-driven observation; removing it solely to improve timing would remove evidence.
Admit supporting tests for explicit reasons
Independently tested composers may be borrowed as expectation builders. Comparison infrastructure needs tests of equal, unequal, and missing data. A dense inherited rule cluster may justify a stable smaller production boundary, as explained in adoption and refactoring.
Do not let temporary construction checks become the release authority while the assembled scenario is missing. Maintain the scenarios that demonstrate participation and complete effects. The business is paying for that continuing regression protection, and new teammates can use it to learn the system.