Client only jar

[xenoterracide]

Given that as mentioned in other tickets we only consume graphql endpoints, we'd like to have a client only jar so that we don't risk accidentally exposing our own graphql endpoint and don't have server side auto-configurations trying to do things.

[bclozel]

I'm not sure I understand. Are you shipping a GraphQL schema with your application? Why would trigger a server auto-configuration? This is also less likely to happen with Spring Boot 4 because of spring-projects/spring-boot#46071.

[xenoterracide]

Summary

We’re running into issues using DGS in a client-only context. It appears
most assumptions are made around a server-first model, and that’s causing
problems for testing and configuration when we just want to consume a GraphQL
API.

What We’re Doing

We’re generating our schema into:

src/main/resources/schema.graphqls

This location should avoid triggering auto-configuration, but given DGS
Codegen’s default lookup behavior, it feels brittle—we’re one careless refactor
away from breaking things unintentionally.

Core Problem

We want to build and test a client against a GraphQL API without running a
full server. But:

• Test slices (e.g. @GraphQlTest) don’t work, they load all Controllers not just graphql
• There's no clear support for running the client in isolation.
• Mocks (e.g. with Mockito) are brittle and often don’t reflect real behavior.
• Request to reopen as there's no way to update server responses for many fake stateful requests Add utility for testing components that use GraphQlClient #1144 (comment)
• Increased jar bloat and security risk due to server side coupling.

It feels like client-only support is a second-class citizen or not fully
accounted for. We’d like to treat the client as a first-class unit that can be
tested independently—ideally in something like a Spring MVC mock context.

Example

class AccountRepository {
   private final HttpGraphQlClient client;

   public Account findById(AccountId id) {
      // invoke client, map response, return Account
   }
}

class AccountRepositoryTest {
   AccountRepository repo;

   @Test
   void findById() {
      repo.findById(myId);
      // assertions
   }
}

We tried @GraphQlTest, but it didn’t help. In fact it made it worse. We only have @RestControllers and it tried to load all of those. Our only workaround so far is mocking the HttpGraphQlClient , but this loses fidelity and makes tests fragile.

[bclozel]

We’re running into issues using DGS in a client-only context. It appears
most assumptions are made around a server-first model, and that’s causing
problems for testing and configuration when we just want to consume a GraphQL
API.

This will be solved with Spring Boot 4, because you can get the spring-graphql dependency and not depend on the spring-boot-graphql Spring Boot module. You can then use the client without the server auto-configuration being involved.

Test slices (e.g. @GraphQlTest) don’t work, they load all Controllers not just graphql

You can select a subset of controllers and run tests without a server. You don't need all controllers to be involved.

• There's no clear support for running the client in isolation.
• Mocks (e.g. with Mockito) are brittle and often don’t reflect real behavior.
• Request to reopen as there's no way to update server responses for many fake stateful requests Add utility for testing components that use GraphQlClient #1144 (comment)

I think this part has been discussed already quite a bit in #1144. There are already several tools available and they all have different tradeoffs. It's up to you to choose the one that fits best your case:

• testing one or more controllers without a live server: @GraphQlTest
• testing the complete stack including the transport layer, @SpringBootTest and @AutoConfigureHttpGraphQlTester
• testing the client itself as the application itself does not implement a server, then using a mock server is possible (see updated guidelines, but as Rossen pointed out already, this can be challenging because field selection is very flexible and you would need to have lots of sample payloads for that.

It feels like client-only support is a second-class citizen or not fully
accounted for. We’d like to treat the client as a first-class unit that can be
tested independently—ideally in something like a Spring MVC mock context.

The situation is actually quite comparable to what we have and recommend for RestTemplate. We have (updated our client testing guidelines to reflect that.

We tried @GraphQlTest, but it didn’t help. In fact it made it worse. We only have @RestControllers and it tried to load all of those. Our only workaround so far is mocking the HttpGraphQlClient , but this loses fidelity and makes tests fragile.

As usual, it seems this issues mixes different use cases. Your issue asks for testing a client in isolation without a server running, and here @GraphQlTest is designed to test a server; this means that your application does implement a GraphQL API.

I'm closing this issue as it's mainly superseded and solved in Spring Boot 4 with the modularization of the auto-configuration. The new spring-boot-graphql module only contains server auto-configuration as we don't ship any client auto-configuration.

[xenoterracide]

The situation is actually quite comparable to what we have and recommend for RestTemplate. We have (updated our client testing guidelines to reflect that.

We have wiremock for testing our feign clients. It's a terrible fit for graphql. One of the big things with testing a client in graphql would be testing the queries. Also graphql returns more dynamic json. It's kind of like suggesting that a CSV is a good replica for SQL queries.

I don't need to test the HTTP protocol which of course is we probably discussed graphql doesn't actually care about. I need to test that the queries can be responded to in a sane fashion.

At a glance I'm guessing the okHTTP server has the same problem.

[bclozel]

We have wiremock for testing our feign clients. It's a terrible fit for graphql. One of the big things with testing a client in graphql would be testing the queries. Also graphql returns more dynamic json. It's kind of like suggesting that a CSV is a good replica for SQL queries.

We've basically reached the same conclusions as in #1144.

I don't need to test the HTTP protocol which of course is we probably discussed graphql doesn't actually care about. I need to test that the queries can be responded to in a sane fashion.

At a glance I'm guessing the okHTTP server has the same problem.

Then the GraphQlTester, on a controller-by-controller basis, without involving any transport is the best way to solve this. In this case, you are indeed testing the server, not the client.

[xenoterracide]

Then the GraphQlTester, on a controller-by-controller basis, without involving any transport is the best way to solve this. In this case, you are indeed testing the server, not the client.

If I'm testing a spring data repository against H2. Am I testing the server or the client? Why would I choose to test the spring data repository at all instead of just mocking it with mockito? Graphql is my database. I still have repositories that are wrapping my graphql client. I need to ensure that the graphql being sent would function against a real graphql server. I cannot rely on the real graphql servers to be working in our CI environment or even be available for that matter. So I need some way to stub their behavior in tests in the same way that we would use test slices for data jpa. So while I do not need to test the HTTP part of this implementation, I need something that can fulfill that contract, in the same way that I assume that an embedded H2 behaves from a client perspective to be a network SQL server.

A closer analogy is I don't need to stand up postgresql to ensure that our client wrote valid select * From table; instead of seeect * From table; and of course using H2 would not ensure that the correct jdbc or even hibernate drivers were going to be used in production but they would prevent that typo.

And yes we are talking about multiple issues here. I am happy to say that we could reopen the testing ticket and open other tickets to make sure that we are only talking about one issue in any given ticket. My opinion is that having client only jars helps with the testing issue and helps with potential production issues. It may in fact be rational to say that the increased modularization of spring boot will actually help with this although I do think that having one jar still for spring graphql Is not modular enough for spring graphql. So if you want to reopen the testing ticket.... And and if I should then open other tickets we can do that...