---
name: jabrena/132-java-testing-integration-testing
source: https://app.decimal.ai/s/jabrena-132-java-testing-integration-testing@1/SKILL.md
source_sha256: 8f4890adc3ad
---

# 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](references/132-java-testing-integration-testing.md).