Spring for GraphQL Documentation

As a protocol GraphQL focuses on the exchange of textual data. This doesn’t include binary data such as images, but there is a separate, informal graphql-multipart-request-spec that allows file uploads with GraphQL over HTTP.

Spring for GraphQL does not support the graphql-multipart-request-spec directly. While the spec does provide the benefit of a unified GraphQL API, the actual experince has led to a number of issues, and best practice recommendations have evolved, see Apollo Server File Upload Best Practices for a more detailed discussion.

If you would like to use graphql-multipart-request-spec in your application, you can do so through the library multipart-spring-graphql.

HTTP and WebSocket transports invoke a chain of 0 or more WebGraphQlInterceptor, followed by an ExecutionGraphQlService that calls the GraphQL Java engine. WebGraphQlInterceptor allows an application to intercept incoming requests and do one of the following:

For example, an interceptor can pass an HTTP request header to a DataFetcher:

Reversely, an interceptor can access values added to the GraphQLContext by a controller:

WebGraphQlHandler can modify the ExecutionResult, for example, to inspect and modify request validation errors that are raised before execution begins and which cannot be handled with a DataFetcherExceptionResolver:

Use WebGraphQlHandler to configure the WebGraphQlInterceptor chain. This is supported by the Boot Starter, see Web Endpoints.

Similar to WebGraphQlInterceptor, an RSocketQlInterceptor allows intercepting GraphQL over RSocket requests before and after GraphQL Java engine execution. You can use this to customize the graphql.ExecutionInput and the graphql.ExecutionResult.

GraphQlSource.Builder can be configured with one or more Resource instances to be parsed and merged together. That means schema files can be loaded from just about any location.

