1. What invariant must always hold?
2. What behavior must consumers rely on?
3. What boundary can fail?
4. What state transition is legal?
5. What transition is illegal?
6. What duplicate/retry path can happen?
7. What persistence behavior matters?
8. What telemetry/audit evidence is required?
9. What test would fail if the implementation regressed?
10. What test would still pass after an internal refactor?

@Test
void testSubmit() {}

@Test
void submitCase_createsDraftCase_whenApplicantProvidesRequiredData() {}

@Test
void approveCase_rejectsCommand_whenCaseIsAlreadyClosed() {}

@Test
void processMessage_doesNotApplySideEffectTwice_whenMessageIsRedelivered() {}

operation_expectedBehavior_whenCondition

givenCondition_whenAction_thenExpectedBehavior

@Test
void approve_rejects_whenCaseIsNotPendingApproval() {
    // Arrange
    CaseFile caseFile = CaseFileTestBuilder.aCase()
            .inState(CaseState.DRAFT)
            .build();

    ApproveCase command = new ApproveCase(caseFile.id(), reviewer());

    // Act
    InvalidTransitionException error = assertThrows(
            InvalidTransitionException.class,
            () -> caseFile.approve(command)
    );

    // Assert
    assertEquals(ErrorClass.CONFLICT, error.errorClass());
    assertEquals(CaseState.DRAFT, caseFile.state());
}

public final class CaseFileTestBuilder {
    private CaseId id = CaseId.random();
    private TenantId tenantId = new TenantId("tenant-01");
    private CaseState state = CaseState.DRAFT;
    private Applicant applicant = ApplicantTestBuilder.validApplicant().build();
    private List<Evidence> evidence = new ArrayList<>();

    private CaseFileTestBuilder() {}

    public static CaseFileTestBuilder aCase() {
        return new CaseFileTestBuilder();
    }

    public CaseFileTestBuilder inState(CaseState state) {
        this.state = state;
        return this;
    }

    public CaseFileTestBuilder withEvidence(Evidence evidence) {
        this.evidence.add(evidence);
        return this;
    }

    public CaseFile build() {
        return CaseFile.restore(id, tenantId, state, applicant, List.copyOf(evidence));
    }
}

[ ] Defaults should create a valid object.
[ ] Test should override only what matters.
[ ] Builder should not hide important domain meaning.
[ ] Avoid global mutable fixture state.
[ ] Avoid random data unless the test controls seed or does not depend on value.

CaseFile caseFile = TestFixtures.caseFileScenario17();

public final class CaseFiles {
    public static CaseFile pendingApproval() {
        return CaseFileTestBuilder.aCase()
                .inState(CaseState.PENDING_APPROVAL)
                .withEvidence(EvidenceTestBuilder.validEvidence().build())
                .build();
    }
}

CaseFile caseFile = CaseFileTestBuilder.aCase()
        .inState(CaseState.UNDER_REVIEW)
        .withEvidence(expiredEvidence())
        .build();

Use a fake when behavior matters.
Use a stub when an answer matters.
Use a spy when an emitted side effect matters.
Use a mock when the interaction itself is the contract.

final class StubRiskScoringClient implements RiskScoringClient {
    private final RiskLevel riskLevel;

    StubRiskScoringClient(RiskLevel riskLevel) {
        this.riskLevel = riskLevel;
    }

    @Override
    public RiskLevel score(CaseFile caseFile) {
        return riskLevel;
    }
}

final class RecordingDomainEventPublisher implements DomainEventPublisher {
    private final List<DomainEvent> published = new ArrayList<>();

    @Override
    public void publish(DomainEvent event) {
        published.add(event);
    }

    public List<DomainEvent> published() {
        return List.copyOf(published);
    }
}

@Test
void close_rejects_whenCaseHasUnresolvedEscalation() {
    CaseFile caseFile = CaseFileTestBuilder.aCase()
            .inState(CaseState.UNDER_REVIEW)
            .withEscalation(Escalation.open("SLA_BREACH"))
            .build();

    InvalidTransitionException error = assertThrows(
            InvalidTransitionException.class,
            () -> caseFile.close(bySupervisor())
    );

    assertEquals(CaseState.UNDER_REVIEW, caseFile.state());
    assertEquals("OPEN_ESCALATION", error.reasonCode());
}

[ ] legal transition succeeds;
[ ] illegal transition fails;
[ ] state remains unchanged after failure;
[ ] domain event is emitted on success;
[ ] no domain event is emitted on failure;
[ ] version or audit metadata changes only when appropriate;
[ ] error class/reason is stable.

