OpenAPI Test Templates Generator

Common errors

• Error: Cannot find module 'mocha' (or 'chakram')

  cause The generated tests require 'mocha' and 'chakram' to run, but these are not direct dependencies of the 'oatts' package itself.
  fix Install `mocha` and `chakram` as development dependencies in your project's test environment: `npm install --save-dev mocha chakram`.

• oatts generate: command not found

  cause The `oatts` command-line interface (CLI) tool was either not installed globally or is not accessible in your system's PATH.
  fix Install the `oatts` CLI globally using `npm install -g oatts`, or execute the command directly using `npx oatts generate ...` if you prefer not to install globally.

• TypeError: oatts.generate is not a function

  cause This error typically occurs if `oatts` was imported incorrectly (e.g., attempting a named import when only a CommonJS default export exists) or if the module resolution failed.
  fix Ensure you are importing the module using the CommonJS `require` syntax: `const oatts = require('oatts');`. Then, call `oatts.generate(...)`.

• Generated tests consistently fail with connection refused errors or unexpected HTTP status codes (e.g., 500, 404).

  cause The API server that the generated tests are configured to target is either not running, inaccessible from the test environment, or the `--host` option (or default host) used during test generation does not match the server's actual address.
  fix Start your API server before running the generated tests. Verify that the `host` option supplied to `oatts.generate` (or the `--host` CLI option) correctly points to your running API's address and port.

Warnings

• gotcha This project is explicitly noted as 'not an officially supported Google product' and 'a work in progress'. Users should be aware this implies potential for limited long-term support, infrequent updates, and the possibility of API changes without strict adherence to semantic versioning guidelines.
  Fix: Factor this disclaimer into project adoption decisions; consider maintaining a local fork for critical projects that require long-term stability or specific feature sets.
• gotcha The unit tests generated by `oatts` are designed to run with the `mocha` testing framework and rely on `chakram` for API assertions. These frameworks are not direct dependencies of `oatts` itself and must be installed separately in your test environment for the generated tests to execute successfully.
  Fix: Ensure `mocha` and `chakram` are installed as development dependencies in your project: `npm install --save-dev mocha chakram`.
• gotcha The official documentation and examples for `oatts` exclusively use CommonJS (`require()`) syntax. While Node.js has robust ESM support, direct native ES Module (`import`) usage for the `oatts` library itself is not explicitly supported and may lead to import resolution errors or unexpected behavior.
  Fix: Consistently use `const oatts = require('oatts');` for importing the module in your Node.js applications. If using ESM in your project, `oatts` might need to be dynamically imported or bundled with a tool that handles CJS-to-ESM conversion.
• gotcha When providing custom Handlebars templates for test generation, the directory specified must contain exactly four templates with specific predefined names to be correctly recognized by `oatts`. Deviations from this naming convention will result in templates not being applied.
  Fix: Refer to the `oatts` documentation or the `templates` directory within the `oatts` source code for the exact required names and structure of custom Handlebars templates.
• gotcha Version 1.3.0 of `oatts` included fixes for 'vulnerabilities per GitHub scanning'. While these issues have been addressed in later versions, it indicates that earlier versions (prior to 1.3.0) may have contained security vulnerabilities. Users should prioritize updating.
  Fix: Upgrade to `oatts` version 1.3.0 or higher to ensure you benefit from these security fixes: `npm install oatts@latest`.

Install

• npm install oatts npm
• yarn add oatts yarn
• pnpm add oatts pnpm

Imports

• oatts (module)
  wrong:

  import oatts from 'oatts';

  correct:

  const oatts = require('oatts');

  The library is primarily designed for CommonJS (CJS) environments, as indicated by all documentation examples. Direct native ES Module (ESM) `import` may not work without a transpiler or specific Node.js configuration, and is not officially supported.
• generate (function)
  wrong:

  import { generate } from 'oatts';

  correct:

  const tests = oatts.generate('/path/to/openapi.yaml', options);

  The `generate` function is accessed as a property of the main `oatts` module object, not as a named export. Ensure the module is imported correctly via CommonJS first.

Quickstart

This quickstart demonstrates how to programmatically use `oatts` to generate unit test scaffolding for a simple OpenAPI specification, writing them to a specified directory. It includes cleanup for the dummy spec.

const oatts = require('oatts');
const path = require('path');
const fs = require('fs');

// Create a dummy OpenAPI spec for demonstration
const dummyOpenApiSpecPath = path.join(__dirname, 'dummy-openapi.yaml');
const dummyOpenApiSpecContent = `
openapi: 3.0.0
info:
  title: Dummy API
  version: 1.0.0
servers:
  - url: http://localhost:3000
paths:
  /hello:
    get:
      summary: Greet the user
      operationId: getHello
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
  /goodbye/{name}:
    parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
    get:
      summary: Bid farewell
      operationId: getGoodbye
      responses:
        '200':
          description: Successful farewell
          content:
            application/json:
              schema:
                type: object
                properties:
                  farewellMessage:
                    type: string
`;

fs.writeFileSync(dummyOpenApiSpecPath, dummyOpenApiSpecContent);

// Options for test generation
const options = {
  host: 'http://localhost:3000', // Target API host for generated tests
  writeTo: path.join(__dirname, 'generated-tests'), // Directory to write tests
  // You can specify specific paths: paths: '/hello,/goodbye/{name}'
};

console.log('Generating tests for dummy OpenAPI spec...');

// Generate the tests
oatts.generate(dummyOpenApiSpecPath, options)
  .then((generatedFiles) => {
    console.log('Tests generated successfully:');
    generatedFiles.forEach(file => console.log(`- ${file}`));
    console.log(`
To run these tests, you'll need mocha and chakram installed:
  npm install --save-dev mocha chakram
Then, start your API server (if applicable) and run:
  mocha --recursive ${options.writeTo}`);
  })
  .catch((error) => {
    console.error('Error generating tests:', error);
  })
  .finally(() => {
    // Clean up the dummy spec file and generated test directory
    fs.unlinkSync(dummyOpenApiSpecPath);
    // Note: Deleting the generated test directory is more complex and left out for quickstart clarity
    // You might want to remove this for actual usage to inspect generated files.
  });