This part does not assume CSG uses JUnit 5, Mockito, AssertJ, JerseyTest,
REST Assured, Arquillian, Spring Test, Maven Surefire/Failsafe, or any specific
internal testing framework.

Treat all framework choices, test naming standards, CI quality gates, and
endpoint test harnesses as internal verification items.

Is there a test?

What behavior is protected?
What failure mode is reproduced?
What contract is locked?
What regression would this test catch?
What production incident would this test have prevented?

verify(mockRepository).save(any())

Given input X and system state Y
when operation Z occurs
then externally observable behavior must be A
and side effect B must happen exactly once
and error C must be returned for invalid state

Using only unit tests and missing runtime behavior.
Using only E2E tests and making feedback slow/flaky.
Testing mocks instead of behavior.
Testing implementation instead of contract.

deterministic
fast
side-effect-light
input/output visible
high business value
high branch complexity

DTO/domain mapper
validation helper
price rounding policy
date/time effective-window logic
permission decision
idempotency decision
retry classification
error code mapping
query parameter parser
filter expression parser

JAX-RS routing
provider discovery
JSON provider behavior
container-managed injection
real transaction boundary
Kafka offset commit behavior
PostgreSQL locking behavior

@Test
void shouldRejectQuoteWhenEffectiveDateIsOutsideCatalogValidity() {
    // given
    CatalogVersion catalog = CatalogVersion.validFromTo(
        LocalDate.parse("2026-01-01"),
        LocalDate.parse("2026-12-31")
    );
    QuoteRequest request = new QuoteRequest(
        "tenant-a",
        LocalDate.parse("2027-01-10")
    );

    // when
    ValidationResult result = validator.validate(request, catalog);

    // then
    assertThat(result.isValid()).isFalse();
    assertThat(result.errorCode()).isEqualTo("CATALOG_EFFECTIVE_DATE_OUT_OF_RANGE");
}

name states expected behavior
input is explicit
business boundary is visible
assertion checks observable result
no irrelevant mock interaction

should<ExpectedBehavior>When<Condition>

shouldReturnBadRequestWhenRequiredQueryParamIsMissing
shouldMapDomainConflictTo409WhenQuoteAlreadySubmitted
shouldPropagateCorrelationIdWhenPresent
shouldGenerateCorrelationIdWhenMissing
shouldRejectTokenWhenAudienceDoesNotMatchService
shouldNotRetryWhenDownstreamReturns400
shouldRoundTaxAmountUsingConfiguredRoundingMode

test1
testSubmitQuote
shouldCallRepository
shouldWork

verify(eventPublisher).publish(argThat(event ->
    event.type().equals("QuoteSubmitted") &&
    event.quoteId().equals(quoteId)
));

verify(repository).save(any());

Does the interaction itself represent contract behavior?
Or are we testing private implementation?

If a refactor breaks many tests without changing behavior,
you probably tested implementation too deeply.

class InMemoryQuoteRepository implements QuoteRepository {
    private final Map<QuoteId, Quote> quotes = new ConcurrentHashMap<>();

    @Override
    public void save(Quote quote) {
        quotes.put(quote.id(), quote);
    }

    @Override
    public Optional<Quote> findById(QuoteId id) {
        return Optional.ofNullable(quotes.get(id));
    }
}

HTTP method
path
query/path/header binding
request body deserialization
validation
status code
response body shape
response headers
error envelope
security behavior when applicable
correlation/logging/tracing behavior when applicable

class QuoteResourceTest {
    private QuoteApplicationService service;
    private QuoteResource resource;

    @BeforeEach
    void setUp() {
        service = mock(QuoteApplicationService.class);
        resource = new QuoteResource(service);
    }

    @Test
    void shouldReturnCreatedWhenQuoteIsCreated() {
        QuoteCreateRequest request = new QuoteCreateRequest("tenant-a", "customer-1");
        QuoteId quoteId = new QuoteId("q-123");

        when(service.createQuote(any())).thenReturn(quoteId);

        Response response = resource.create(request);

        assertThat(response.getStatus()).isEqualTo(201);
        assertThat(response.getHeaderString("Location")).isEqualTo("/quotes/q-123");
    }
}

