Skip to main content

Oat

(greatest) Open Api Test library of all times!

npm version npm downloads bundle JSDocs License

The oat package makes it very easy to test your API with an OpenAPI specification. It:

  • 🤝 validates request and response parameter
  • 🧬 generates multiple tests based on different security or parameter combinations
  • 🧩 is compatible to all JavaScript testrunner
  • 🚀 integration to Faker.js for easy payload generation
  • ⚡ supports referencing response values from other API tests

Example​

The following example shows a simple API test using Vitest:

import { describe, it } from 'vitest'
import { Testplan, URLParam, APIKeyAuth, QueryParam } from 'oat'
import type { OpenAPIV3 } from 'openapi-types'

import { specification } from './openapi-specification.json' assert { type: 'json' }

const urlParam = new URLParam({ id: '39f07889-1072-48df-8ca6-9d6726b5e525' })
const apiToken = new APIKeyAuth('Authorization', 'vollq-b82b312d-4d44-40a3-bb5a-02529417e2d7', 'header')
const userQuery = new QueryParam({
  /**
   * resolves to the body value with the JSON path "specification.owner" of the first 200 response of
   * request with the `operationId` "getUsers", e.g. in this example the owner of the specification
   */
  name: '#/getSpecification/200/body/specification.owner'
})

const plan = new Testplan(specification as OpenAPIV3.Document)
plan.usingServer('http://api.server.com')

describe('/api/specifications/{id}', () => {
  plan.runTest('delete', '/api/specifications/{id}')
    .withPayloads(urlParam)
    .expect(401) // fails due to missing auth
  plan.runTest('get', '/api/specifications/{id}')
    .withSecuritySchemes([apiToken])
    .withPayloads(urlParam)
    .expect(200)
  plan.runWith(it)
})

describe('/api/users/{id}', () => {
  plan.runTest('get', '/api/users')
    .withSecuritySchemes([apiToken])
    .withPayloads(userQuery)
    .expect(200)
  plan.runWith(it)
})

The Oat library is can be used with any TDD test framework, e.g. Mocha, Jasmine, Jest, Node Tap or the built-in Node.js testrunner.

Install​

Install the package via:

npm i oat

Classes​

The following primitives are available for composing your API tests.

  • Testplan: composes one or multiple API tests based on provided security schemas and payload
  • Test: represents one or multiple API request to a certain endpoint
  • Payload: represents a payload for an API request, e.g. query or url parameter as well as body payloads
  • Auth: represents an auth mechanism for an API request, e.g. Basic Auth, Bearer Auth or custom headers