Does the endpoint work?

Does this boundary preserve the contract under normal, invalid, duplicate, concurrent, and degraded conditions?

OpenAPI contract
Generated DTOs
JAX-RS/Jersey resource
Request filters
Validation layer
Authorization context
Idempotency store
Application service
PostgreSQL transaction
Outbox insert
Error mapper
Response schema
Observability metadata

A test must not invent API shapes that are not in the contract.

String request = """
  { "name": "Case X" }
""";

Use examples from the OpenAPI contract.
Validate request examples against request schemas.
Validate actual responses against response schemas.
Generate or centrally define fixtures from contract-owned samples.

contracts/openapi/case-command-api.yaml
contracts/examples/cases/create-case-request.valid.json
contracts/examples/cases/create-case-response.accepted.json
contracts/examples/problems/validation-error.json

case-platform/
  contracts/
    openapi/
      case-command-api.yaml
      case-query-api.yaml
    examples/
      cases/
      problems/

  case-contract-tests/
    src/test/java/...      # OpenAPI lint, example validation, compatibility checks

  case-api-generated/
    src/generated/java/... # generated DTO/resource interfaces

  case-api-jersey/
    src/main/java/...      # Jersey ResourceConfig, filters, mappers
    src/test/java/...      # Jersey boundary tests

  case-application/
    src/main/java/...      # use cases, commands, result types
    src/test/java/...      # pure application tests

  case-persistence-postgres/
    src/main/java/...      # MyBatis mappers, repositories
    src/test/java/...      # mapper + Testcontainers PostgreSQL

  case-api-integration-tests/
    src/test/java/...      # API + DB + Kafka + outbox tests

  case-deployment-tests/
    src/test/java/...      # container runtime smoke tests, optional

paths:
  /cases:
    post:
      operationId: createCase
      x-capability: case-intake
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/CorrelationId'
      responses:
        '202':
          description: Case accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCaseAcceptedResponse'
        '400':
          $ref: '#/components/responses/BadRequestProblem'
        '409':
          $ref: '#/components/responses/ConflictProblem'
        '422':
          $ref: '#/components/responses/SemanticValidationProblem'
        '500':
          $ref: '#/components/responses/InternalProblem'

contracts/examples/cases/create-case-request.valid.json
contracts/examples/cases/create-case-request.invalid-missing-subject.json
contracts/examples/cases/create-case-response.accepted.json
contracts/examples/problems/validation-error.json
contracts/examples/problems/conflict-error.json

@Test
void createCaseValidExample_matchesOpenApiRequestSchema() {
    OpenApiContract contract = OpenApiContract.load("contracts/openapi/case-command-api.yaml");
    JsonNode example = Json.read("contracts/examples/cases/create-case-request.valid.json");

    SchemaValidationResult result = contract.validateRequestBody(
        "POST",
        "/cases",
        "application/json",
        example
    );

    assertThat(result.errors()).isEmpty();
}

The contract says one thing.
The examples say another.
The implementation follows a third thing.

class CaseResourceContractTest extends JerseyTest {

    private final FakeCreateCaseUseCase createCaseUseCase = new FakeCreateCaseUseCase();

    @Override
    protected Application configure() {
        return new ResourceConfig()
            .register(new CaseResource(createCaseUseCase))
            .register(new CorrelationIdFilter())
            .register(new ProblemDetailsExceptionMapper())
            .register(new JsonProvider())
            .property("jersey.config.beanValidation.enableOutputValidationErrorEntity.server", true);
    }

    @Test
    void createCase_whenAccepted_returns202AndProblemFreeContractShape() {
        createCaseUseCase.nextResult = CreateCaseResult.accepted(
            new CaseId("case_01J9YV"),
            new ProcessInstanceRef("camunda_123")
        );

        Response response = target("/cases")
            .request()
            .header("Idempotency-Key", "idem-001")
            .header("X-Correlation-Id", "corr-001")
            .post(Entity.json(validCreateCaseRequest()));

        assertThat(response.getStatus()).isEqualTo(202);
        assertThat(response.getHeaderString("X-Correlation-Id")).isEqualTo("corr-001");

        JsonNode body = response.readEntity(JsonNode.class);
        assertThat(body.get("caseId").asText()).isEqualTo("case_01J9YV");
    }
}

createCaseUseCase.nextResult = CreateCaseResult.duplicate(...);
createCaseUseCase.nextResult = CreateCaseResult.semanticViolation(...);
createCaseUseCase.nextResult = CreateCaseResult.authorizationDenied(...);
createCaseUseCase.nextResult = CreateCaseResult.unavailable(...);

