Support HTTP Interface Clients in Test Framework

[ZIRAKrezovic]

From: https://docs.spring.io/spring-framework/reference/integration/rest-clients.html#rest-http-service-client

[start quote]

On the server side, an @Controller class can implement the same interface to handle requests with @HttpExchange controller methods.

[end quote]

At the moment, there are WebTestClient and RestTestClient for REST Testing. However, it may be beneficial to use HTTP Interface clients for testing where WebTestClient and RestTestClient assertions are not needed.

At the moment, I see no way to instantiate HTTP Interface Clients and bind them to test Web Server in conjunction with SpringBootTest.WebEnvironment.RANDOM_PORT.

Would you be interested in providing any kind of support for using HTTP Interface Clients within Test Context?

At least consider providing HttpExchangeAdapter for WebTestClient and RestTestClient.

Thanks in advance.

[devareddy05]

Opened a PR for this: #36715

This change adds RestTestClientAdapter and WebTestClientAdapter, enabling an @HttpExchange interface to be invoked against a RestTestClient or WebTestClient, including support for mock-server setups. The reference documentation has also been updated with a short example.

Changes

• Introduced RestTestClientAdapter
• Introduced WebTestClientAdapter
• Enabled usage of @HttpExchange interfaces with both clients
• Updated reference docs with a usage example

[rstoyanchev]

If you're testing over a port, then you should be using RestClient or WebClient with the port set accordingly. Why is that an issue?

RestTestClient and WebTestClient are essentially the same as RestClient and WebClient except they expose a workflow for testing after the exchange, but if you don't need the assertions, there is no sense in using test clients which are meant to be used directly.

[ZIRAKrezovic]

If you're testing over a port, then you should be using RestClient or WebClient with the port set accordingly. Why is that an issue?

RestTestClient and WebTestClient are essentially the same as RestClient and WebClient except they expose a workflow for testing after the exchange, but if you don't need the assertions, there is no sense in using test clients which are meant to be used directly.

To quote myself

At the moment, I see no way to instantiate HTTP Interface Clients and bind them to test Web Server in conjunction with SpringBootTest.WebEnvironment.RANDOM_PORT.

Any hints, documentation or similar, are mostly welcome.

Edit: I don't see a way where I could do it painlessly. I could use @LocalServerPort in the test class itself, then build the right HttpExchangeAdapter and HttpServiceProxyFactory, and so forth. Doing so, I lose everything provided by Spring (Boot?) support for HTTP Interface Clients, where I only have to define an interface and register them via annotation. This is what I seek, but in absence of a solution I welcome any solution where I don't have to instantiate everything, and end up using completely different client infrastructure in tests than in production. Tests like these do not make much sense, and in that case I could simply use WebTestClient or RestTestClient.

Please do not think I ask specifically for WebTestClient or RestTestClient HttpExchangeAdapters - it's just that those are already bound to the correct server/port instance.

Edit 2: Base URL for HTTP Clients may be set via Environment (application.properties/yaml/config server/...) property, but I have yet to find out how to add a property using the @LocalServerPort value into Environment at the right stage of the application.

Using @DynamicPropertySource is not possible unless the annotation is present on a static method, but @LocalServerPort itself operates only on instance variables.

Wiremock (Spring Boot Integration), for example, gives the ability to inject its baseUrl into any environment property, which makes it easy to instantiate baseUrl for any HTTP Interface Client. Even that would be a solution I'd welcome, but I'm not sure if it's possible as the server depends on Environment being initialized.

[rstoyanchev]

That makes more sense when stated as a problem rather than a specific solution. It is more of a Boot question however. Let me find out a bit more and I'll come back to you.

[rstoyanchev]

Could you clarify how you set up HTTP Services in your application, e.g. do you use @ImportHttpServices config for example?

[krezovic]

Could you clarify how you set up HTTP Services in your application, e.g. do you use @ImportHttpServices config for example?

Hi,

Yes, I use @ImportHttpServices, as outlined in blog post https://spring.io/blog/2025/09/23/http-service-client-enhancements

[rstoyanchev]

Thanks. After some further thought, in order to make progress, I would like to take a further step back to understand more about the application and the test strategy.

I understand there is a live integration test of a server application given the random port. The application also seems to have a client side based on the @ImportHttpServices, but is that really in the same application, or how is that coming together in the same tests? What is the focus of testing, client or server logic? Are you loading the full application or parts of it?

[ZIRAKrezovic]

Hello, I can provide a code example come Monday, but for now this will have to do

• I write an interface with HTTP Client Annotations
• I write a REST Controller that implements the interface with HTTP Client Annotations, as this is supported
• I would like to instantiate a client in my test, which is a @SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT) (real web server) and use it to test the rest service
• At the moment, I use either RestTestClient or WebTestClient to achieve that. I am not sure if they are mapped by default to a real server or just an application context

I want to add that I have both HttpServiceArgumentResolver for client side and HandlerMethodArgumentResolver for server side to support using custom annotations/types on Rest Client / Rest Controller arguments.

[rstoyanchev]

For now a description is fine, no need for a code sample. However, you're describing the desired outcome rather than answering the questions.

It's still unclear if the HttpExchange interfaces are used as client proxies for testing purposes only, or also in the actual application at runtime as the use of @ImportHttpServices would imply, but in that case why would client proxies connect to a server within the same application?

I'm not making any judgement, just trying to understand the scenario because if we talk about supporting HTTP Service interfaces as client proxies for testing, such client proxies would typically connect to another application while the live port implies connecting to the same application.

Or perhaps you mean to use them for testing only within the server application, while another application would import and use the same interfaces as client proxies at runtime?