Skip to content

Test-suite-writer generator (test-suite-writer)

This page describes the built-in test-suite-writer generator and how it writes JSON/YAML TestSuite files.

For core entry points and extension context, see the core module. For distribution defaults and wiring, see distribution settings. For configuration via YAML, see YAML config.

Output behavior

TestSuiteWriter writes test suites as JSON or YAML. It is stateful and not thread-safe. Create a new instance per generation run.

Output modes:

  • SINGLE_FILE: aggregate all suites into a single file keyed by operation name.
  • MULTIPLE_FILES: write one file per suite (prefix + operation name + extension).

Write modes:

  • writeMode = OVERWRITE: overwrite output for suites generated in the current run.
  • writeMode = MERGE (default): load existing output and merge by suite operationName and test case name.

Merge behavior (when writeMode = MERGE): see Generator options for the canonical semantics (suite/case overwrite flags, protected fields, and atomic writes).

Options

See Generator options for the authoritative list of supported options and defaults.

Commonly used options:

  • outputFileName (for SINGLE_FILE)
  • format (JSON / YAML)
  • writeMode (MERGE / OVERWRITE)
  • outputMode (SINGLE_FILE / MULTIPLE_FILES)

Extending generators

To add a custom generator (new generator id), see Custom generators and Custom modules.

Output structure

The test-suite-writer generator outputs test suites keyed by operation name. Each suite contains the path, method, operation name, and an array of test cases.

Example output

{
  "getUser": {
    "path": "/users/{userId}",
    "method": "GET",
    "operationName": "getUser",
    "testCases": [
      {
        "name": "Invalid Path userId parameter: Invalid Pattern",
        "method": "GET",
        "path": "/users/{userId}",
        "pathParams": { "userId": "AE." },
        "headers": [{ "key": "X-API-Key", "value": "test-api-key-123" }],
        "expectedStatusCode": 400,
        "rule": "...InvalidPatternSchemaValidationRule"
      }
    ]
  }
}

Query parameter encoding

The queryParams field uses structured values. Your test runner should serialize objects according to the parameter's style and explode settings from the OpenAPI spec.

For detailed field definitions, types, and complete examples, see:

Output location

  • SINGLE_FILE mode: {outputDir}/{outputFileName} (e.g., ./build/generated/test-suites.json)
  • MULTIPLE_FILES mode: {outputDir}/{fileNamePrefix}{operationName}.{format} per operation