application result -> HTTP response

final class ApiContractAssert {
    private final OpenApiContract contract;

    void assertResponse(String method, String path, int status, String contentType, JsonNode body) {
        SchemaValidationResult result = contract.validateResponseBody(
            method,
            path,
            status,
            contentType,
            body
        );

        if (!result.errors().isEmpty()) {
            throw new AssertionError(result.render());
        }
    }
}

@Test
void validationError_matchesOpenApiProblemSchema() {
    Response response = target("/cases")
        .request()
        .header("Idempotency-Key", "idem-002")
        .post(Entity.json("{}"));

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

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

    apiContractAssert.assertResponse(
        "POST",
        "/cases",
        400,
        "application/problem+json",
        body
    );
}

{
  "error": "bad request"
}

{
  "type": "https://errors.case-platform.local/http/validation-failed",
  "title": "Validation failed",
  "status": 400,
  "code": "HTTP.VALIDATION_FAILED",
  "correlationId": "corr-001",
  "violations": [
    {
      "field": "subject.externalRef",
      "message": "must not be blank"
    }
  ]
}

@ParameterizedTest
@MethodSource("invalidCreateCasePayloads")
void createCase_invalidPayload_returns400Problem(String fixturePath) {
    JsonNode payload = Json.read(fixturePath);

    Response response = target("/cases")
        .request()
        .header("Idempotency-Key", UUID.randomUUID().toString())
        .post(Entity.json(payload));

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

    JsonNode problem = response.readEntity(JsonNode.class);
    assertThat(problem.get("code").asText()).isEqualTo("HTTP.VALIDATION_FAILED");
    assertThat(problem.has("correlationId")).isTrue();
}

@Test
void createCase_duplicateSameIdempotencyKey_doesNotCreateSecondCaseOrOutboxEvent() {
    String idemKey = "idem-" + UUID.randomUUID();
    JsonNode request = Json.read("contracts/examples/cases/create-case-request.valid.json");

    ApiResponse first = api.postJson("/cases", idemKey, request);
    ApiResponse second = api.postJson("/cases", idemKey, request);

    assertThat(first.status()).isEqualTo(202);
    assertThat(second.status()).isEqualTo(202);
    assertThat(second.body().get("caseId").asText())
        .isEqualTo(first.body().get("caseId").asText());

    String caseId = first.body().get("caseId").asText();

    assertThat(db.count("select count(*) from enforcement_case where case_id = ?", caseId))
        .isEqualTo(1);

    assertThat(db.count("select count(*) from event_outbox where aggregate_id = ?", caseId))
        .isEqualTo(1);
}

@Testcontainers
abstract class PostgresIntegrationTest {

    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:17")
        .withDatabaseName("case_platform")
        .withUsername("case_app")
        .withPassword("case_app_pw");

    static DataSource dataSource;

    @BeforeAll
    static void startDatabase() {
        dataSource = DataSources.hikari(
            postgres.getJdbcUrl(),
            postgres.getUsername(),
            postgres.getPassword()
        );

        MigrationRunner.run(dataSource, "db/migration");
    }
}

@Testcontainers
abstract class PlatformIntegrationTest {

    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:17");

    @Container
    static KafkaContainer kafka = new KafkaContainer(
        DockerImageName.parse("apache/kafka-native:3.9.0")
    );

    @BeforeAll
    static void boot() {
        TestRuntimeConfig config = TestRuntimeConfig.builder()
            .jdbcUrl(postgres.getJdbcUrl())
            .kafkaBootstrapServers(kafka.getBootstrapServers())
            .build();

        PlatformTestApp.start(config);
    }
}

select lifecycle_status
from enforcement_case
where case_id = :case_id;

select count(*)
from case_audit_log
where case_id = :case_id
  and action_code = 'CASE_ACCEPTED';

select event_type, aggregate_id, publish_status
from event_outbox
where aggregate_id = :case_id;

select idem_status, response_status
from idempotency_record
where idempotency_key = :key;

A case is created with lifecycle_status = INTAKE_ACCEPTED.

The row happens to be physically inserted before the audit row.

@Test
void createCase_writesCaseAcceptedOutboxEvent() {
    ApiResponse response = api.postJson("/cases", newIdemKey(), validCreateCaseRequest());
    String caseId = response.body().get("caseId").asText();

    OutboxRow event = outboxRepository.findByAggregateId(caseId).single();

    assertThat(event.eventType()).isEqualTo("case.accepted.v1");
    assertThat(event.aggregateType()).isEqualTo("case");
    assertThat(event.aggregateId()).isEqualTo(caseId);
    assertThat(event.partitionKey()).isEqualTo(caseId);
    assertThat(event.payload().at("/caseId").asText()).isEqualTo(caseId);
    assertThat(event.publishStatus()).isEqualTo("PENDING");
}

