[plugin] support generating graphql client test sources (#718)

* [plugin] support generating graphql client test sources

Generate GraphQL client Gradle task and Maven Mojo now accept optional `generateTestSources` boolean parameter to indicate generation of test sources.

Resolves: #706

* fix example maven client

* fix test

* separate generateTestClient task/mojo

* update docs

* revert some docs to old format

Author: dariuszkuc

docs/plugins/gradle-plugin.md

@@ -41,6 +41,8 @@ graphql {
   allowDeprecatedFields = false
   // Custom GraphQL scalar to converter mapping containing information about corresponding Java type and converter that should be used to serialize/deserialize values.
   converters.put("UUID", ScalarConverterMapping("java.util.UUID", "com.example.UUIDScalarConverter"))
+  // Boolean flag indicating whether generated GraphQL client should be added to main or test sources.
+  generateTestSources = false
 }
 ```
 
@@ -66,7 +68,7 @@ and could be used as an alternative to `graphqlIntrospectSchema` to generate inp
 
 Task that generates GraphQL Kotlin client and corresponding data classes based on the provided GraphQL queries that are
 evaluated against target Graphql schema. Individual clients with their specific data models are generated for each query
-file and are placed under specified `packageName`.
+file and are placed under specified `packageName`. Generated code is automatically added to the project main source set.
 
 **Properties**
 
@@ -80,6 +82,24 @@ file and are placed under specified `packageName`.
 | `schemaFile` | File | `schemaFileName` or `schemaFile` has to be provided | GraphQL schema file that will be used to generate client code. |
 | `schemaFileName` | String | `schemaFileName` or `schemaFile` has to be provided | Path to GraphQL schema file that will be used to generate client code.<br/>**Command line property is**: `schemaFileName`. |
 
+### graphqlGenerateTestClient
+
+Task that generates GraphQL Kotlin test client and corresponding data classes based on the provided GraphQL queries that are
+evaluated against target Graphql schema. Individual test clients with their specific data models are generated for each query
+file and are placed under specified `packageName`. Generated code is automatically added to the project test source set.
+
+**Properties**
+
+| Property | Type | Required | Description |
+| -------- | ---- | -------- | ----------- |
+| `allowDeprecatedFields` | Boolean | | Boolean flag indicating whether selection of deprecated fields is allowed or not.<br/>**Default value is:** `false`.<br/>**Command line property is**: `allowDeprecatedFields`. |
+| `converters` | Map<String, ScalarConverter> | | Custom GraphQL scalar to converter mapping containing information about corresponding Java type and converter that should be used to serialize/deserialize values. |
+| `packageName` | String | yes | Target package name for generated code.<br/>**Command line property is**: `packageName`. |
+| `queryFiles` | FileCollection | | List of query files to be processed. Instead of a list of files to be processed you can specify `queryFileDirectory` directory instead. If this property is specified it will take precedence over the corresponding directory property. |
+| `queryFileDirectory` | String | | Directory file containing GraphQL queries. Instead of specifying a directory you can also specify list of query file by using `queryFiles` property instead.<br/>**Default value is:** `src/test/resources`.<br/>**Command line property is**: `queryFileDirectory`. |
+| `schemaFile` | File | `schemaFileName` or `schemaFile` has to be provided | GraphQL schema file that will be used to generate client code. |
+| `schemaFileName` | String | `schemaFileName` or `schemaFile` has to be provided | Path to GraphQL schema file that will be used to generate client code.<br/>**Command line property is**: `schemaFileName`. |
+
 ### graphqlIntrospectSchema
 
 Task that executes GraphQL introspection query against specified `endpoint` and saves the underlying schema file as

docs/plugins/maven-plugin.md

@@ -45,12 +45,51 @@ Generate GraphQL client code based on the provided GraphQL schema and target que
 | -------- | ---- | -------- | ----------- |
 | `allowDeprecatedFields` | Boolean | | Boolean flag indicating whether selection of deprecated fields is allowed or not.<br/>**Default value is:** `false`.<br/>**User property is**: `graphql.allowDeprecatedFields`. |
 | `converters` | Map<String, ScalarConverter> | | Custom GraphQL scalar to converter mapping containing information about corresponding Java type and converter that should be used to serialize/deserialize values. |
-| `outputDirectory` | File | | Target directory where to store generated files.<br/>**Default value is**: `${project.build.directory}/generated/sources/graphql` |
+| `outputDirectory` | File | | Target directory where to store generated files.<br/>**Default value is**: `${project.build.directory}/generated-sources/graphql` |
 | `packageName` | String | yes | Target package name for generated code.<br/>**User property is**: `graphql.packageName`. |
 | `queryFileDirectory` | File | | Directory file containing GraphQL queries. Instead of specifying a directory you can also specify list of query file by using `queryFiles` property instead.<br/>**Default value is:** `src/main/resources`. |
 | `queryFiles` | List<File> | | List of query files to be processed. Instead of a list of files to be processed you can also specify `queryFileDirectory` directory containing all the files. If this property is specified it will take precedence over the corresponding directory property. |
 | `schemaFile` | String | yes | GraphQL schema file that will be used to generate client code.<br/>**User property is**: `graphql.schemaFile`. |
 
+**Parameter Details**
+
+  * *converters* - Custom GraphQL scalar to converter mapping containing information about corresponding Java type and converter that should be used to serialize/deserialize values.
+
+    ```xml
+    <converters>
+      <!-- custom scalar type -->
+      <UUID>
+        <!-- fully qualified Java class name of a custom scalar type -->
+        <type>java.util.UUID</type>
+        <!-- fully qualified Java class name of a custom com.expediagroup.graphql.client.converter.ScalarConverter
+             used to convert to/from raw JSON and scalar type -->
+        <converter>com.example.UUIDScalarConverter</converter>
+      </UUID>
+    </converters>
+    ```
+
+### generateTestClient
+
+Generate GraphQL test client code based on the provided GraphQL schema and target queries.
+
+**Attributes**
+
+* *Default Lifecycle Phase*: `generate-test-sources`
+* *Requires Maven Project*
+* Generated classes are automatically added to the list of test compiled sources.
+
+**Parameters**
+
+| Property | Type | Required | Description |
+| -------- | ---- | -------- | ----------- |
+| `allowDeprecatedFields` | Boolean | | Boolean flag indicating whether selection of deprecated fields is allowed or not.<br/>**Default value is:** `false`.<br/>**User property is**: `graphql.allowDeprecatedFields`. |
+| `converters` | Map<String, ScalarConverter> | | Custom GraphQL scalar to converter mapping containing information about corresponding Java type and converter that should be used to serialize/deserialize values. |
+| `outputDirectory` | File | | Target directory where to store generated files.<br/>**Default value is**: `${project.build.directory}/generated-test-sources/graphql` |
+| `packageName` | String | yes | Target package name for generated code.<br/>**User property is**: `graphql.packageName`. |
+| `queryFileDirectory` | File | | Directory file containing GraphQL queries. Instead of specifying a directory you can also specify list of query file by using `queryFiles` property instead.<br/>**Default value is:** `src/test/resources`. |
+| `queryFiles` | List<File> | | List of query files to be processed. Instead of a list of files to be processed you can also specify `queryFileDirectory` directory containing all the files. If this property is specified it will take precedence over the corresponding directory property. |
+| `schemaFile` | String | yes | GraphQL schema file that will be used to generate client code.<br/>**User property is**: `graphql.schemaFile`. |
+
 **Parameter Details**
 
   * *converters* - Custom GraphQL scalar to converter mapping containing information about corresponding Java type and converter that should be used to serialize/deserialize values.
@@ -185,6 +224,9 @@ Mojo can also be configured in your Maven build file and it provides additional
 This will process all GraphQL queries located under `src/main/resources` and generate corresponding GraphQL Kotlin clients.
 Generated classes will be automatically added to the project compile sources.
 
+>NOTE: You might need to explicitly add generated clients to your project sources for your IDE to recognize them. See
+>[build-helper-maven-plugin](https://www.mojohaus.org/build-helper-maven-plugin/) for details.
+
 ### Generating Client with Custom Scalars
 
 By default, all custom GraphQL scalars will be serialized as Strings. You can override this default behavior by specifying
@@ -277,6 +319,6 @@ This generated schema is subsequently used to generate GraphQL client code based
 </plugin>
 ```
 
-NOTE: Both `introspectSchema` and `generateClient` goals are bound to the same `generate-sources` Maven lifecycle phase.
-As opposed to Gradle, Maven does not support explicit dependencies between different goals and they will be executed in
-the order they are defined in your `pom.xml` build file.
+>NOTE: Both `introspectSchema` and `generateClient` goals are bound to the same `generate-sources` Maven lifecycle phase.
+>As opposed to Gradle, Maven does not support explicit ordering of goals. Maven Mojos will be executed in the order they
+>are defined in your `pom.xml` build file.

examples/client/gradle-client/settings.gradle.kts

@@ -0,0 +1 @@
+rootProject.name = "graphql-kotlin-gradle-client-example"

examples/client/maven-client/pom.xml

@@ -91,7 +91,7 @@
                         </goals>
                         <configuration>
                             <sources>
-                                <source>${project.build.directory}/generated/sources/graphql</source>
+                                <source>${project.build.directory}/generated-sources/graphql</source>
                             </sources>
                         </configuration>
                     </execution>

examples/client/server/settings.gradle.kts

@@ -0,0 +1 @@
+rootProject.name = "graphql-kotlin-simple-server-example"

plugins/graphql-kotlin-gradle-plugin/README.md

@@ -51,7 +51,7 @@ and could be used as an alternative to `graphqlIntrospectSchema` to generate inp
 
 Task that generates GraphQL Kotlin client and corresponding data classes based on the provided GraphQL queries that are
 evaluated against target Graphql schema. Individual clients with their specific data models are generated for each query
-file and are placed under specified `packageName`.
+file and are placed under specified `packageName`. Generated code is automatically added to the project main source set.
 
 **Properties**
 
@@ -65,6 +65,24 @@ file and are placed under specified `packageName`.
 | `schemaFile` | File | `schemaFileName` or `schemaFile` has to be provided | GraphQL schema file that will be used to generate client code. |
 | `schemaFileName` | String | `schemaFileName` or `schemaFile` has to be provided | Path to GraphQL schema file that will be used to generate client code.<br/>**Command line property is**: `schemaFileName`. |
 
+### graphqlGenerateTestClient
+
+Task that generates GraphQL Kotlin test client and corresponding data classes based on the provided GraphQL queries that are
+evaluated against target Graphql schema. Individual test clients with their specific data models are generated for each query
+file and are placed under specified `packageName`. Generated code is automatically added to the project test source set.
+
+**Properties**
+
+| Property | Type | Required | Description |
+| -------- | ---- | -------- | ----------- |
+| `allowDeprecatedFields` | Boolean | | Boolean flag indicating whether selection of deprecated fields is allowed or not.<br/>**Default value is:** `false`.<br/>**Command line property is**: `allowDeprecatedFields`. |
+| `converters` | Map<String, ScalarConverter> | | Custom GraphQL scalar to converter mapping containing information about corresponding Java type and converter that should be used to serialize/deserialize values. |
+| `packageName` | String | yes | Target package name for generated code.<br/>**Command line property is**: `packageName`. |
+| `queryFiles` | FileCollection | | List of query files to be processed. Instead of a list of files to be processed you can specify `queryFileDirectory` directory instead. If this property is specified it will take precedence over the corresponding directory property. |
+| `queryFileDirectory` | String | | Directory file containing GraphQL queries. Instead of specifying a directory you can also specify list of query file by using `queryFiles` property instead.<br/>**Default value is:** `src/test/resources`.<br/>**Command line property is**: `queryFileDirectory`. |
+| `schemaFile` | File | `schemaFileName` or `schemaFile` has to be provided | GraphQL schema file that will be used to generate client code. |
+| `schemaFileName` | String | `schemaFileName` or `schemaFile` has to be provided | Path to GraphQL schema file that will be used to generate client code.<br/>**Command line property is**: `schemaFileName`. |
+
 ### graphqlIntrospectSchema
 
 Task that executes GraphQL introspection query against specified `endpoint` and saves the underlying schema file as

plugins/graphql-kotlin-gradle-plugin/build.gradle.kts

@@ -5,7 +5,6 @@ plugins {
     id("com.gradle.plugin-publish")
 }
 
-val kotlinVersion: String by project
 val kotlinCoroutinesVersion: String by project
 val wireMockVersion: String by project
 
@@ -59,7 +58,10 @@ tasks {
         }
     }
     test {
+        val kotlinVersion: String by project
+        val junitVersion: String by project
         systemProperty("graphQLKotlinVersion", project.version)
         systemProperty("kotlinVersion", kotlinVersion)
+        systemProperty("junitVersion", junitVersion)
     }
 }

