java-setup-integration-tests

name	java-setup-integration-tests
description	Integration testing patterns for Java/Spring Boot services with Spock. Covers BaseIntegrationSpec setup, Testcontainers, mock frameworks, gRPC testing, REST controller testing, Kafka consumers, and GrpcMock for external services.
compatibility	Java services with Spring Boot and Spock
alwaysApply	false
metadata	{"version":"1.0.0","technology":"java","category":"testing","tags":["java","testing","integration-tests","spock","testcontainers","grpc","rest","kafka"]}

Java Integration Testing

Comprehensive integration testing patterns for Java/Spring Boot services using Spock Framework.

When to use this skill

• Setting up integration tests for a new service
• Migrating from unit tests to proper integration tests
• Choosing mock strategy: GrpcMock/WireMock (preferred) vs @MockitoBean/@SpringBean (ProtoShims only)
• Configuring Testcontainers (PostgreSQL, Valkey/Redis)
• Testing gRPC handlers or external gRPC clients
• Testing REST controllers with MockMvc
• Testing Kafka consumers with EmbeddedKafka

Skill Contents

Sections

• When to use this skill
• Quick Decision Tree
• Core Principles
• References
• Related Skills

Available Resources

📚 references/ - Detailed documentation

• base spec patterns
• container cleanup
• container reuse
• grpc handler testing
• grpcmock resilience
• grpcmock setup
• grpcmock stub helpers
• kafka testing
• migration workflow
• rest controller testing
• testcontainers setup

---

Quick Decision Tree

What are you testing?
│
├─► Your own gRPC handlers?
│   └─► Use [grpc-handler-testing.md](references/grpc-handler-testing.md)
│       (In-process transport, GrpcClientTestConfig)
│
├─► External gRPC clients (retries/timeouts)?
│   └─► Use [grpcmock-setup.md](references/grpcmock-setup.md)
│       (WireMock-like stubbing for gRPC)
│
├─► REST controllers?
│   └─► Use [rest-controller-testing.md](references/rest-controller-testing.md)
│       (MockMvc, @AutoConfigureMockMvc)
│
├─► Kafka consumers?
│   └─► Use [kafka-testing.md](references/kafka-testing.md)
│       (@EmbeddedKafka, KafkaTestUtils)
│
├─► Setting up BaseIntegrationSpec?
│   └─► Use [base-spec-patterns.md](references/base-spec-patterns.md)
│       (Mock framework choice, reset strategies)
│
└─► Configuring containers?
    └─► Use [testcontainers-setup.md](references/testcontainers-setup.md)
        (PostgreSQL jdbc:tc, Valkey)

Core Principles

The Golden Rules

Rule	Why
Real domain services	Tests should exercise actual business logic
Real repositories	Use Testcontainers for DB/cache
Prefer GrpcMock/WireMock for external services	Tests real client wrappers, resilience, error codes
Bean mocking only for ProtoShims/custom RPCs	Use @MockitoBean/@SpringBean only when GrpcMock/WireMock is not feasible
Reset mocks in setup()	Prevent test interference (@MockitoBean only)
Clean data in cleanup()	Ensure test isolation
No @DirtiesContext	Use proper cleanup instead
No @Transactional on tests	Let transactions commit to test real behavior
Static containers	Share across test classes for speed
Centralize config in BaseSpec	All test beans and mocks in base class

External Dependency Mocking Hierarchy

Always prefer the highest-fidelity mock available:

PREFER (most realistic)                    AVOID (least realistic)
─────────────────────────────────────────────────────────────────────
  GrpcMock          WireMock          @MockitoBean/@SpringBean
  (gRPC services)   (REST services)   (ONLY for ProtoShims/custom RPCs)

External Dependency Type	Mock Strategy	Why
Standard gRPC service	GrpcMock (always)	Tests real client wrapper, retry logic, error codes, timeouts
Standard REST service	WireMock (always)	Tests real HTTP client, error handling, serialization
ProtoShim / custom RPC (e.g., UserModel, TradeModel)	@MockitoBean/@SpringBean	Custom protocols not directly testable via GrpcMock
Kafka producer	@MockitoBean/@SpringBean	No network mock available

Why GrpcMock/WireMock over bean mocking:

• Tests the real client wrapper code (serialization, error mapping, retries)
• Catches bugs in client configuration and resilience patterns
• More realistic - simulates actual network behavior
• Single GrpcMock server handles ALL external gRPC services

What to Mock vs Use Real

┌─────────────────────────────────────────────────────────────────────┐
│                        Test JVM Process                              │
│                                                                      │
│  ┌─────────────────┐     ┌─────────────────────────────────────┐    │
│  │ Test Code       │     │      Spring Boot Context            │    │
│  │                 │     │                                     │    │
│  │ Direct API call │ ──► │  Handler / Controller               │    │
│  │ (stub or HTTP)  │     │         │                           │    │
│  │                 │     │         ▼                           │    │
│  │                 │     │  ┌─────────────────────┐            │    │
│  │                 │     │  │   Domain Service    │            │    │
│  │                 │     │  │   (REAL impl)       │            │    │
│  │                 │     │  │         │           │            │    │
│  │                 │     │  │    ┌────┴────┐      │            │    │
│  │                 │     │  │    ▼         ▼      │            │    │
│  │                 │     │  │ Repository  Cache   │            │    │
│  │                 │     │  │ (REAL)     (REAL)   │            │    │
│  │                 │     │  └─────────────────────┘            │    │
│  │                 │     │                                     │    │
│  │  GrpcMock/      │     │  gRPC Client ──────► GrpcMock      │    │
│  │  WireMock       │     │  (REAL wrapper)      Server        │    │
│  │  (preferred)    │     │                                     │    │
│  │                 │     │  REST Client ──────► WireMock       │    │
│  │  @SpringBean    │     │  (REAL wrapper)      Server        │    │
│  │  (ProtoShims    │     │                                     │    │
│  │   only)         │     │  ProtoShim ◄──── @SpringBean MOCK  │    │
│  │                 │     │  (custom RPC)                       │    │
│  └─────────────────┘     └─────────────────────────────────────┘    │
│                                                                      │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐     │
│  │   PostgreSQL    │  │     Valkey      │  │     Kafka       │     │
│  │  Testcontainer  │  │  Testcontainer  │  │  EmbeddedKafka  │     │
│  │  (if needed)    │  │  (if needed)    │  │  (if needed)    │     │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘     │
└─────────────────────────────────────────────────────────────────────┘

Mock Framework Choice

When bean mocking IS needed (ProtoShims/custom RPCs only):

Approach	Annotation	Mock Syntax	Verification	Reset Needed
Mockito	@MockitoBean	when(mock.method()).thenReturn(value)	verify(mock).method()	Yes
Spock	@SpringBean	mock.method() >> value	1 * mock.method()	No

WARNING: You cannot mix syntaxes! With @MockitoBean, Spock's >> syntax will NOT work.

See base-spec-patterns.md for detailed examples.

---

References

Reference	Description
base-spec-patterns.md	BaseIntegrationSpec patterns with mock frameworks
testcontainers-setup.md	Container configuration patterns
grpc-handler-testing.md	Testing your own gRPC handlers
grpcmock-setup.md	GrpcMock for external services
rest-controller-testing.md	REST controller testing
kafka-testing.md	Kafka consumer testing

Related Skills

Skill	Purpose
java-testing	General testing guidelines
java-coverage	JaCoCo coverage setup
grpc-services-rfc-33	gRPC service standards