This part does not assume CSG uses Testcontainers, Docker-in-Docker, localstack,
embedded Kafka, WireMock, MockServer, REST Assured, JerseyTest, Maven Failsafe,
or any specific CI container runtime.

Treat all integration testing frameworks, CI execution model, container images,
internal test environments, migration tools, and messaging test harnesses as
internal verification items.

wrong wiring
wrong provider registration
wrong object mapper
wrong database migration
wrong SQL behavior
wrong transaction boundary
wrong Kafka commit strategy
wrong Redis TTL behavior
wrong external HTTP error mapping
wrong container/runtime config

Which boundary risk are we proving?

Can we run everything in Docker?

SQL syntax actually works
index/query plan is acceptable
transaction isolation behaves as expected
deadlock/lock timeout behavior
migration applies cleanly
JSON provider registered in runtime
JAX-RS filter order in runtime
Kafka producer config works
Kafka consumer commit behavior works
Redis TTL and atomic command behavior
HTTP client timeout/error mapping with real wire behavior
container memory/startup/probe behavior

static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16")
    .withDatabaseName("quote_test")
    .withUsername("quote")
    .withPassword("quote");

String jdbcUrl = postgres.getJdbcUrl();
String username = postgres.getUsername();
String password = postgres.getPassword();

Use real infrastructure behavior where correctness depends on it.
Keep test scope narrow enough to stay debuggable.

container startup failure
migration failure
wiring failure
test data failure
behavior failure
cleanup/isolation failure
CI resource failure

SQL syntax
mapper result mapping
constraint behavior
transaction boundary
unique key violation handling
foreign key behavior
JSONB query behavior
locking behavior
pagination query correctness
migration-created schema compatibility

class QuoteRepositoryIT {
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16");

    QuoteRepository repository;

    @BeforeAll
    static void startDatabase() {
        postgres.start();
        runMigrations(postgres.getJdbcUrl(), postgres.getUsername(), postgres.getPassword());
    }

    @BeforeEach
    void setUp() {
        repository = new MyBatisQuoteRepository(testSqlSessionFactory(postgres));
        truncateTables();
    }

    @Test
    void shouldPersistAndLoadQuote() {
        Quote quote = Quote.draft("q-1", "tenant-a");

        repository.save(quote);

        Optional<Quote> loaded = repository.findById("tenant-a", "q-1");

        assertThat(loaded).contains(quote);
    }
}

schema exists
SQL insert works
SQL select works
mapping works
tenant condition works

Can schema be created from scratch?
Can existing schema be upgraded?
Are migrations ordered correctly?
Are checksums stable?
Are repeatable migrations safe?
Do application queries work after migration?
Can expand-contract rollout be simulated?

empty database -> apply all migrations -> application starts -> smoke query passes

old schema + old data -> apply new migration -> new app can read/write -> compatibility preserved

new schema must support old app version during rollout
old schema must not be required after new app deploy unless sequence guarantees it

migration N adds new nullable column/table without breaking old app
new app can write old and new shape if required
backfill is idempotent
read path works with old and new rows
contract migration only runs after all old readers/writers are gone

Can this migration run while old pods are still serving traffic?

mapper XML loads
parameter binding works
result mapping works
nested result mapping works
dynamic SQL produces valid SQL
SQL injection-safe binding is used
PostgreSQL-specific types map correctly
SQLState/error handling is correct

@Test
void shouldSearchQuotesUsingDynamicFilters() {
    insertQuote("tenant-a", "q-1", "DRAFT");
    insertQuote("tenant-a", "q-2", "SUBMITTED");
    insertQuote("tenant-b", "q-3", "DRAFT");

    List<QuoteRow> rows = mapper.searchQuotes(
        new QuoteSearchCriteria("tenant-a", "DRAFT", 50, null)
    );

    assertThat(rows).extracting(QuoteRow::quoteId).containsExactly("q-1");
}

unique idempotency key prevents duplicate command
row lock serializes state transition
lock timeout is mapped to retryable/non-retryable error
concurrent submit does not double-publish event