@ParameterizedTest
@MethodSource("transitionCases")
void transitionPolicy_returnsExpectedDecision(
        CaseState from,
        Action action,
        Role role,
        boolean expectedAllowed
) {
    TransitionPolicy policy = new TransitionPolicy();

    boolean allowed = policy.canPerform(from, action, role);

    assertEquals(expectedAllowed, allowed);
}

static Stream<Arguments> transitionCases() {
    return Stream.of(
            Arguments.of(CaseState.DRAFT, Action.SUBMIT, Role.APPLICANT, true),
            Arguments.of(CaseState.DRAFT, Action.APPROVE, Role.REVIEWER, false),
            Arguments.of(CaseState.PENDING_APPROVAL, Action.APPROVE, Role.REVIEWER, true),
            Arguments.of(CaseState.CLOSED, Action.APPROVE, Role.REVIEWER, false)
    );
}

A case cannot move from CLOSED to UNDER_REVIEW.
Total allocation cannot exceed available budget.
Sorted output is always non-decreasing.
Serialization then deserialization preserves value.
Applying same idempotent command twice has same final state.

@Property
void normalizedEmail_isAlwaysLowercase(@ForAll String input) {
    assumeFalse(input.isBlank());

    Email email = Email.normalize(input + "@example.com");

    assertEquals(email.value(), email.value().toLowerCase(Locale.ROOT));
}

[ ] independent of implementation;
[ ] true for broad input range;
[ ] meaningful when it fails;
[ ] shrinks to understandable counterexample;
[ ] does not depend on external nondeterminism.

@Test
void legacyRiskScore_preservesCurrentBoundaryBehavior_forHighValueCase() {
    LegacyRiskService service = new LegacyRiskService();

    RiskScore score = service.calculate(legacyHighValueCase());

    assertEquals(new RiskScore(87), score);
}

@Test
void enforcementReport_matchesApprovedOutput() {
    EnforcementReport report = reportGenerator.generate(caseScenario());

    String actual = normalize(report.toMarkdown());

    assertEquals(readResource("approved/enforcement-report.md"), actual);
}

{
  "request": {
    "method": "POST",
    "path": "/cases",
    "headers": {
      "Idempotency-Key": "string"
    }
  },
  "response": {
    "status": 201,
    "body": {
      "caseId": "string",
      "state": "DRAFT"
    }
  }
}

{
  "eventType": "CaseSubmitted",
  "schemaVersion": 3,
  "requiredHeaders": [
    "eventId",
    "correlationId",
    "tenantId",
    "occurredAt"
  ],
  "payload": {
    "caseId": "string",
    "caseType": "string",
    "submittedBy": "string"
  }
}

[ ] Required fields are explicit.
[ ] Optional fields are explicit.
[ ] Unknown fields policy is explicit.
[ ] Error format is tested.
[ ] Backward compatibility is tested.
[ ] Event schema version is tested.
[ ] Consumer assumptions are captured.

[ ] mapping between entity and table;
[ ] required columns and constraints;
[ ] unique constraints;
[ ] optimistic locking version;
[ ] pagination order;
[ ] query filters including tenant boundary;
[ ] soft-delete behavior;
[ ] temporal validity queries;
[ ] transaction rollback;
[ ] outbox insert in same transaction.

@Test
void save_incrementsVersion_whenAggregateIsUpdated() {
    CaseFile saved = repository.save(CaseFileTestBuilder.aCase().build());

    saved.submit(byApplicant());
    CaseFile updated = repository.save(saved);

    assertEquals(1, updated.version());
}

@Testcontainers
class CaseRepositoryTest {
    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine");

    @Test
    void findByTenant_doesNotReturnOtherTenantCases() {
        CaseRepository repository = repositoryConnectedTo(postgres);

        repository.save(caseFor("tenant-a"));
        repository.save(caseFor("tenant-b"));

        List<CaseFile> result = repository.findByTenant(new TenantId("tenant-a"));

        assertEquals(1, result.size());
        assertEquals(new TenantId("tenant-a"), result.getFirst().tenantId());
    }
}

@Test
void submit_rollsBackCaseAndOutbox_whenAuditWriteFails() {
    AuditWriter failingAudit = auditWriterThatFails();
    SubmitCaseService service = serviceWith(failingAudit);

    assertThrows(AuditWriteException.class, () -> service.submit(validCommand()));

    assertTrue(caseRepository.findAll().isEmpty());
    assertTrue(outboxRepository.findAll().isEmpty());
}

[ ] success commits all required writes;
[ ] failure rolls back all transactional writes;
[ ] outbox write is atomic with aggregate write;
[ ] audit behavior is intentionally transactional or non-transactional;
[ ] duplicate command does not duplicate side effect;
[ ] optimistic lock conflict is surfaced as conflict, not generic error.