fast
simple
no container needed
business-to-response mapping visible

does not test annotation routing
does not test provider/filter behavior
does not test JSON serialization
does not test validation integration
does not test dependency injection runtime

class QuoteResourceJerseyTest extends JerseyTest {
    @Override
    protected Application configure() {
        return new ResourceConfig()
            .register(new QuoteResource(new FakeQuoteService()))
            .register(GlobalExceptionMapper.class)
            .register(JsonProvider.class)
            .register(CorrelationIdFilter.class);
    }

    @Test
    void shouldReturnBadRequestForInvalidBody() {
        Response response = target("/quotes")
            .request()
            .post(Entity.json("{}"));

        assertThat(response.getStatus()).isEqualTo(400);

        ErrorResponse body = response.readEntity(ErrorResponse.class);
        assertThat(body.code()).isEqualTo("VALIDATION_FAILED");
    }
}

JerseyTest is Jersey-specific.
If the internal stack does not use Jersey, verify the approved endpoint test harness.

happy path status/body/header
invalid request body
missing required parameter
invalid query parameter type
unsupported media type
not acceptable media type
domain conflict mapped to correct HTTP error
technical error mapped to safe generic response
correlation ID returned or propagated
sensitive data not leaked in error

@GET
@Path("/quotes")
@Produces(MediaType.APPLICATION_JSON)
public Response searchQuotes(
    @QueryParam("tenantId") String tenantId,
    @QueryParam("status") String status,
    @QueryParam("limit") @DefaultValue("50") int limit
) {
    // ...
}

@Test
void shouldUseDefaultLimitWhenLimitIsMissing() {
    Response response = target("/quotes")
        .queryParam("tenantId", "tenant-a")
        .queryParam("status", "DRAFT")
        .request()
        .get();

    assertThat(response.getStatus()).isEqualTo(200);
    assertThat(fakeService.lastLimit()).isEqualTo(50);
}

@Test
void shouldReturnBadRequestWhenLimitIsNotANumber() {
    Response response = target("/quotes")
        .queryParam("tenantId", "tenant-a")
        .queryParam("limit", "abc")
        .request()
        .get();

    assertThat(response.getStatus()).isEqualTo(400);
}

@Test
void shouldRejectNegativeQuantity() {
    ConstraintViolation<QuoteLineRequest> violation = validate(
        new QuoteLineRequest("product-a", new BigDecimal("-1"))
    ).single();

    assertThat(violation.getPropertyPath().toString()).isEqualTo("quantity");
}

@Test
void shouldReturnValidationEnvelopeWhenRequestBodyIsInvalid() {
    Response response = target("/quotes")
        .request()
        .post(Entity.json("""
            { "tenantId": "", "customerId": null }
            """));

    assertThat(response.getStatus()).isEqualTo(400);

    ErrorResponse error = response.readEntity(ErrorResponse.class);
    assertThat(error.code()).isEqualTo("VALIDATION_FAILED");
    assertThat(error.fields()).extracting("field")
        .contains("tenantId", "customerId");
}

public class DomainConflictExceptionMapper
        implements ExceptionMapper<DomainConflictException> {

    @Override
    public Response toResponse(DomainConflictException exception) {
        return Response.status(Response.Status.CONFLICT)
            .entity(ErrorResponse.of(exception.code(), exception.safeMessage()))
            .type(MediaType.APPLICATION_JSON_TYPE)
            .build();
    }
}

@Test
void shouldMapDomainConflictTo409() {
    DomainConflictException ex = new DomainConflictException(
        "QUOTE_ALREADY_SUBMITTED",
        "Quote has already been submitted"
    );

    Response response = mapper.toResponse(ex);

    assertThat(response.getStatus()).isEqualTo(409);
    assertThat(response.getMediaType()).isEqualTo(MediaType.APPLICATION_JSON_TYPE);

    ErrorResponse body = (ErrorResponse) response.getEntity();
    assertThat(body.code()).isEqualTo("QUOTE_ALREADY_SUBMITTED");
}

