OAT
===

> (greatest) Open Api Test library of all times!

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![bundle][bundle-src]][bundle-href]
[![JSDocs][jsdocs-src]][jsdocs-href]
[![License][license-src]][license-href]

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:

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

import { specification } from './openapi-specification.json' with { 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 theoperationId"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:

`sh npm i oat``

Documentation

For more details on how to use Oat, check out our documentation.

License

[npm-version-src]: https://img.shields.io/npm/v/oat?style=flat&colorA=080f12&colorB=1fa669
[npm-version-href]: https://npmjs.com/package/oat
[npm-downloads-src]: https://img.shields.io/npm/dm/oat?style=flat&colorA=080f12&colorB=1fa669
[npm-downloads-href]: https://npmjs.com/package/oat
[bundle-src]: https://img.shields.io/bundlephobia/minzip/oat?style=flat&colorA=080f12&colorB=1fa669&label=minzip
[bundle-href]: https://bundlephobia.com/result?p=oat
[license-src]: https://img.shields.io/github/license/vollq-ai/oat.svg?style=flat&colorA=080f12&colorB=1fa669
[license-href]: https://github.com/vollq-ai/oat/blob/main/LICENSE
[jsdocs-src]: https://img.shields.io/badge/jsdocs-reference-080f12?style=flat&colorA=080f12&colorB=1fa669
[jsdocs-href]: https://www.jsdocs.io/package/oat

Example

The following example shows a simple API test using Vitest:

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

import { specification } from './openapi-specification.json' with { 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.

License