FAQ¶
Short answers to common questions, each linking to the page that covers the topic in depth.
How do I install the CLI?¶
The quickest path is npm: npm install -g @openapi-testgen/cli (native binaries are used automatically where available, falling back to a bundled JAR that needs Java 21+). Native binaries and JVM distributions are also on GitHub Releases. See Installation.
How do I generate tests from an OpenAPI spec in a Gradle build?¶
Apply the plugin art.galushko.openapi-test-generator, configure specFile, outputDir, and generator in the openApiTestGenerator { ... } block, then run ./gradlew generateOpenApiTests. Template output is wired into your test sources automatically. See Gradle integration and the Gradle plugin reference.
How do I generate JSON or YAML test suites instead of Java code?¶
Use the test-suite-writer generator instead of template. It writes TestSuite data files for data-driven frameworks or custom runners. See Test-suite-writer generator.
How do I provide API keys or tokens for secured endpoints?¶
Set validSecurityValues, keyed by the scheme name under components.securitySchemes (e.g. ApiKeyAuth) — not the header name (e.g. X-API-Key). Without it, secured requests carry <valid_..._placeholder> values. See Security values.
How do I generate tests for only specific endpoints?¶
Use includeOperations with exact paths (or * wildcards for path/method) — it filters before generation, so it is also the fastest option on large specs. See Include operations.
How do I skip specific test cases or disable a validation rule?¶
Skip generated cases by operation and name with ignoreTestCases; disable a rule everywhere by adding its fully qualified class name to ignoreSchemaValidationRules / ignoreAuthValidationRules. See Ignore rules and Disable a rule.
Does it generate positive (2xx) tests or only negative ones?¶
Negative (4xx) tests by default. Set includeValidCase: true to add one baseline positive case named "Test Valid Case" per operation. See Positive testing.
Does the generator call my API during generation?¶
No. Generation is offline: it parses the spec (a local file or a remote URL) and writes artifacts. Your API is only called when you run the generated tests.
Can I run the generated tests against a live server?¶
Yes — the RestAssured template sets take the target host from the baseUrl template variable, so point it at any environment. For data-driven suites, your own runner decides the target. See Generators.
Can I customize the generated test code?¶
Yes, at two levels: pass templateVariables to the built-in RestAssured template sets, or supply your own Mustache templates with customTemplateDir for full control over the output. See Custom Mustache templates.
How do I keep manual edits when the suites are regenerated?¶
With test-suite-writer, use writeMode: MERGE and list the fields you edited in protectedTestCaseFields. With the template generator, use writeMode: SKIP_IF_EXISTS to leave existing files untouched. See Merge semantics.
What does "Budget exceeded" mean?¶
A complexity limit (schema combinations or test cases per operation) was hit — a guard against combinatorial explosion on deeply composed schemas. Raise the limit the message names, simplify the schema, or exclude the operation. See Troubleshooting — Budget exceeded.
What happens when the YAML config file, CLI flags, and Gradle DSL disagree?¶
CLI flags and Gradle DSL values override the YAML config file. Nested maps are deep-merged; lists are replaced. See Configuration sources and precedence.
Which OpenAPI and Swagger versions are supported?¶
OpenAPI 3.0.x and 3.1.x directly; Swagger 2.0 through normalization to the OpenAPI 3 model. Swagger 1.x is rejected. Webhooks are parsed but not generated. See Supported specifications.
Can I use the generator programmatically from Kotlin or Java?¶
Yes — TestGenerationRunner from distribution-bundle is the high-level entry point; core's TestGenerationEngine gives lower-level control. See Distribution-bundle.
Is the output deterministic?¶
Yes: the same spec and settings always produce the same tests. Rules, providers, and modules are deterministically ordered, and value generation uses fixed seeds. See Architecture — determinism.