@Test
void shouldAllowOnlyOneConcurrentSubmit() throws Exception {
    insertDraftQuote("tenant-a", "q-1");

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

    Future<Result> first = executor.submit(() -> submitAfter(start, "q-1"));
    Future<Result> second = executor.submit(() -> submitAfter(start, "q-1"));

    start.countDown();

    List<Result> results = List.of(first.get(), second.get());

    assertThat(results).extracting(Result::status)
        .containsExactlyInAnyOrder("SUBMITTED", "CONFLICT");

    assertThat(countSubmittedEvents("q-1")).isEqualTo(1);
}

resources are registered
providers are registered
filters execute in expected order
ExceptionMapper works
JSON provider is production-like
validation is active
DI wiring works
configuration is loaded
health endpoint works

Test bootstrap should not silently use a different provider/filter/config setup
from production bootstrap.

200 success response
400 mapped to domain/client error
404 mapped to not found or empty result
409 mapped to conflict
429 mapped to retry/backoff behavior
500 mapped to downstream technical error
timeout
malformed JSON
large streaming response
unexpected content type

@Test
void shouldMapDownstreamTimeoutToRetryableIntegrationError() {
    mockServer.stubFor(get("/catalog/products/p-1")
        .willReturn(aResponse().withFixedDelay(5_000)));

    CatalogClient client = new CatalogClient(baseUrl, timeoutMillis(100));

    assertThatThrownBy(() -> client.getProduct("p-1"))
        .isInstanceOf(RetryableIntegrationException.class)
        .hasMessageContaining("catalog timeout");
}

producer sends to correct topic
key is correct
headers include trace/correlation/tenant context
schema serialization works
consumer receives and processes message
offset commit occurs after successful processing
failed processing does not commit incorrectly
DLQ/retry path works
idempotency prevents duplicate processing

@Test
void shouldPublishQuoteSubmittedEventWithQuoteIdAsKey() {
    submitQuote("tenant-a", "q-1");

    ConsumerRecord<String, byte[]> record = readOne("quote.events");

    assertThat(record.key()).isEqualTo("q-1");
    assertThat(record.headers().lastHeader("tenant-id").value())
        .isEqualTo(bytes("tenant-a"));

    QuoteSubmitted event = deserialize(record.value());
    assertThat(event.quoteId()).isEqualTo("q-1");
}

valid event updates state
duplicate event is ignored safely
invalid event goes to DLQ or error path
technical failure is retried
poison message does not block partition forever
consumer commits only after successful processing
context headers are propagated into logs/traces

@Test
void shouldIgnoreDuplicateQuoteSubmittedEvent() {
    QuoteSubmitted event = new QuoteSubmitted("tenant-a", "q-1", "event-1");

    produce("quote.events", "q-1", event);
    produce("quote.events", "q-1", event);

    await().untilAsserted(() -> {
        assertThat(repository.countProcessedEvent("event-1")).isEqualTo(1);
        assertThat(repository.findQuote("tenant-a", "q-1").status()).isEqualTo("SUBMITTED");
    });
}

producer serializes event using registered schema
consumer deserializes event using expected schema
unknown optional field does not break consumer
missing required field is rejected intentionally

test registry strategy
compatibility mode in CI
local registry container
mock registry support
schema subject naming convention

cache TTL expires
cache-aside fallback works
idempotency key is set atomically
lock release does not delete another client's lock
rate limiter increments atomically
stream consumer acknowledges only after success

@Test
void shouldExpireIdempotencyKeyAfterTtl() {
    idempotencyStore.save("tenant-a", "key-1", response, Duration.ofSeconds(1));

    assertThat(idempotencyStore.find("tenant-a", "key-1")).isPresent();

    await().atMost(Duration.ofSeconds(3)).untilAsserted(() ->
        assertThat(idempotencyStore.find("tenant-a", "key-1")).isEmpty()
    );
}

HTTP POST /quotes
-> validation
-> service
-> PostgreSQL transaction
-> outbox insert
-> response 201
-> outbox publisher emits Kafka event

response status is correct
response body/header correct
row exists in database
audit/outbox row exists
Kafka event emitted with correct key/header/schema
correlation ID preserved

truncate tables before each test
use unique tenant/test IDs
use transaction rollback where applicable
recreate schema for class/suite
use isolated Kafka topic per test class
use unique consumer group per test
flush Redis before each test