@Test
void shouldUseGlobalExceptionMapperAtRuntime() {
    fakeService.failWith(new DomainConflictException("QUOTE_ALREADY_SUBMITTED", "..."));

    Response response = target("/quotes/q-1/submit")
        .request()
        .post(Entity.json("{}"));

    assertThat(response.getStatus()).isEqualTo(409);
}

authentication
authorization
correlation ID
MDC population
request logging
response headers
CORS/security headers
rate limiting

If X-Correlation-ID is present, preserve it.
If missing, generate one.
Always return it in the response header.
Always place it in MDC during request processing.
Always clear MDC after request.

shouldPreserveCorrelationIdWhenPresent
shouldGenerateCorrelationIdWhenMissing
shouldReturnCorrelationIdInResponseHeader
shouldClearMdcAfterRequest
shouldNotLogAuthorizationHeader

mocked JAX-RS context objects for narrow behavior
in-memory endpoint runtime for full pipeline behavior

@Test
void shouldRejectAccessToDifferentTenantQuote() {
    TestToken token = tokenForTenant("tenant-a").withPermission("quote:read");

    Response response = target("/tenants/tenant-b/quotes/q-1")
        .request()
        .header("Authorization", token.asBearer())
        .get();

    assertThat(response.getStatus()).isIn(List.of(403, 404));
}

@Test
void shouldSerializeQuoteResponseWithStableFieldNames() throws Exception {
    QuoteResponse response = new QuoteResponse(
        "q-123",
        "DRAFT",
        new BigDecimal("10.50"),
        OffsetDateTime.parse("2026-07-10T10:15:30Z")
    );

    String json = objectMapper.writeValueAsString(response);

    assertThatJson(json).isEqualTo("""
        {
          "quoteId": "q-123",
          "status": "DRAFT",
          "totalAmount": 10.50,
          "createdAt": "2026-07-10T10:15:30Z"
        }
        """);
}

UTC serialization
local timezone conversion
DST boundary
effective date start/end
catalog validity window
pricing effective date
BigDecimal scale
rounding mode
tax boundary

class PricingService {
    private final Clock clock;

    PricingService(Clock clock) {
        this.clock = clock;
    }

    Price calculate(...) {
        Instant now = clock.instant();
        // ...
    }
}

@Test
void shouldUseConfiguredClockForEffectivePricingDate() {
    Clock fixedClock = Clock.fixed(
        Instant.parse("2026-07-10T00:00:00Z"),
        ZoneOffset.UTC
    );

    PricingService service = new PricingService(fixedClock);

    Price price = service.calculate(request);

    assertThat(price.effectiveAt()).isEqualTo(Instant.parse("2026-07-10T00:00:00Z"));
}

first request creates state
same idempotency key returns same result
same key with different payload is rejected
concurrent same key does not create duplicate side effect
expired key behavior is explicit

@Test
void shouldReturnSameResponseForRepeatedIdempotencyKey() {
    String key = "idem-123";

    Response first = target("/quotes")
        .request()
        .header("Idempotency-Key", key)
        .post(Entity.json(validRequest));

    Response second = target("/quotes")
        .request()
        .header("Idempotency-Key", key)
        .post(Entity.json(validRequest));

    assertThat(first.getStatus()).isEqualTo(201);
    assertThat(second.getStatus()).isIn(List.of(200, 201));
    assertThat(second.readEntity(String.class)).isEqualTo(first.readEntity(String.class));
}

correlation ID is returned
correlation ID is propagated to downstream client
MDC is populated and cleared
sensitive headers are redacted
error responses contain safe error ID
metrics tags do not include high-cardinality user input

@Test
void shouldNotExposeInternalExceptionMessage() {
    fakeService.failWith(new RuntimeException("password=secret internal stack detail"));

    Response response = target("/quotes")
        .request()
        .post(Entity.json(validRequest));

    String body = response.readEntity(String.class);

    assertThat(response.getStatus()).isEqualTo(500);
    assertThat(body).doesNotContain("password=secret");
    assertThat(body).doesNotContain("stack detail");
}

class QuoteRequestBuilder {
    private String tenantId = "tenant-a";
    private String customerId = "customer-1";
    private List<QuoteLineRequest> lines = List.of(
        new QuoteLineRequest("product-a", new BigDecimal("1"))
    );