@Test
void submitCase_persistsOutboxEvent_inSameTransaction() {
    SubmitCase command = validSubmitCase();

    CaseId caseId = service.submit(command);

    List<OutboxRecord> records = outboxRepository.findPending();
    assertEquals(1, records.size());
    assertEquals("CaseSubmitted", records.getFirst().eventType());
    assertEquals(caseId.value(), records.getFirst().aggregateId());
}

@Test
void consume_doesNotApplySideEffectTwice_whenMessageIsRedelivered() {
    MessageEnvelope<CaseSubmitted> message = caseSubmittedMessage();

    consumer.consume(message);
    consumer.consume(message);

    assertEquals(1, projectionRepository.countByCaseId(message.payload().caseId()));
    assertTrue(inboxRepository.wasProcessed(message.eventId()));
}

@Test
void consume_movesToDeadLetter_whenMessageIsPoisonAfterMaxAttempts() {
    MessageEnvelope<CaseSubmitted> message = invalidMessage();

    repeat(3, () -> consumer.consume(message));

    DeadLetterRecord deadLetter = deadLetterRepository.findByMessageId(message.eventId()).orElseThrow();
    assertEquals("VALIDATION", deadLetter.failureClass());
    assertFalse(deadLetter.replayEligible());
}

@ParameterizedTest
@MethodSource("illegalTransitions")
void illegalTransitions_areRejected(CaseState from, CaseAction action) {
    CaseWorkflow workflow = CaseWorkflowTestBuilder.workflow()
            .inState(from)
            .build();

    assertThrows(InvalidTransitionException.class, () -> workflow.apply(action));
}

static Stream<Arguments> illegalTransitions() {
    return Stream.of(
            Arguments.of(CaseState.DRAFT, CaseAction.APPROVE),
            Arguments.of(CaseState.CLOSED, CaseAction.SUBMIT),
            Arguments.of(CaseState.REJECTED, CaseAction.ESCALATE)
    );
}

@Test
void escalate_recordsTimelineEntry_andPublishesEvent() {
    RecordingDomainEventPublisher events = new RecordingDomainEventPublisher();
    RecordingTimeline timeline = new RecordingTimeline();
    CaseWorkflow workflow = workflowUnderReview(events, timeline);

    workflow.escalate(reason("SLA_BREACH"));

    assertEquals(CaseState.ESCALATED, workflow.state());
    assertTrue(events.containsEvent("CaseEscalated"));
    assertTrue(timeline.containsTransition("UNDER_REVIEW", "ESCALATED"));
}

@Test
void call_retriesAndSucceeds_whenDependencyFailsOnce() {
    FlakyRiskClient client = new FlakyRiskClient()
            .failTimes(1)
            .thenReturn(RiskLevel.HIGH);

    RiskLevel result = serviceWith(client).calculateRisk(caseFile());

    assertEquals(RiskLevel.HIGH, result);
    assertEquals(2, client.callCount());
}

@Test
void call_failsWithDependencyUnavailable_whenRetriesExhausted() {
    AlwaysFailingRiskClient client = new AlwaysFailingRiskClient();

    DependencyUnavailableException error = assertThrows(
            DependencyUnavailableException.class,
            () -> serviceWith(client).calculateRisk(caseFile())
    );

    assertEquals(ErrorClass.DEPENDENCY_UNAVAILABLE, error.errorClass());
    assertEquals(3, client.callCount());
}

@Test
void call_usesFallback_andEmitsMetric_whenRiskServiceUnavailable() {
    RecordingCaseMetrics metrics = new RecordingCaseMetrics();
    RiskService service = serviceWith(alwaysUnavailableRiskClient(), metrics);

    RiskLevel result = service.calculateRisk(caseFile());

    assertEquals(RiskLevel.UNKNOWN, result);
    assertTrue(metrics.contains("fallback:risk.calculate:DEPENDENCY_UNAVAILABLE"));
}

@Test
void submit_emitsTimelineAndAuditRecord() {
    RecordingTimeline timeline = new RecordingTimeline();
    RecordingAuditLog audit = new RecordingAuditLog();
    SubmitCaseService service = serviceWith(timeline, audit);

    CaseId caseId = service.submit(validCommand());

    assertTrue(timeline.contains("CaseSubmitted", caseId));
    assertTrue(audit.containsDecision("CASE_SUBMIT", "ALLOW"));
}

@Test
void validationFailure_doesNotLogRawDocumentContent() {
    RecordingLogSink logs = new RecordingLogSink();
    SubmitCaseService service = serviceWith(logs);

    assertThrows(ValidationException.class, () -> service.submit(commandWithSensitiveDocument()));

    assertFalse(logs.contains("raw passport text"));
    assertTrue(logs.contains("error_class=VALIDATION"));
}

