Skip to content

Gradle plugin reference

Plugin id: art.galushko.openapi-test-generator

Implementation class: art.galushko.openapi.testgen.plugin.OpenApiTestGeneratorPlugin

Adding to an existing project

Step 1: Apply the plugin

plugins {
    id("art.galushko.openapi-test-generator") version "<version>"
}
See Version placeholders for how to choose <version>.

Step 2: Configure the generator

Minimum configuration:

openApiTestGenerator {
    specFile.set("src/main/resources/openapi.yaml")
    outputDir.set(layout.buildDirectory.dir("generated/openapi-tests"))
    generator.set("template") // or "test-suite-writer"
}

Step 3: Add test dependencies

For the template generator with RestAssured:

dependencies {
    testImplementation("io.rest-assured:rest-assured:5.5.0")
    testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")
}

Step 4: Run in CI

./gradlew test

Or explicitly:

./gradlew generateOpenApiTests test

See CI/CD integration for job wiring patterns.

Extension: openApiTestGenerator

Apply and configure:

plugins {
    id("art.galushko.openapi-test-generator") version "<version>"
}

openApiTestGenerator {
    specFile.set("src/test/resources/openapi.yaml")
    outputDir.set(layout.buildDirectory.dir("generated/openapi-tests"))
    generator.set("template")
}

Example: configure example value options:

openApiTestGenerator {
    testGenerationSettings {
        exampleValues.putAll(
            mapOf(
                "includeOptionalExampleProperties" to true,
                "includeWriteOnly" to false,
                "useSchemaExampleFallback" to true,
                "fullExample" to true,
            )
        )
    }
    parserSettings {
        yamlCodePointLimit.set(10_000_000)
    }
}

Fields

  • configFile: Property<String> (optional): path to YAML config.
  • specFile: Property<String>: path to the OpenAPI 3.x or Swagger 2.0 spec (relative to project dir or absolute).
  • outputDir: DirectoryProperty: output directory for generated artifacts.
  • generator: Property<String>: generator id (template or test-suite-writer). Unset by default (the convention is an empty string, treated as unset); when left unset, the id must come from the YAML config file's generator field, and no source-set auto-wiring is applied.
  • generatorOptions: MapProperty<String, Any>: generator-specific options.
  • testGenerationSettings: TestGenerationSettingsExtension: typed settings DSL (nested block).
  • parserSettings: ParserSettingsExtension: parser settings DSL (SnakeYAML).
  • manualOnly: Property<Boolean> (default false): disable automatic wiring when true.
  • alwaysWriteTests: Property<Boolean> (optional): force writing artifacts even when generation fails.
  • logLevel: Property<String> (optional, deprecated): has no effect inside Gradle — the daemon owns the SLF4J binding; use --info/--debug instead. The value is still validated.

Nested extension: parserSettings { ... }

  • yamlCodePointLimit: Property<Int>
  • yamlMaxAliasesForCollections: Property<Int>
  • yamlAllowRecursiveKeys: Property<Boolean>
  • yamlNestingDepthLimit: Property<Int>

Nested extension: testGenerationSettings { ... }

openApiTestGenerator {
    testGenerationSettings {
        maxSchemaDepth.set(50)
        maxSchemaCombinations.set(100)
        maxTestCasesPerOperation.set(1000)
        maxErrors.set(100)
        errorMode.set(art.galushko.openapi.testgen.model.error.ErrorMode.COLLECT_ALL)
        includeOperations.put("/users/{userId}", listOf("GET"))
        validSecurityValues.put("ApiKeyAuth", "test-key")
    }
}

Fields

  • includeOperations: MapProperty<String, Any>
  • ignoreTestCases: MapProperty<String, Any>
  • ignoreSchemaValidationRules: SetProperty<String>
  • ignoreAuthValidationRules: SetProperty<String>
  • maxSchemaDepth: Property<Int>
  • overrideBasicTestData: MapProperty<String, String>
  • maxSchemaCombinations: Property<Int>
  • maxMergedSchemaDepth: Property<Int>
  • maxTestCasesPerOperation: Property<Int>
  • validSecurityValues: MapProperty<String, String>
  • errorMode: Property<ErrorMode>
  • includeValidCase: Property<Boolean>
  • maxErrors: Property<Int>
  • exampleValues: MapProperty<String, Any> (raw map passed to core)
  • patternGeneration: MapProperty<String, Any> (raw map parsed by pattern support)

includeOperations expects a map of path strings to a list of HTTP methods (e.g., listOf("GET")).

Task: generateOpenApiTests

The plugin registers a single task:

  • Name: generateOpenApiTests
  • Group: verification

Registering additional tasks

Register extra OpenApiTestGeneratorTask instances to generate from several specs or configurations in one build. Directly registered tasks are not fed by the openApiTestGenerator { ... } extension and are not auto-wired into source sets — configure their inputs on the task itself (note that the task-level configFile is a RegularFileProperty, so pass a file, not a string):

import art.galushko.openapi.testgen.plugin.OpenApiTestGeneratorTask

tasks.register<OpenApiTestGeneratorTask>("generateOpenApiTestsYaml") {
    configFile.set(layout.projectDirectory.file("yaml-config.yaml"))
    outputDir.set(layout.projectDirectory.dir("src/test/resources"))
}

Wiring behavior

Wiring depends on generator and manualOnly:

  • template:
  • Adds outputDir to the test source set
  • Wires compilation (compileTestJava / compileTestKotlin) to depend on generation when manualOnly=false
  • test-suite-writer:
  • Wires generated files into processTestResources when manualOnly=false

Operation scope

  • Generation currently targets operations under paths.
  • OpenAPI webhooks are parsed but are not yet generated into test suites.
  • Swagger 2.0 input is normalized to the same OpenAPI model used for generation. See Supported specifications.
  • When a spec contains only webhooks and no paths, generateOpenApiTests completes successfully with zero generated suites.

See also

Distribution defaults

See Distribution settings for the shared defaults and precedence used by the CLI and Gradle plugin.