Java Integration testing guidelines

Set up robust integration-test infrastructure for Java services using WireMock to stub outbound HTTP dependencies.

What is covered in this Skill?

• Infrastructure topology detection: scanning imports for HttpClient, feign.*, retrofit2.*, RestTemplate
• Abstract BaseIntegrationTest base class
• WireMockExtension with @RegisterExtension, dynamic port allocation (dynamicPort())
• usingFilesUnderClasspath(wiremock), @BeforeAll + System.setProperty() for coordinate propagation
• WireMock JSON mapping files (bodyFileName referencing wiremock/files/)
• Programmatic stub registration via WireMock DSL
• Per-test stub isolation: register stubs inside each test method
• Fault injection: 503 service unavailable, network latency with withFixedDelay
• Request verification via WIREMOCK.verify
• wiremock-standalone Maven dependency (test scope)
• Anti-patterns: global @BeforeAll stubs, Mockito-mocked HTTP clients, hardcoded ports or URLs

Scope: The reference is organized by examples (good/bad code patterns) for each core area. Apply recommendations based on applicable examples.

Constraints

Before applying any integration test changes, ensure the project compiles. If compilation fails, stop immediately — do not proceed until resolved. After applying improvements, run full verification.

• MANDATORY: Run ./mvnw compile or mvn compile before applying any change
• SAFETY: If compilation fails, stop immediately and do not proceed — compilation failure is a blocking condition
• VERIFY: Run ./mvnw clean verify or mvn clean verify after applying improvements
• BEFORE APPLYING: Read the reference for detailed examples, good/bad patterns, and constraints

When to use this skill

• Review Java code for integration tests
• Apply best practices for integration tests in Java code
• Write Java integration tests with real infrastructure boundaries
• Improve Testcontainers integration tests for Java code
• Review integration test setup and teardown in Java projects

Workflow

1. Compile project before integration-test changes

Run ./mvnw compile or mvn compile and stop immediately if compilation fails.

2. Read integration-testing reference and detect topology

Read references/132-java-testing-integration-testing.md and detect HTTP client and external dependency integration points.

3. Set up resilient integration-test infrastructure

Implement BaseIntegrationTest, WireMock mappings/stubs, per-test isolation, and verification patterns.

4. Verify with full build

Run ./mvnw clean verify or mvn clean verify after applying improvements.

Reference

For detailed guidance, examples, and constraints, see references/132-java-testing-integration-testing.md.