plugins/graphql-kotlin-gradle-plugin/src/main/kotlin/com/expediagroup/graphql/plugin/gradle/GraphQLGradlePlugin.kt

@@ -18,13 +18,15 @@ package com.expediagroup.graphql.plugin.gradle
 
 import com.expediagroup.graphql.plugin.gradle.tasks.DOWNLOAD_SDL_TASK_NAME
 import com.expediagroup.graphql.plugin.gradle.tasks.GENERATE_CLIENT_TASK_NAME
+import com.expediagroup.graphql.plugin.gradle.tasks.GENERATE_TEST_CLIENT_TASK_NAME
 import com.expediagroup.graphql.plugin.gradle.tasks.GraphQLDownloadSDLTask
 import com.expediagroup.graphql.plugin.gradle.tasks.GraphQLGenerateClientTask
 import com.expediagroup.graphql.plugin.gradle.tasks.GraphQLIntrospectSchemaTask
 import com.expediagroup.graphql.plugin.gradle.tasks.INTROSPECT_SCHEMA_TASK_NAME
 import org.gradle.api.Plugin
 import org.gradle.api.Project
 import org.gradle.api.tasks.SourceSetContainer
+import java.io.File
 
 private const val PLUGIN_EXTENSION_NAME = "graphql"
 
