Testing Feign Clients in Spring Boot (The Practical Guide)

Why Testing Feign Clients Is Challenging

Spring Cloud OpenFeign simplifies HTTP client development by generating implementations from annotated interfaces. This allows developers to focus on API contracts instead of low-level HTTP logic.

However, testing Feign clients introduces complexity because Feign relies on real HTTP communication configured through Spring properties and runtime proxy generation.

Common Testing Pitfalls

• Mocking the Interface: Using @MockBean bypasses the entire HTTP stack. This prevents validation of request mappings, headers, serialization, and parameter formatting.
• Manual HTTP Simulation: Tools such as WireMock allow full control over responses but require manual stub maintenance and configuration to redirect Feign clients to mock endpoints.

Record-Replay Testing for Feign Clients

Record-replay testing captures real HTTP traffic and reuses it during later test runs.

StableMock enables this workflow by recording HTTP requests generated by Feign clients during integration tests.

StableMock does not mock Feign itself. Instead, it intercepts outgoing HTTP calls by routing them through a proxy server and recording real responses as WireMock-compatible stubs.

How StableMock Integrates with Feign

1. StableMock starts a WireMock proxy during test initialization.
2. Spring configuration properties are overridden to redirect Feign client base URLs to the proxy.
3. Feign sends real HTTP requests to the proxy.
4. StableMock records responses and stores them as reusable stubs.

Example Spring Boot Test

@SpringBootTest
@U(
  urls = { "https://external-service.com" },
  properties = { "my-service.url" }
)
class FeignClientTest extends BaseStableMockTest {

  @Autowired
  private MyFeignClient feignClient;

  @DynamicPropertySource
  static void configure(DynamicPropertyRegistry registry) {
    autoRegisterProperties(registry, FeignClientTest.class);
  }

  @Test
  void testGetProduct() {
    Product p = feignClient.getProduct("123");
    assertEquals("Laptop", p.getName());
  }
  }
}

When Record-Replay Testing Works Well with Feign

Record-replay testing is particularly effective for Feign clients because Feign relies heavily on runtime configuration and property-driven URL resolution.

• When Feign clients target existing services with stable API contracts
• When you want to validate that Feign request mappings, headers, and serialization match real API behavior
• When you want integration tests that run offline while preserving real request/response structure
• When Feign base URLs are configured through Spring properties that can be overridden during tests

When Simulation-Based Testing May Be Preferable

Manual simulation tools such as WireMock may be more suitable when Feign clients are being developed before the target API exists or when specific error scenarios must be modeled manually.

• Designing Feign interfaces before backend services are implemented
• Testing fallback logic with controlled failure responses
• Simulating latency or network behavior that cannot be reproduced through recorded traffic

Why This Workflow Fits Feign Architecture

Feign resolves service URLs through Spring configuration. StableMock automatically overrides these properties during tests, allowing Feign clients to communicate with the proxy server without modifying production configuration.