@Test
void outboxPublisher_publishesCaseAcceptedEventToKafka() {
    String caseId = createCaseThroughApi();

    outboxPublisher.drainOnce();

    ConsumerRecord<String, String> record = kafkaTestConsumer.readOne("case.events.v1");

    assertThat(record.key()).isEqualTo(caseId);

    JsonNode event = Json.parse(record.value());
    assertThat(event.get("eventType").asText()).isEqualTo("case.accepted.v1");
    assertThat(event.get("correlationId").asText()).isNotBlank();
}

@Test
void getCase_whenOfficerOutsideJurisdiction_returns403EvenIfCaseExists() {
    CaseId caseId = fixture.createCase(jurisdiction("WEST"));
    TestPrincipal officer = fixture.officerWithJurisdiction("EAST");

    ApiResponse response = api.get(
        "/cases/" + caseId.value(),
        authHeaders(officer)
    );

    assertThat(response.status()).isEqualTo(403);
    assertThat(response.problemCode()).isEqualTo("AUTHZ.CASE_SCOPE_DENIED");
}

@Test
void getCase_whenCaseDoesNotExist_returns404() {
    TestPrincipal officer = fixture.officerWithJurisdiction("WEST");

    ApiResponse response = api.get(
        "/cases/case_missing",
        authHeaders(officer)
    );

    assertThat(response.status()).isEqualTo(404);
}

@Test
void createCase_concurrentDuplicateExternalReference_createsOnlyOneCase() throws Exception {
    JsonNode request = validCreateCaseRequestWithExternalRef("ext-777");

    ExecutorService executor = Executors.newFixedThreadPool(8);
    CountDownLatch start = new CountDownLatch(1);

    List<Callable<ApiResponse>> calls = IntStream.range(0, 8)
        .mapToObj(i -> (Callable<ApiResponse>) () -> {
            start.await();
            return api.postJson("/cases", "idem-" + i, request);
        })
        .toList();

    List<Future<ApiResponse>> futures = calls.stream()
        .map(executor::submit)
        .toList();

    start.countDown();

    List<ApiResponse> responses = futures.stream()
        .map(TestFutures::getUnchecked)
        .toList();

    long accepted = responses.stream().filter(r -> r.status() == 202).count();
    long conflicts = responses.stream().filter(r -> r.status() == 409).count();

    assertThat(accepted).isEqualTo(1);
    assertThat(conflicts).isEqualTo(7);

    assertThat(db.count("select count(*) from enforcement_case where external_ref = ?", "ext-777"))
        .isEqualTo(1);
}

@Test
void searchCases_filtersByLifecycleStatusAndJurisdiction() {
    fixture.createCase(status("UNDER_INVESTIGATION"), jurisdiction("WEST"));
    fixture.createCase(status("CLOSED"), jurisdiction("WEST"));
    fixture.createCase(status("UNDER_INVESTIGATION"), jurisdiction("EAST"));

    TestPrincipal westOfficer = fixture.officerWithJurisdiction("WEST");

    ApiResponse response = api.get(
        "/cases?status=UNDER_INVESTIGATION&pageSize=20",
        authHeaders(westOfficer)
    );

    assertThat(response.status()).isEqualTo(200);
    assertThat(response.body().get("items")).hasSize(1);
    assertThat(response.body().at("/items/0/status").asText()).isEqualTo("UNDER_INVESTIGATION");
}

Map<String, Object> payload = new HashMap<>();
payload.put("a", "x");
payload.put("b", "y");
payload.put("c", "z");

JsonNode request = CaseRequests.validComplaint()
    .withSubjectExternalRef("subject-123")
    .withAllegationType("UNLICENSED_OPERATION")
    .withIncidentDate(LocalDate.parse("2026-03-01"))
    .buildJson();

final class CaseRequestFixture {
    private String subjectExternalRef = "subject-default";
    private String allegationType = "UNLICENSED_OPERATION";
    private LocalDate incidentDate = LocalDate.parse("2026-03-01");

    CaseRequestFixture withSubjectExternalRef(String value) {
        this.subjectExternalRef = value;
        return this;
    }

    CaseRequestFixture withAllegationType(String value) {
        this.allegationType = value;
        return this;
    }