    static QuoteRequestBuilder validQuoteRequest() {
        return new QuoteRequestBuilder();
    }

    QuoteRequestBuilder withoutTenant() {
        this.tenantId = null;
        return this;
    }

    QuoteCreateRequest build() {
        return new QuoteCreateRequest(tenantId, customerId, lines);
    }
}

QuoteCreateRequest request = validQuoteRequest()
    .withoutTenant()
    .build();

src/test/java
  com.example.quote
    api
      QuoteResourceTest.java
      QuoteResourceJerseyTest.java
      GlobalExceptionMapperTest.java
      CorrelationIdFilterTest.java
    application
      SubmitQuoteServiceTest.java
    domain
      QuoteStateMachineTest.java
      PricingPolicyTest.java
    mapping
      QuoteMapperTest.java
    security
      PermissionEvaluatorTest.java

unit tests      -> Maven Surefire -> *Test.java
integration    -> Maven Failsafe -> *IT.java

QuoteServiceTest.java        // unit
QuoteResourceTest.java       // resource/unit-ish
QuoteResourceIT.java         // container/integration
QuoteDatabaseIT.java         // PostgreSQL/Testcontainers
KafkaConsumerIT.java         // Kafka/Testcontainers

unit tests run on every commit
endpoint tests run on every PR
integration tests run on every PR or gated branch
contract tests run before merge/release
performance tests run on schedule or release gate

wrong status code
wrong media type
missing header
broken error envelope
validation not active
ExceptionMapper not registered
filter not registered
JSON date format drift
sensitive error leak
correlation ID not returned
wrong tenant access behavior

rounding bug
wrong state transition
permission decision bug
retry classification bug
idempotency mismatch
mapper field loss
validation boundary bug

behavior regression
wrong test expectation
test fixture drift
time-dependent flake
order-dependent flake
environment dependency issue
mock too strict
serialization/config mismatch

Did the public contract change?
Was the change intentional?
Is compatibility preserved?
Do consumers need migration?
Does the test represent current expected behavior?

Does the PR add or modify behavior?
Is the behavior protected by a test?
Do tests include negative paths?
Are status codes and error envelopes asserted?
Are headers/media types asserted where relevant?
Are validation failures tested at HTTP boundary?
Are security failures tested negatively?
Are date/time/currency edge cases covered?
Are mocks used only where interaction is meaningful?
Are tests deterministic?
Are test names readable?
Are fixtures small and intentional?
Would this test catch a real regression?

only happy-path tests
asserting only non-null
excessive verify calls
Thread.sleep in tests
shared mutable fixture
no endpoint-level test for new resource
no error test for new exception mapper
no security negative test for protected endpoint

Which test framework is standard: JUnit 4, JUnit 5, TestNG, other?
Which assertion library is standard?
Which mocking library is approved?
Is JerseyTest used for endpoint tests?
Is REST Assured used?
Is Arquillian or a container-based test harness used?
How are resource classes instantiated in tests?
How are providers/filters/exception mappers registered in tests?
How is JSON ObjectMapper/JSON-B config shared with tests?
How are validation errors tested?
What is the naming convention for unit vs integration tests?
Which tests run in PR vs nightly vs release pipeline?
What is the quality gate for coverage, mutation testing, or contract testing?
How are flaky tests tracked?
How are secrets/config avoided in tests?
How are tenant and permission scenarios tested?
What is the expected minimum test for a new endpoint?
What is the expected minimum test for a new error code?
What is the expected minimum test for a new mapper or DTO field?

A test should fail for the right reason.
A test should explain behavior without reading implementation.
A test should protect a contract, invariant, or failure mode.
A test should be deterministic.
A test should be easy to debug when it fails.
A test should not make safe refactoring painful.

Is this behavior verified at the same boundary where it can break?

unit tests protect deterministic logic
endpoint tests protect HTTP/JAX-RS boundary behavior
provider/filter tests protect cross-cutting pipeline behavior
negative tests protect production failure modes
review checklist protects compatibility and operability

The behavior changed.
The right boundary is tested.
The failure modes are covered.
The test will catch a real regression.
The test will not block safe refactoring.