By default, the Boot starter looks for schema files with extensions ".graphqls" or ".gqls" under the location classpath:graphql/**, which is typically src/main/resources/graphql. You can also use a file system location, or any location supported by the Spring Resource hierarchy, including a custom implementation that loads schema files from remote locations, from storage, or from memory.

By default, GraphQlSource.Builder uses the GraphQL Java SchemaGenerator to create the graphql.schema.GraphQLSchema. This works for typical use, but if you need to use a different generator, e.g. for federation, you can register a schemaFactory callback:

The GraphQlSource section explains how to configure that with Spring Boot.

For an example with Apollo Federation, see federation-jvm-spring-example.

You can use RuntimeWiringConfigurer to register:

The Boot Starter detects beans of type RuntimeWiringConfigurer and registers them in the GraphQlSource.Builder. That means in most cases, you’ll' have something like the following in your configuration:

If you need to add a WiringFactory, e.g. to make registrations that take into account schema definitions, implement the alternative configure method that accepts both the RuntimeWiring.Builder and an output List<WiringFactory>. This allows you to add any number of factories that are then invoked in sequence.

GraphQlSource.Builder registers ClassNameTypeResolver as the default TypeResolver to use for GraphQL Interfaces and Unions that don’t already have such a registration through a RuntimeWiringConfigurer. The purpose of a TypeResolver in GraphQL Java is to determine the GraphQL Object type for values returned from the DataFetcher for a GraphQL Interface or Union field.

ClassNameTypeResolver tries to match the simple class name of the value to a GraphQL Object Type and if it is not successful, it also navigates its super types including base classes and interfaces, looking for a match. ClassNameTypeResolver provides an option to configure a name extracting function along with Class to GraphQL Object type name mappings that should help to cover more corner cases:

The GraphQlSource section explains how to configure that with Spring Boot.

The GraphQL language supports directives that "describe alternate runtime execution and type validation behavior in a GraphQL document". Directives are similar to annotations in Java but declared on types, fields, fragments and operations in a GraphQL document.

GraphQL Java provides the SchemaDirectiveWiring contract to help applications detect and handle directives. For more details, see Schema Directives in the GraphQL Java documentation.

In Spring GraphQL you can register a SchemaDirectiveWiring through a RuntimeWiringConfigurer. The Boot Starter detects such beans, so you might have something like:

You can register a graphql.schema.GraphQLTypeVisitor via builder.schemaResources(..).typeVisitorsToTransformSchema(..) if you want to traverse and transform the schema after it is created, and make changes to the schema. Keep in mind that this is more expensive than Schema Traversal so generally prefer traversal to transformation unless you need to make schema changes.

You can register a graphql.schema.GraphQLTypeVisitor via builder.schemaResources(..).typeVisitors(..) if you want to traverse the schema after it is created, and possibly apply changes to the GraphQLCodeRegistry. Keep in mind, however, that such a visitor cannot change the schema. See Schema Transformation, if you need to make changes to the schema.

If a query, mutation, or subscription operation does not have a DataFetcher, it won’t return any data, and won’t do anything useful. Likewise, fields on schema types returned by an operation that are covered neither explicitly through a DataFetcher registration, nor implicitly by the default PropertyDataFetcher, which looks for a matching Java object property, will always be null.

GraphQL Java does not perform checks to ensure every schema field is covered, and that can result in gaps that might not be discovered depending on test coverage. At runtime you may get a "silent" null, or an error if the field is not nullable. As a lower level library, GraphQL Java simply does not know enough about DataFetcher implementations and their return types, and therefore can’t compare schema type structure against Java object structure.

Spring for GraphQL defines the SelfDescribingDataFetcher interface to allow a DataFetcher to expose return type information. All Spring DataFetcher implementations implement this interface. That includes those for Annotated Controllers, and those for Querydsl and Query by Example Spring Data repositories. For annotated controllers, the return type is derived from the declared return type on a @SchemaMapping method.

On startup, Spring for GraphQL can inspect schema fields, DataFetcher registrations, and the properties of Java objects returned from DataFetcher implementations to check if all schema fields are covered either by an explicitly registered DataFetcher, or a matching Java object property. The inspection also performs a reverse check looking for DataFetcher registrations against schema fields that don’t exist.

To enable inspection of schema mappings:

Below is an example report:

There are limits to what schema field inspection can do, in particular when there is insufficient Java type information. This is the case if an annotated controller method is declared to return java.lang.Object, or if the return type has an unspecified generic parameter such as List<?>, or if the DataFetcher does not implement SelfDescribingDataFetcher and the return type is not even known. In such cases, the Java object type structure remains unknown, and the schema type is listed as skipped in the resulting report. For every skipped type, a DEBUG message is logged to indicate why it was skipped.

Schema union types are always skipped because there is no way for a controller method to declare such a return type in Java, and the Java type structure is unknown.

Schema interface types are supported only as far as fields declared directly, which are compared against properties on the Java type declared by a SelfDescribingDataFetcher. Additional fields on concrete implementations are not inspected. This could be improved in a future release to also inspect schema interface implementation types and to try to find a match among subtypes of the declared Java return type.

GraphQL Java must parse and validate an operation before executing it. This may impact performance significantly. To avoid the need to re-parse and validate, an application may configure a PreparsedDocumentProvider that caches and reuses Document instances. The GraphQL Java docs provide more details on query caching through a PreparsedDocumentProvider.

In Spring GraphQL you can register a PreparsedDocumentProvider through GraphQlSource.Builder#configureGraphQl: .

The GraphQlSource section explains how to configure that with Spring Boot.

A DataFetcher and other components invoked by GraphQL Java may not always execute on the same thread as the Spring MVC handler, for example if an asynchronous WebGraphQlInterceptor or DataFetcher switches to a different thread.

Spring for GraphQL supports propagating ThreadLocal values from the Servlet container thread to the thread a DataFetcher and other components invoked by GraphQL Java to execute on. To do this, an application needs to implement io.micrometer.context.ThreadLocalAccessor for a ThreadLocal values of interest:

You can register a ThreadLocalAccessor manually on startup with the global ContextRegistry instance, which is accessible via io.micrometer.context.ContextRegistry#getInstance(). You can also register it automatically through the java.util.ServiceLoader mechanism.

A Reactive DataFetcher can rely on access to Reactor context that originates from the WebFlux request handling chain. This includes Reactor context added by WebGraphQlInterceptor components.

The GraphQL Java engine may run into validation or other errors when parsing the request and that in turn prevent request execution. In such cases, the response contains a "data" key with null and one or more request-level "errors" that are global, i.e. not having a field path.

DataFetcherExceptionResolver cannot handle such global errors because they are raised before execution begins and before any DataFetcher is invoked. An application can use transport level interceptors to inspect and transform errors in the ExecutionResult. See examples under WebGraphQlInterceptor.

The Publisher for a subscription request may complete with an error signal in which case the underlying transport (e.g. WebSocket) sends a final "error" type message with a list of GraphQL errors.

DataFetcherExceptionResolver cannot resolve errors from a subscription Publisher, since the data DataFetcher only creates the Publisher initially. After that, the transport subscribes to the Publisher that may then complete with an error.

An application can register a SubscriptionExceptionResolver in order to resolve exceptions from a subscription Publisher in order to resolve those to GraphQL errors to send to the client.

Connection type definitions must be created for every type that needs pagination, adding boilerplate and noise to the schema. Spring for GraphQL provides ConnectionTypeDefinitionConfigurer to add these types on startup, if not already present in the parsed schema files. That means in the schema you only need this:

Note the spec-defined forward pagination arguments first and after that clients can use to request the first N items after the given cursor, while last and before are backward pagination arguments to request the last N items before the given cursor.

Next, configure ConnectionTypeDefinitionConfigurer as follows:

and the following type definitions will be transparently added to the schema:

The Boot Starter registers ConnectionTypeDefinitionConfigurer by default.

Once Connection Types are available in the schema, you also need equivalent Java types. GraphQL Java provides those, including generic Connection and Edge, as well as a PageInfo.

One option is to populate a Connection and return it from your controller method or DataFetcher. However, this requires boilerplate code to create the Connection, creating cursors, wrapping each item as an Edge, and creating the PageInfo. Moreover, you may already have an underlying pagination mechanism such as when using Spring Data repositories.

Spring for GraphQL defines the ConnectionAdapter contract to adapt a container of items to Connection. Adapters are applied through a DataFetcher decorator that is in turn installed through a ConnectionFieldTypeVisitor. You can configure it as follows:

There are built-in ConnectionAdapters for Spring Data’s Window and Slice. You can also create your own custom adapter. ConnectionAdapter implementations rely on a CursorStrategy to create cursors for returned items. The same strategy is also used to support the Subrange controller method argument that contains pagination input.

CursorStrategy is a contract to encode and decode a String cursor that refers to the position of an item within a large result set. The cursor can be based on an index or on a keyset.

A ConnectionAdapter uses this to encode cursors for returned items. Annotated Controllers methods, Querydsl repositories, and Query by Example repositories use it to decode cursors from pagination requests, and create a Subrange.

CursorEncoder is a related contract that further encodes and decodes String cursors to make them opaque to clients. EncodingCursorStrategy combines CursorStrategy with a CursorEncoder. You can use Base64CursorEncoder, NoOpEncoder or create your own.

There is a built-in CursorStrategy for the Spring Data ScrollPosition. The Boot Starter registers a CursorStrategy<ScrollPosition> with Base64Encoder when Spring Data is present.

There is no standard way to provide sort information in a GraphQL request. However, pagination depends on a stable sort order. You can use a default order, or otherwise expose input types and extract sort details from GraphQL arguments.

There is built-in support for Spring Data’s Sort as a controller method argument. For this to work, you need to have a SortStrategy bean.

GraphQL Java provides a DataLoader mechanism for batch loading of related entities. You can find the full details in the GraphQL Java docs. Below is a summary of how it works:

The complete batching loading mechanism in GraphQL Java requires implementing one of several BatchLoader interface, then wrapping and registering those as DataLoaders with a name in the DataLoaderRegistry.

The API in Spring GraphQL is slightly different. For registration, there is only one, central BatchLoaderRegistry exposing factory methods and a builder to create and register any number of batch loading functions:

The Boot Starter declares a BatchLoaderRegistry bean that you can inject into your configuration, as shown above, or into any component such as a controller in order register batch loading functions. In turn the BatchLoaderRegistry is injected into DefaultExecutionGraphQlService where it ensures DataLoader registrations per request.

By default, the DataLoader name is based on the class name of the target entity. This allows an @SchemaMapping method to declare a DataLoader argument with a generic type, and without the need for specifying a name. The name, however, can be customized through the BatchLoaderRegistry builder, if necessary, along with other DataLoaderOptions.

To configure default DataLoaderOptions globally, to use as a starting point for any registration, you can override Boot’s BatchLoaderRegistry bean and use the constructor for DefaultBatchLoaderRegistry that accepts Supplier<DataLoaderOptions>.

For many cases, when loading related entities, you can use @BatchMapping controller methods, which are a shortcut for and replace the need to use BatchLoaderRegistry and DataLoader directly.

BatchLoaderRegistry provides other important benefits too. It supports access to the same GraphQLContext from batch loading functions and from @BatchMapping methods, as well as ensures Context Propagation to them. This is why applications are expected to use it. It is possible to perform your own DataLoader registrations directly but such registrations would forgo the above benefits.

Start by having BatchLoaderRegistry perform registrations on a DataLoaderRegistry:

Now you can access and test individual DataLoader's as follows:

To configure Querydsl in your build, follow the official reference documentation:

For example:

The webmvc-http sample uses Querydsl for artifactRepositories.

QuerydslDataFetcher supports customizing how GraphQL arguments are bound onto properties to create a Querydsl Predicate. By default, arguments are bound as "is equal to" for each available property. To customize that, you can use QuerydslDataFetcher builder methods to provide a QuerydslBinderCustomizer.

A repository may itself be an instance of QuerydslBinderCustomizer. This is auto-detected and transparently applied during Auto-Registration. However, when manually building a QuerydslDataFetcher you will need to use builder methods to apply it.

QuerydslDataFetcher supports interface and DTO projections to transform query results before returning these for further GraphQL processing.

To use Spring Data projections with Querydsl repositories, create either a projection interface or a target DTO class and configure it through the projectAs method to obtain a DataFetcher producing the target type:

If a repository is annotated with @GraphQlRepository, it is automatically registered for queries that do not already have a registered DataFetcher and whose return type matches that of the repository domain type. This includes single value queries, multi-value queries, and paginated queries.

By default, the name of the GraphQL type returned by the query must match the simple name of the repository domain type. If needed, you can use the typeName attribute of @GraphQlRepository to specify the target GraphQL type name.

For paginated queries, the simple name of the repository domain type must match the Connection type name without the Connection ending (e.g. Book matches BooksConnection). For auto-registration, pagination is offset-based with 20 items per page.

Auto-registration detects if a given repository implements QuerydslBinderCustomizer and transparently applies that through QuerydslDataFetcher builder methods.

Auto-registration is performed through a built-in RuntimeWiringConfigurer that can be obtained from QuerydslDataFetcher. The Boot Starter automatically detects @GraphQlRepository beans and uses them to initialize the RuntimeWiringConfigurer with.

Auto-registration applies customizations by calling customize(Builder) on the repository instance if your repository implements QuerydslBuilderCustomizer or ReactiveQuerydslBuilderCustomizer respectively.

Query by Example is already included in the Spring Data modules for the data stores where it is supported, so no extra setup is required to enable it.

QueryByExampleDataFetcher supports interface and DTO projections to transform query results before returning these for further GraphQL processing.

To use Spring Data projections with Query by Example repositories, create either a projection interface or a target DTO class and configure it through the projectAs method to obtain a DataFetcher producing the target type:

If a repository is annotated with @GraphQlRepository, it is automatically registered for queries that do not already have a registered DataFetcher and whose return type matches that of the repository domain type. This includes single value queries, multi-value queries, and paginated queries.

By default, the name of the GraphQL type returned by the query must match the simple name of the repository domain type. If needed, you can use the typeName attribute of @GraphQlRepository to specify the target GraphQL type name.

For paginated queries, the simple name of the repository domain type must match the Connection type name without the Connection ending (e.g. Book matches BooksConnection). For auto-registration, pagination is offset-based with 20 items per page.

Auto-registration is performed through a built-in RuntimeWiringConfigurer that can be obtained from QueryByExampleDataFetcher. The Boot Starter automatically detects @GraphQlRepository beans and uses them to initialize the RuntimeWiringConfigurer with.

Auto-registration applies customizations by calling customize(Builder) on the repository instance if your repository implements QueryByExampleBuilderCustomizer or ReactiveQueryByExampleBuilderCustomizer respectively.

Schema mapping handler methods can have any of the following method arguments:

Schema mapping handler methods can return:

In GraphQL Java, DataFetchingEnvironment provides access to a map of field-specific argument values. The values can be simple scalar values (e.g. String, Long), a Map of values for more complex input, or a List of values.

Use the @Argument annotation to have an argument bound to a target object and injected into the handler method. Binding is performed by mapping argument values to a primary data constructor of the expected method parameter type, or by using a default constructor to create the object and then map argument values to its properties. This is repeated recursively, using all nested argument values and creating nested target objects accordingly. For example:

By default, if the method parameter name is available (requires the -parameters compiler flag with Java 8+ or debugging info from the compiler), it is used to look up the argument. If needed, you can customize the name through the annotation, e.g. @Argument("bookInput").

If binding fails, a BindException is raised with binding issues accumulated as field errors where the field of each error is the argument path where the issue occurred.

You can use @Argument with a Map<String, Object> argument, to obtain the raw value of the argument. For example:

By default, input arguments in GraphQL are nullable and optional, which means an argument can be set to the null literal, or not provided at all. This distinction is useful for partial updates with a mutation where the underlying data may also be, either set to null or not changed at all accordingly. When using @Argument there is no way to make such a distinction, because you would get null or an empty Optional in both cases.

If you want to know not whether a value was not provided at all, you can declare an ArgumentValue method parameter, which is a simple container for the resulting value, along with a flag to indicate whether the input argument was omitted altogether. You can use this instead of @Argument, in which case the argument name is determined from the method parameter name, or together with @Argument to specify the argument name.

For example:

ArgumentValue is also supported as a field within the object structure of an @Argument method parameter, either initialized via a constructor argument or via a setter, including as a field of an object nested at any level below the top level object.

Use the @Arguments annotation, if you want to bind the full arguments map onto a single target Object, in contrast to @Argument, which binds a specific, named argument.

For example, @Argument BookInput bookInput uses the value of the argument "bookInput" to initialize BookInput, while @Arguments uses the full arguments map and in that case, top-level arguments are bound to BookInput properties.

You can use @Arguments with a Map<String, Object> argument, to obtain the raw map of all argument values.

As an alternative to using complete Objects with @Argument, you can also use a projection interface to access GraphQL request arguments through a well-defined, minimal interface. Argument projections are provided by Spring Data’s Interface projections when Spring Data is on the class path.

To make use of this, create an interface annotated with @ProjectedPayload and declare it as a controller method parameter. If the parameter is annotated with @Argument, it applies to an individual argument within the DataFetchingEnvironment.getArguments() map. When declared without @Argument, the projection works on top-level arguments in the complete arguments map.

For example:

In GraphQL Java, the DataFetchingEnvironment provides access to the source (i.e. parent/container) instance of the field. To access this, simply declare a method parameter of the expected target type.

The source method argument also helps to determine the type name for the mapping. If the simple name of the Java class matches the GraphQL type, then there is no need to explicitly specify the type name in the @SchemaMapping annotation.

When there is a CursorStrategy bean in Spring configuration, controller methods support a Subrange<P> argument where <P> is a relative position converted from a cursor. For Spring Data, ScrollSubrange exposes ScrollPosition. For example:

See Pagination for an overview of pagination and of built-in mechanisms.

When there is a SortStrategy bean in Spring configuration, controller methods support Sort as a method argument. For example:

When you register a batch loading function for an entity, as explained in Batch Loading, you can access the DataLoader for the entity by declaring a method argument of type DataLoader and use it to load the entity:

By default, BatchLoaderRegistry uses the full class name of the value type (e.g. the class name for Author) for the key of the registration, and therefore simply declaring the DataLoader method argument with generic types provides enough information to locate it in the DataLoaderRegistry. As a fallback, the DataLoader method argument resolver will also try the method argument name as the key but typically that should not be necessary.

Note that for many cases with loading related entities, where the @SchemaMapping simply delegates to a DataLoader, you can reduce boilerplate by using a @BatchMapping method as described in the next section.

When a javax.validation.Validator bean is found, AnnotatedControllerConfigurer enables support for Bean Validation on annotated controller methods. Typically, the bean is of type LocalValidatorFactoryBean.

Bean validation lets you declare constraints on types:

You can then annotate a controller method parameter with @Valid to validate it before method invocation:

If an error occurs during validation, a ConstraintViolationException is raised. You can use the Exceptions chain to decide how to present that to clients by turning it into an error to include in the GraphQL response.

Bean validation is useful for @Argument, @Arguments, and @ProjectedPayload method parameters, but applies more generally to any method parameter.

Batch mapping methods support the following arguments:

Batch mapping methods can return:

Exception handler methods support a flexible method signature with method arguments resolved from a DataFetchingEnvironment, and matching to those of @SchemaMapping methods.

Supported return types are listed below:

HttpGraphQlClient uses WebClient to execute GraphQL requests over HTTP.

Once HttpGraphQlClient is created, you can begin to execute requests using the same API, independent of the underlying transport. If you need to change any transport specific details, use mutate() on an existing HttpGraphQlClient to create a new instance with customized settings:

WebSocketGraphQlClient executes GraphQL requests over a shared WebSocket connection. It is built using the WebSocketClient from Spring WebFlux and you can create it as follows:

In contrast to HttpGraphQlClient, the WebSocketGraphQlClient is connection oriented, which means it needs to establish a connection before making any requests. As you begin to make requests, the connection is established transparently. Alternatively, use the client’s start() method to establish the connection explicitly before any requests.

In addition to being connection-oriented, WebSocketGraphQlClient is also multiplexed. It maintains a single, shared connection for all requests. If the connection is lost, it is re-established on the next request or if start() is called again. You can also use the client’s stop() method which cancels in-progress requests, closes the connection, and rejects new requests.

Once WebSocketGraphQlClient is created, you can begin to execute requests using the same API, independent of the underlying transport. If you need to change any transport specific details, use mutate() on an existing WebSocketGraphQlClient to create a new instance with customized settings:

RSocketGraphQlClient uses RSocketRequester to execute GraphQL requests over RSocket requests.

In contrast to HttpGraphQlClient, the RSocketGraphQlClient is connection oriented, which means it needs to establish a session before making any requests. As you begin to make requests, the session is established transparently. Alternatively, use the client’s start() method to establish the session explicitly before any requests.

RSocketGraphQlClient is also multiplexed. It maintains a single, shared session for all requests. If the session is lost, it is re-established on the next request or if start() is called again. You can also use the client’s stop() method which cancels in-progress requests, closes the session, and rejects new requests.

Once RSocketGraphQlClient is created, you can begin to execute requests using the same API, independent of the underlying transport.

GraphQlClient defines a parent Builder with common configuration options for the builders of all extensions. Currently, it has lets you configure:

The below retrieves and decodes the data for a query:

The input document is a String that could be a literal or produced through a code generated request object. You can also define documents in files and use a Document Source to resole them by file name.

The path is relative to the "data" key and uses a simple dot (".") separated notation for nested fields with optional array indices for list elements, e.g. "project.name" or "project.releases[0].version".

Decoding can result in FieldAccessException if the given path is not present, or the field value is null and has an error. FieldAccessException provides access to the response and the field:

Retrieve is only a shortcut to decode from a single path in the response map. For more control, use the execute method and handle the response:

For example:

The document for a request is a String that may be defined in a local variable or constant, or it may be produced through a code generated request object.

You can also create document files with extensions .graphql or .gql under "graphql-documents/" on the classpath and refer to them by file name.

For example, given a file called projectReleases.graphql in src/main/resources/graphql-documents, with content:

You can then:

The "JS GraphQL" plugin for IntelliJ supports GraphQL query files with code completion.

You can use the GraphQlClient Builder to customize the DocumentSource for loading documents by names.

To start a subscription stream, use retrieveSubscription which is similar to retrieve for a single response but returning a stream of responses, each decoded to some data:

The Flux may terminate with SubscriptionErrorException if the subscription ends from the server side with an "error" message. The exception provides access to GraphQL errors decoded from the "error" message.

The Flux may termiate with GraphQlTransportException such as WebSocketDisconnectedException if the underlying connection is closed or lost. In that case you can use the retry operator to restart the subscription.

To end the subscription from the client side, the Flux must be cancelled, and in turn the WebSocket transport sends a "complete" message to the server. How to cancel the Flux depends on how it is used. Some operators such as take or timeout themselves cancel the Flux. If you subscribe to the Flux with a Subscriber, you can get a reference to the Subscription and cancel through it. The onSubscribe operator also provides access to the Subscription.

Retrieve is only a shortcut to decode from a single path in each response map. For more control, use the executeSubscription method and handle each response directly:

HttpGraphQlTester uses WebTestClient to execute GraphQL requests over HTTP, with or without a live server, depending on how WebTestClient is configured.

To test in Spring WebFlux, without a live server, point to your Spring configuration that declares the GraphQL HTTP endpoint:

To test in Spring MVC, without a live server, do the same using MockMvcWebTestClient:

Or to test against a live server running on a port:

Once HttpGraphQlTester is created, you can begin to execute requests using the same API, independent of the underlying transport. If you need to change any transport specific details, use mutate() on an existing HttpSocketGraphQlTester to create a new instance with customized settings:

WebSocketGraphQlTester executes GraphQL requests over a shared WebSocket connection. It is built using the WebSocketClient from Spring WebFlux and you can create it as follows:

WebSocketGraphQlTester is connection oriented and multiplexed. Each instance establishes its own single, shared connection for all requests. Typically, you’ll want to use a single instance only per server.

Once WebSocketGraphQlTester is created, you can begin to execute requests using the same API, independent of the underlying transport. If you need to change any transport specific details, use mutate() on an existing WebSocketGraphQlTester to create a new instance with customized settings:

WebSocketGraphQlTester provides a stop() method that you can use to have the WebSocket connection closed, e.g. after a test runs.

RSocketGraphQlTester uses RSocketRequester from spring-messaging to execute GraphQL requests over RSocket:

RSocketGraphQlTester is connection oriented and multiplexed. Each instance establishes its own single, shared session for all requests. Typically, you’ll want to use a single instance only per server. You can use the stop() method on the tester to close the session explicitly.

Once RSocketGraphQlTester is created, you can begin to execute requests using the same API, independent of the underlying transport.

Many times it’s enough to test GraphQL requests on the server side, without the use of a client to send requests over a transport protocol. To test directly against a ExecutionGraphQlService, use the ExecutionGraphQlServiceTester extension:

Once ExecutionGraphQlServiceTester is created, you can begin to execute requests using the same API, independent of the underlying transport.

ExecutionGraphQlServiceTester.Builder provides an option to customize ExecutionInput details:

The GraphQlService extension lets you test on the server side, without a client. However, in some cases it’s useful to involve server side transport handling with given mock transport input.

The WebGraphQlTester extension lets you processes request through the WebGraphQlInterceptor chain before handing off to ExecutionGraphQlService for request execution:

The builder for this extension allows you to define HTTP request details:

Once WebGraphQlServiceTester is created, you can begin to execute requests using the same API, independent of the underlying transport.

GraphQlTester defines a parent Builder with common configuration options for the builders of all extensions. It lets you configure the following:

By default, paths are relative to the "data" section of the GraphQL response. You can also nest down to a path, and inspect multiple paths relative to it as follows: