{"id":16866,"library":"oatts","title":"OpenAPI Test Templates Generator","description":"OATTS (OpenAPI Test Templates) is a utility designed to generate basic Node.js unit test scaffolding directly from an OpenAPI specification document. Currently at version 1.6.0, it provides both a command-line interface and a module API to automate the creation of boilerplate tests for your API endpoints. The generated tests are structured for the Mocha testing framework and utilize Chakram for API assertions, encouraging developers to maintain a consistent contract between their API specification and its implementation. While providing valuable scaffolding for early and continuous API contract testing, it's important to note that OATTS is described as a 'work in progress' and 'not an officially supported Google product', suggesting a less frequent release cadence and potentially limited long-term support compared to core Google projects. Its primary differentiator is its focus on generating runnable Mocha/Chakram tests specifically for Node.js environments, building on lessons learned from `swagger-test-templates`.","status":"maintenance","version":"1.6.0","language":"javascript","source_language":"en","source_url":"https://github.com/google/oatts","tags":["javascript","Swagger","OpenAPI","Test","API"],"install":[{"cmd":"npm install oatts","lang":"bash","label":"npm"},{"cmd":"yarn add oatts","lang":"bash","label":"yarn"},{"cmd":"pnpm add oatts","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import oatts from 'oatts';","symbol":"oatts (module)","correct":"const oatts = require('oatts');"},{"note":"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.","wrong":"import { generate } from 'oatts';","symbol":"generate (function)","correct":"const tests = oatts.generate('/path/to/openapi.yaml', options);"}],"quickstart":{"code":"const oatts = require('oatts');\nconst path = require('path');\nconst fs = require('fs');\n\n// Create a dummy OpenAPI spec for demonstration\nconst dummyOpenApiSpecPath = path.join(__dirname, 'dummy-openapi.yaml');\nconst dummyOpenApiSpecContent = `\nopenapi: 3.0.0\ninfo:\n  title: Dummy API\n  version: 1.0.0\nservers:\n  - url: http://localhost:3000\npaths:\n  /hello:\n    get:\n      summary: Greet the user\n      operationId: getHello\n      responses:\n        '200':\n          description: Successful response\n          content:\n            application/json:\n              schema:\n                type: object\n                properties:\n                  message:\n                    type: string\n  /goodbye/{name}:\n    parameters:\n      - name: name\n        in: path\n        required: true\n        schema:\n          type: string\n    get:\n      summary: Bid farewell\n      operationId: getGoodbye\n      responses:\n        '200':\n          description: Successful farewell\n          content:\n            application/json:\n              schema:\n                type: object\n                properties:\n                  farewellMessage:\n                    type: string\n`;\n\nfs.writeFileSync(dummyOpenApiSpecPath, dummyOpenApiSpecContent);\n\n// Options for test generation\nconst options = {\n  host: 'http://localhost:3000', // Target API host for generated tests\n  writeTo: path.join(__dirname, 'generated-tests'), // Directory to write tests\n  // You can specify specific paths: paths: '/hello,/goodbye/{name}'\n};\n\nconsole.log('Generating tests for dummy OpenAPI spec...');\n\n// Generate the tests\noatts.generate(dummyOpenApiSpecPath, options)\n  .then((generatedFiles) => {\n    console.log('Tests generated successfully:');\n    generatedFiles.forEach(file => console.log(`- ${file}`));\n    console.log(`\nTo run these tests, you'll need mocha and chakram installed:\n  npm install --save-dev mocha chakram\nThen, start your API server (if applicable) and run:\n  mocha --recursive ${options.writeTo}`);\n  })\n  .catch((error) => {\n    console.error('Error generating tests:', error);\n  })\n  .finally(() => {\n    // Clean up the dummy spec file and generated test directory\n    fs.unlinkSync(dummyOpenApiSpecPath);\n    // Note: Deleting the generated test directory is more complex and left out for quickstart clarity\n    // You might want to remove this for actual usage to inspect generated files.\n  });\n","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `mocha` and `chakram` are installed as development dependencies in your project: `npm install --save-dev mocha chakram`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to `oatts` version 1.3.0 or higher to ensure you benefit from these security fixes: `npm install oatts@latest`.","message":"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.","severity":"gotcha","affected_versions":"<1.3.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install `mocha` and `chakram` as development dependencies in your project's test environment: `npm install --save-dev mocha chakram`.","cause":"The generated tests require 'mocha' and 'chakram' to run, but these are not direct dependencies of the 'oatts' package itself.","error":"Error: Cannot find module 'mocha' (or 'chakram')"},{"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.","cause":"The `oatts` command-line interface (CLI) tool was either not installed globally or is not accessible in your system's PATH.","error":"oatts generate: command not found"},{"fix":"Ensure you are importing the module using the CommonJS `require` syntax: `const oatts = require('oatts');`. Then, call `oatts.generate(...)`.","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.","error":"TypeError: oatts.generate is not a function"},{"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.","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.","error":"Generated tests consistently fail with connection refused errors or unexpected HTTP status codes (e.g., 500, 404)."}],"ecosystem":"npm","meta_description":null}