@@ -39,19 +41,17 @@ class GraphQLGradlePlugin : Plugin<Project> {
         project.tasks.register(INTROSPECT_SCHEMA_TASK_NAME, GraphQLIntrospectSchemaTask::class.java)
         project.tasks.register(DOWNLOAD_SDL_TASK_NAME, GraphQLDownloadSDLTask::class.java)
         project.tasks.register(GENERATE_CLIENT_TASK_NAME, GraphQLGenerateClientTask::class.java) { generateClientTask ->
-            val compileKotlinTask = project.tasks.findByPath("compileKotlin")
-            if (compileKotlinTask == null) {
-                throw RuntimeException("compileKotlin task not found")
-            } else {
-                compileKotlinTask.dependsOn(generateClientTask.path)
-            }
+            configureCompileTaskDependency(project = project, generateClientTaskPath = generateClientTask.path)
 
-            // configure generated directory source sets
-            val outputDirectory = generateClientTask.outputDirectory.get().asFile
-            outputDirectory.mkdirs()
+            generateClientTask.queryFileDirectory.convention("${project.projectDir}/src/main/resources")
+            generateClientTask.outputDirectory.convention(project.layout.buildDirectory.dir("generated/source/graphql/main"))
+        }
+        project.tasks.register(GENERATE_TEST_CLIENT_TASK_NAME, GraphQLGenerateClientTask::class.java) { generateTestClientTask ->
+            configureCompileTaskDependency(project = project, generateClientTaskPath = generateTestClientTask.path, compileTaskName = "compileTestKotlin")
 
-            val sourceSetContainer = project.findProperty("sourceSets") as? SourceSetContainer
-            sourceSetContainer?.findByName("main")?.java?.srcDir(outputDirectory.path)
+            generateTestClientTask.description = "Generate HTTP test client from the specified GraphQL queries."
+            generateTestClientTask.queryFileDirectory.convention("${project.projectDir}/src/test/resources")
+            generateTestClientTask.outputDirectory.convention(project.layout.buildDirectory.dir("generated/source/graphql/test"))
         }
 
         project.afterEvaluate {
@@ -75,6 +75,29 @@ class GraphQLGradlePlugin : Plugin<Project> {
                     generateClientTask.schemaFile.convention(downloadSDLTask.outputFile)
                 }
             }
+
+            project.tasks.named(GENERATE_CLIENT_TASK_NAME, GraphQLGenerateClientTask::class.java) { task ->
+                configureProjectSourceSet(project = project, outputDirectory = task.outputDirectory.get().asFile)
+            }
+            project.tasks.named(GENERATE_TEST_CLIENT_TASK_NAME, GraphQLGenerateClientTask::class.java) { task ->
+                configureProjectSourceSet(project = project, outputDirectory = task.outputDirectory.get().asFile, targetSourceSet = "test")
+            }
         }
     }