[ ] request JSON maps to command;
[ ] validation errors produce stable response shape;
[ ] authorization denial produces 403 shape;
[ ] idempotency header is required where needed;
[ ] correlation ID is returned/propagated;
[ ] API does not expose internal exception names.

1. Applicant submits case.
2. Evidence is attached.
3. Risk is calculated.
4. Case is assigned.
5. Reviewer approves.
6. Enforcement action is created.
7. Audit trail is visible.

[ ] Keep E2E tests few.
[ ] Test business-critical paths only.
[ ] Avoid asserting implementation details.
[ ] Make failures easy to diagnose.
[ ] Do not replace lower-level invariant tests with E2E tests.

public final class SlaPolicy {
    private final Clock clock;

    public SlaPolicy(Clock clock) {
        this.clock = clock;
    }

    public boolean isBreached(CaseFile caseFile) {
        Instant now = clock.instant();
        return caseFile.submittedAt().plus(Duration.ofDays(5)).isBefore(now);
    }
}

@Test
void isBreached_returnsTrue_afterFiveDays() {
    Clock fixed = Clock.fixed(Instant.parse("2026-06-27T00:00:00Z"), ZoneOffset.UTC);
    SlaPolicy policy = new SlaPolicy(fixed);

    CaseFile caseFile = CaseFileTestBuilder.aCase()
            .submittedAt(Instant.parse("2026-06-20T00:00:00Z"))
            .build();

    assertTrue(policy.isBreached(caseFile));
}

public interface IdGenerator {
    CaseId nextCaseId();
}

final class FixedIdGenerator implements IdGenerator {
    @Override
    public CaseId nextCaseId() {
        return new CaseId("CASE-TEST-001");
    }
}

[ ] Tests can run in any order.
[ ] Tests can run repeatedly.
[ ] Tests can run in parallel or are explicitly marked not parallel.
[ ] Static mutable state is reset.
[ ] Caches are cleared or isolated.
[ ] Clocks and ID generators are deterministic.

assertNotNull(result);

condition is inverted?
state transition target is wrong?
event is not published?
authorization check is removed?
idempotency check is removed?
tenant filter is removed?
retry count changes from 3 to 1?

assertEquals(CaseState.PENDING_APPROVAL, result.state());
assertEquals(1, events.count("CaseSubmitted"));
assertEquals(command.idempotencyKey(), result.creationCommandKey());

Validation failure
Authorization failure
Conflict/optimistic lock
Dependency timeout
Duplicate command
Serialization failure
Poison message
Dead-letter after max attempts
Transaction rollback
Partial external failure
Cancellation

verify(repository).save(any());
verify(publisher).publish(any());
verify(metrics).increment(any());

Thread.sleep(5000);
assertTrue(done);

1. Identify top production risks and recent bugs.
2. Add characterization tests around risky legacy behavior.
3. Add domain invariant tests for critical aggregates/policies.
4. Add repository tests for important persistence assumptions.
5. Add contract tests for APIs/events with external consumers.
6. Add idempotency tests for commands/messages.
7. Add workflow transition matrix tests.
8. Add resilience tests for retry/timeout/fallback paths.
9. Remove or rewrite brittle over-mocked tests.
10. Keep a small E2E smoke suite for critical journeys.

Intent
[ ] Does each test have a clear behavioral reason?
[ ] Would a reader know what risk this test protects?

Domain
[ ] Are invariants tested?
[ ] Are illegal transitions tested?
[ ] Are edge cases tested?

Boundaries
[ ] Are API contracts tested?
[ ] Are event contracts tested?
[ ] Are database constraints tested against real DB semantics?
[ ] Are tenant and authorization boundaries tested?

Failure
[ ] Are validation, conflict, timeout, dependency failure, duplicate, and poison-message paths tested?
[ ] Are retry/fallback/circuit behaviors observable and tested?

Fixtures
[ ] Are fixtures readable?
[ ] Do defaults create valid objects?
[ ] Are irrelevant details hidden?

Doubles
[ ] Are mocks used only where interaction is the contract?
[ ] Are fakes realistic enough for the test purpose?
[ ] Do tests avoid verifying private implementation details?

Determinism
[ ] Is time controlled?
[ ] Are IDs controlled?
[ ] Are tests order-independent?
[ ] Are async tests not sleep-based?

Maintainability
[ ] Would the test survive a safe refactor?
[ ] Are assertions strong enough to catch meaningful mutation?

3 legal transitions
5 illegal transitions
failure state unchanged
success event emitted
failure event not emitted

tenant filter
unique constraint
optimistic lock
pagination order
soft delete
temporal query

first delivery applies side effect
second delivery does not duplicate side effect
inbox record is created
metric/log indicates duplicate

final state
published domain event
persisted record
visible output
classified failure

invalid input
authorization denied
stale version
dependency timeout
duplicate command
transaction failure