132-java-testing-integration-testing
npx machina-cli add skill jabrena/cursor-rules-java/132-java-testing-integration-testing --openclawJava Integration testing guidelines
Set up robust integration-test infrastructure for Java services using WireMock to stub outbound HTTP dependencies.
Core areas: Infrastructure topology detection (scanning imports for HttpClient, feign.*, retrofit2.*, RestTemplate, etc.), abstract BaseIntegrationTest base class, WireMockExtension with @RegisterExtension, dynamic port allocation (dynamicPort()), usingFilesUnderClasspath("wiremock"), @BeforeAll + System.setProperty() for coordinate propagation, concrete test classes extending the base class, 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 (WIREMOCK.verify), wiremock-standalone Maven dependency (test scope), and anti-patterns (global @BeforeAll stubs causing order-dependent failures, Mockito-mocked HTTP clients bypassing the real HTTP pipeline, hardcoded ports or URLs in property files).
Prerequisites: Run ./mvnw compile or mvn compile before applying any change. If compilation fails, stop immediately and do not proceed — compilation failure is a blocking condition.
Multi-step scope: Step 1 scans class imports for HTTP client signals and confirms the integration topology with the user (REST → WireMock). Step 2 generates a tailored BaseIntegrationTest.java under src/test/java/{root-package}/ with WireMockExtension and @BeforeAll coordinate propagation, then lists required Maven dependencies. Step 3 generates starter WireMock JSON mapping files (one per confirmed external service) under src/test/resources/wiremock/mappings/{service-name}/.
Before applying changes: Read the reference for detailed examples, good/bad patterns, and constraints.
Reference
For detailed guidance, examples, and constraints, see references/132-java-integration-testing.md.
Source
git clone https://github.com/jabrena/cursor-rules-java/blob/main/skills/132-java-testing-integration-testing/SKILL.mdView on GitHub Overview
Set up robust integration-test infrastructure for Java services using WireMock to stub outbound HTTP dependencies. It guides you through topology detection, a reusable BaseIntegrationTest, and per-test stubs, while avoiding common anti-patterns like global stubs or Mockito HTTP mocks.
How This Skill Works
First, it analyzes code imports to detect HTTP clients and defines the integration topology. Then it generates a BaseIntegrationTest using WireMockExtension, dynamicPort, and coordinated properties, and supports per-test stub registration and request verification using WireMock DSL.
When to Use It
- When your Java service calls external HTTP dependencies and you need reliable, isolated stubs via WireMock.
- When migrating from Mockito-mocked HTTP clients to a real HTTP pipeline in tests.
- When you want per-test isolation of stubs to avoid cross-test pollution.
- When you rely on dynamic port allocation and coordinate propagation through System.setProperty.
- When you need starter WireMock JSON mappings (bodyFileName) and verification of outbound requests.
Quick Start
- Step 1: Scan your code imports for HTTP clients (HttpClient, Feign, RestTemplate, Retrofit) to confirm the topology (REST → WireMock).
- Step 2: Generate BaseIntegrationTest.java under src/test/java/{root-package}/ with WireMockExtension and @BeforeAll that propagates coordinates via System.setProperty(), and list needed Maven dependencies.
- Step 3: Create starter WireMock JSON mappings under src/test/resources/wiremock/mappings/{service-name}/ using bodyFileName to reference wiremock/files/.
Best Practices
- Register stubs inside each test method to ensure isolation.
- Prefer dynamicPort() and System.setProperty to avoid hard-coded ports.
- Use the WireMockExtension with @RegisterExtension and a shared BaseIntegrationTest abstraction.
- Store mapping files under src/test/resources/wiremock/mappings and reference with bodyFileName.
- Verify outbound HTTP interactions with WIREMOCK.verify and avoid global @BeforeAll stubs that cause order issues.
Example Use Cases
- Testing an OrderService that calls an external Payment API; WireMock mappings stub payments and verify request payloads.
- Testing an InventoryService using RestTemplate to call an Inventory API; per-test stubs ensure isolation.
- Testing a CatalogService that uses Feign client to reach a Product API; dynamic ports avoid clashes.
- Testing a ShippingService backed by Retrofit calls; inject latency with fixedDelay to simulate slow responses.
- Setting up a multi-service integration where a single BaseIntegrationTest drives all external dependencies with per-service mappings.