+
+    private fun configureCompileTaskDependency(project: Project, generateClientTaskPath: String, compileTaskName: String = "compileKotlin") {
+        val compileKotlinTask = project.tasks.findByPath(compileTaskName)
+        if (compileKotlinTask == null) {
+            throw RuntimeException("$compileKotlinTask task not found")
+        } else {
+            compileKotlinTask.dependsOn(generateClientTaskPath)
+        }
+    }
+
+    private fun configureProjectSourceSet(project: Project, outputDirectory: File, targetSourceSet: String = "main") {
+        outputDirectory.mkdirs()
+
+        val sourceSetContainer = project.findProperty("sourceSets") as? SourceSetContainer
+        sourceSetContainer?.findByName(targetSourceSet)?.java?.srcDir(outputDirectory.path)
+    }
 }

plugins/graphql-kotlin-gradle-plugin/src/main/kotlin/com/expediagroup/graphql/plugin/gradle/tasks/GraphQLGenerateClientTask.kt

@@ -25,7 +25,6 @@ import org.gradle.api.file.Directory
 import org.gradle.api.file.RegularFileProperty
 import org.gradle.api.provider.MapProperty
 import org.gradle.api.provider.Property
-import org.gradle.api.provider.Provider
 import org.gradle.api.tasks.Input
 import org.gradle.api.tasks.InputFile
 import org.gradle.api.tasks.InputFiles
