Swagger Test Code Generator

Common errors

• TypeError: stt is not a function

  cause The module was imported incorrectly, likely using named import syntax for a default export, or attempting to call a property instead of the root function.
  fix For CommonJS, use `const stt = require('swagger-test-templates');`. For ESM, use `import stt from 'swagger-test-templates';`. Then call `stt(swagger, config);`.

• Error: 'assertionFormat' is required

  cause The `assertionFormat` property was either missing or undefined in the configuration object passed to `stt`.
  fix Add a valid `assertionFormat` property (e.g., 'should', 'expect', or 'assert') to your configuration object: `config: { assertionFormat: 'should', ... }`.

• Error: 'testModule' is required

  cause The `testModule` property was either missing or undefined in the configuration object.
  fix Add a valid `testModule` property (e.g., 'supertest' or 'request') to your configuration object: `config: { testModule: 'supertest', ... }`.

• Generated test files contain 'undefined' for request bodies/parameters.

  cause The `requestData` object provided in the configuration does not match the expected nested structure or the Swagger schema for the operation.
  fix Verify that your `requestData` object precisely follows the `/endpoint -> operation -> responseCode -> array of data` format, and that the data objects themselves contain the correct keys for parameters or the `body` property for request bodies.

Warnings

• breaking This library explicitly supports Swagger Specification version 2.0. It does not support OpenAPI Specification versions 3.x or later. Attempting to use a 3.x spec will lead to generation failures or incorrect tests.
  Fix: Ensure your API specification is in Swagger 2.0 format. For OpenAPI 3.x, consider alternative test generation tools or manual conversion.
• gotcha When providing a `templatesPath` for custom Handlebars templates, it functions as an 'all-or-nothing' path. You must copy all default templates to your custom directory; the library does not merge custom templates with its built-in ones.
  Fix: If using `templatesPath`, ensure your custom directory contains all necessary Handlebars templates (e.g., base-test.js.handlebars, request-test.js.handlebars, load-test.js.handlebars) or your generated tests may be incomplete.
• gotcha The `requestData` option requires a precise nested object structure matching `/endpoint -> operation -> responseCode -> array of data objects`. Incorrect structuring will result in generated tests sending empty or malformed request bodies/parameters.
  Fix: Carefully review the `requestData` structure in the documentation, ensuring keys for path, operation, and response code, along with an array of objects containing `body` (for HTTP body) or parameter keys (for path/query params).
• gotcha The `pathName` configuration option expects an array of specific paths. If an empty array `[]` is provided, the library will generate tests for *all* paths defined in the Swagger specification, which might be unintended for large APIs.
  Fix: Explicitly list the paths you wish to test in the `pathName` array. If you truly want all paths, document this choice clearly in your configuration.

Install

• npm install swagger-test-templates npm
• yarn add swagger-test-templates yarn
• pnpm add swagger-test-templates pnpm

Imports

• stt
  wrong:

  import { testGen } from 'swagger-test-templates';

  correct:

  import stt from 'swagger-test-templates';

  The library primarily exports a single default function. While `require` is shown in examples, ESM import syntax is typically `import stt from 'package-name'` for default exports.
• require('swagger-test-templates')

  const stt = require('swagger-test-templates');

  This is the CommonJS import pattern shown in the official documentation and example usage, suitable for Node.js environments.
• testGen
  wrong:

  const tests = stt.testGen(swagger, config);

  correct:

  const tests = stt(swagger, config);

  The `swagger-test-templates` module exports its primary function directly as the default export, so you call the imported module reference directly like a function, not a property of it.

Quickstart

This quickstart demonstrates how to initialize `swagger-test-templates` with a mock Swagger 2.0 spec and configuration, generating test files for specified paths and including basic load test setup.

const stt = require('swagger-test-templates');
const fs = require('fs');

// In a real scenario, replace this with a path to your actual Swagger 2.0 JSON file
const swaggerSpec = {
  "swagger": "2.0",
  "info": {"title": "Test API", "version": "1.0.0"},
  "paths": {
    "/user": {
      "get": {
        "responses": {
          "200": {"description": "OK"}
        }
      }
    },
    "/user/{id}": {
      "parameters": [{
        "name": "id",
        "in": "path",
        "required": true,
        "type": "string"
      }],
      "get": {
        "responses": {
          "200": {"description": "OK"}
        }
      }
    }
  }
};

const config = {
  assertionFormat: 'should',
  testModule: 'supertest',
  pathName: ['/user', '/user/{id}'],
  pathParams: {
    "id": "0123"
  },
  // Example of a load test configuration for a specific path/operation
  loadTest: [{
    pathName: '/user',
    operation: 'get',
    load: {requests: 100, concurrent: 10}
  }]
};

// Generates an array of objects containing the test file content and name
const tests = stt(swaggerSpec, config);

// Iterate through generated tests and print them (or write to files)
tests.forEach(testFile => {
  console.log(`--- Test File: ${testFile.name} ---\n`);
  console.log(testFile.test);
  // Example: Writing to a file
  // fs.writeFileSync(`${testFile.name}`, testFile.test);
});