same Kafka topic
same consumer group
same DB rows
same Redis keys
same mock server paths
same static configuration
same port binding
shared global clock

String testRunId = UUID.randomUUID().toString();
String tenantId = "tenant-it-" + testRunId;
String topic = "quote.events." + testRunId;
String consumerGroup = "quote-consumer-it-" + testRunId;

Docker availability
container runtime policy
network access
image pull policy
registry authentication
resource limits
parallelism
test timeout
log capture
container reuse policy
security restrictions

image pull rate limit
slow container startup
test timeout too short
port collision
insufficient memory
Kafka readiness race
database still starting when migration runs
container logs not captured

application logs
container logs
database state
migration output
Kafka topic records
consumer group offsets
Redis keys/TTL
mock server requests
HTTP request/response payloads
trace/correlation IDs

Did container start successfully?
Did migrations run?
Did app use container connection string?
Did test data insert succeed?
Did request reach resource method?
Did transaction commit?
Did Kafka event publish?
Did consumer receive and commit?
Did cleanup delete needed state too early?

Thread.sleep
fixed ports
shared mutable state
real external services
assumed test order
unbounded async waits
very short TTLs
timing-sensitive assertions without await

await().untilAsserted(...)
unique IDs
container readiness checks
explicit cleanup
fixed Clock for business time
bounded timeouts
captured logs

fast integration subset for PR
full integration suite for main branch/nightly
migration compatibility suite for release branch
performance smoke for release candidate

# fast unit tests
./mvnw test

# integration tests
./mvnw verify -Pintegration

# specific integration test
./mvnw -Dtest=QuoteRepositoryIT verify

simple getters/setters
pure mapping already unit-tested
every validation annotation individually
internal branch not crossing a boundary
framework behavior already covered elsewhere

What boundary risk does this test prove?
Could this be a unit test instead?
Does it use real dependency behavior where needed?
Are migrations applied exactly as production would apply them?
Is data cleanup explicit?
Is the test deterministic?
Does it avoid fixed sleeps?
Does it use unique IDs/topics/groups/keys where needed?
Are container versions intentional?
Are logs available when test fails?
Are negative/failure scenarios included?
Does CI have enough resource/time for it?
Does the test protect a production-relevant failure mode?

integration test with only mocked dependencies
test passes without asserting side effects
shared Kafka consumer group across tests
real shared dev database used by automated tests
migration not run before repository test
hardcoded local port
Thread.sleep for async event processing
no cleanup
no negative path

Is Testcontainers approved and used?
Which version and container images are standard?
Is Docker available in CI?
Are reusable containers allowed?
How are database migrations run in integration tests?
Is Flyway or Liquibase used?
Are migration tests required for DB changes?
Is PostgreSQL container version aligned with production?
Are MyBatis mappers integration-tested?
How are Kafka topics created in tests?
Is embedded Kafka used or container Kafka used?
How are schema registry tests handled?
How are Kafka consumer groups isolated?
How are Redis tests isolated?
Is WireMock, MockServer, or another HTTP mock standard?
How are cloud services mocked locally?
Are LocalStack/Azurite used, or are cloud calls abstracted?
Which tests run in PR vs nightly vs release?
What is the naming convention for IT tests?
Where are container logs stored in CI?
How are flaky tests tracked and quarantined?
What is the maximum acceptable integration test runtime?
Who owns integration test infrastructure?

Integration tests should prove boundary behavior.
Every slow test must justify its cost.
Every migration should be tested against representative data.
Every Kafka consumer must be tested for duplicate and failure behavior.
Every multi-tenant query should be tested for tenant isolation.
Every idempotency feature should be tested under repeat and concurrency.
Every test should be debuggable from logs and persisted evidence.

unit tests prove logic
endpoint tests prove HTTP/runtime boundary
integration tests prove real dependency behavior
migration tests prove deployability
Kafka/Redis tests prove distributed semantics
slice tests prove critical flows

This test is worth its runtime cost.
It catches a failure that unit tests cannot catch.
It uses realistic dependency behavior.
It is isolated, deterministic, and debuggable.
It increases production confidence.