@@ -36,6 +35,7 @@ import org.gradle.api.tasks.options.Option
 import java.io.File
 
 internal const val GENERATE_CLIENT_TASK_NAME: String = "graphqlGenerateClient"
+internal const val GENERATE_TEST_CLIENT_TASK_NAME: String = "graphqlGenerateTestClient"
 
 /**
  * Generate GraphQL Kotlin client and corresponding data classes based on the provided GraphQL queries.
@@ -97,13 +97,14 @@ open class GraphQLGenerateClientTask : DefaultTask() {
     val converters: MapProperty<String, ScalarConverterMapping> = project.objects.mapProperty(String::class.java, ScalarConverterMapping::class.java)
 
     /**
-     * Directory containing GraphQL queries, defaults to `src/main/resources`.
+     * Directory containing GraphQL queries. Defaults to `src/main/resources` when generating main sources and `src/test/resources`
+     * when generating test client.
      *
      * Instead of specifying a directory you can also specify list of query file by using `queryFiles` property instead.
      */
     @Input
     @Optional
-    @Option(option = "queryFileDirectory", description = "directory containing query files, defaults to src/main/resources")
+    @Option(option = "queryFileDirectory", description = "directory containing query files")
     val queryFileDirectory: Property<String> = project.objects.property(String::class.java)
 
     /**
@@ -115,13 +116,12 @@ open class GraphQLGenerateClientTask : DefaultTask() {
     val queryFiles: ConfigurableFileCollection = project.objects.fileCollection()
 
     @OutputDirectory
-    val outputDirectory: Provider<Directory> = project.layout.buildDirectory.dir("generated/source/graphql")
+    val outputDirectory: Property<Directory> = project.objects.directoryProperty()
 
     init {
         group = "GraphQL"
         description = "Generate HTTP client from the specified GraphQL queries."
 
-        queryFileDirectory.convention("${project.projectDir}/src/main/resources")
         allowDeprecatedFields.convention(false)
         converters.convention(emptyMap())
     }