    JsonNode buildJson() {
        return Json.object()
            .putObject("subject")
                .put("externalRef", subjectExternalRef)
                .parent()
            .put("allegationType", allegationType)
            .put("incidentDate", incidentDate.toString())
            .build();
    }
}

One PostgreSQL container per test class or suite.
Apply migrations once.
Each test creates unique external refs / case IDs.
Clean tables between tests for synchronous data.
Avoid async publisher unless the test is explicitly about publishing.

truncate table
    event_outbox,
    event_inbox,
    case_audit_log,
    case_assignment,
    case_evidence,
    enforcement_case,
    idempotency_record
restart identity cascade;

alter table enforcement_case
add constraint uq_case_external_ref unique (source_system, external_ref);

@Test
void createCase_duplicateExternalReference_returnsConflictProblem() {
    fixture.createCase(source("PORTAL"), externalRef("ext-123"));

    ApiResponse response = api.postJson(
        "/cases",
        newIdemKey(),
        validCreateCaseRequestWithExternalRef("PORTAL", "ext-123")
    );

    assertThat(response.status()).isEqualTo(409);
    assertThat(response.problemCode()).isEqualTo("CASE.EXTERNAL_REF_ALREADY_EXISTS");
}

@Test
void requestWithoutCorrelationId_generatesCorrelationId() {
    ApiResponse response = api.postJson("/cases", newIdemKey(), validCreateCaseRequest());

    assertThat(response.header("X-Correlation-Id")).isNotBlank();
}

@Test
void requestWithCorrelationId_echoesCorrelationId() {
    ApiResponse response = api.postJson(
        "/cases",
        Map.of(
            "Idempotency-Key", newIdemKey(),
            "X-Correlation-Id", "corr-test-123"
        ),
        validCreateCaseRequest()
    );

    assertThat(response.header("X-Correlation-Id")).isEqualTo("corr-test-123");
}

@Test
void validationProblem_includesCorrelationId() {
    ApiResponse response = api.postJson(
        "/cases",
        Map.of("X-Correlation-Id", "corr-validation-1"),
        Json.object().build()
    );

    assertThat(response.status()).isEqualTo(400);
    assertThat(response.body().get("correlationId").asText())
        .isEqualTo("corr-validation-1");
}

@Test
void createCase_whenUseCaseTimesOut_returns503Problem() {
    createCaseUseCase.nextResult = CreateCaseResult.temporaryUnavailable("db-timeout");

    Response response = target("/cases")
        .request()
        .header("Idempotency-Key", "idem-timeout")
        .post(Entity.json(validCreateCaseRequest()));

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

    JsonNode problem = response.readEntity(JsonNode.class);
    assertThat(problem.get("code").asText()).isEqualTo("INFRA.TEMPORARILY_UNAVAILABLE");
}

contracts/releases/case-command-api-1.4.0.yaml
contracts/openapi/case-command-api.yaml

current contract must be backward compatible with latest released contract
unless the version policy explicitly allows a breaking major change

@Test
void createCase_oldMinimalRequestStillAccepted() {
    JsonNode oldClientPayload = Json.read(
        "contracts/compat/v1_4/create-case-minimal-request.json"
    );

    ApiResponse response = api.postJson("/cases", newIdemKey(), oldClientPayload);

    assertThat(response.status()).isEqualTo(202);
}

API creates case and outbox event.

worker consumes event and starts/correlates process.

API creates case and process instance reference.

validate
  - check OpenAPI syntax
  - lint contracts
  - run compatibility diff

generate-sources
  - generate JAX-RS interfaces and DTOs
  - generate event model if used

compile
  - compile production code

test
  - unit tests
  - resource boundary tests
  - mapper tests where fast enough

verify
  - integration tests with Testcontainers
  - OpenAPI response contract tests
  - idempotency/concurrency selected tests

*Test.java       -> unit/resource tests during test phase
*IT.java         -> integration tests during verify phase
*ContractIT.java -> contract-backed runtime integration tests

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-plugin</artifactId>
  <configuration>
    <includes>
      <include>**/*Test.java</include>
    </includes>
  </configuration>
</plugin>

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-failsafe-plugin</artifactId>
  <configuration>
    <includes>
      <include>**/*IT.java</include>
      <include>**/*ContractIT.java</include>
    </includes>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>integration-test</goal>
        <goal>verify</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Every domain rule is only tested by POSTing JSON to Jersey.

OpenAPI defines the external promise.
Jersey implements the transport adapter.
Application service enforces use-case behavior.
PostgreSQL enforces durable invariants.
Outbox records event obligations.
Kafka tests prove publication behavior.
Problem Details makes failures contract-visible.
Maven makes all of this repeatable.