Testplan

A test plan composes one or multiple API tests based on provided security schemas and payload. To create an instance pass in an OpenAPI v3 specification as payload.

const plan = new Testplan(specification)

Methods

runTest

Creates a test penetrating a specific endpoint that can be contain different security schemas or payloads. The method returns an instance of a Test.

plan.runTest('get', '/api/specifications/{id}')

usingServer

Select a server from the specification to run the test agains, e.g. given the following server defintion:

{
  "servers": [
    {
      "url": "https://staging.gigantic-server.com/v1",
      "description": "Staging server"
    },
    {
      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
      "description": "The production API server",
      "variables": {
        "username": {
          "default": "demo",
          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
        },
        "port": {
          "enum": [
            "8443",
            "443"
          ],
          "default": "8443"
        },
        "basePath": {
          "default": "v2"
        }
      }
    }
  ]
}

You can select a server either via the index or the URL, e.g.:

plan.usingServer(0) // selects Staging server
plan.usingServer('https://staging.gigantic-server.com/v1')  // selects custom server
plan.usingServer(1, { username: 'demo', port: '8443', basePath: 'v2' }) // selects server with parameter

runWith

Test function of the test framework of your choice, e.g. Vitest, Mocha etc. The provided test function should match the following interface:

type FrameworkFn = ((title: string, fn: (() => void)) => unknown)
type FrameworkAPI = FrameworkFn & {
  only?: FrameworkFn
  skip?: FrameworkFn
}

For above mentioned frameworks, it would be simply:

import { describe, it } from 'vitest'

plan.runWith(it)

Hooks

Every test plan allows to register hooks to execute synchronous or asynchronous code at different lifecycle moments of a test.

beforeRequest

The beforeRequest hook will be executed before a test, there therefore a request is being made. It allows to modify the request url and payload.

Type: (options: { url: string, requestInit: RequestInit }) => void | Promise<void>

Example:

const plan = new Testplan(specification, {
  /**
   * set custom test header
   */
  beforeRequest: async ({ url, options }) => {
    (options.headers as Record<string, string>)['x-test-api'] = '1'
  }
})

afterResponse

The afterResponse hook allows you to modify the response before it is processed and validated, e.g. to log the response.

Type: (options: { url: string, requestInit: RequestInit }) => void | Promise<void>

Example:

const plan = new Testplan(specification, {
  /**
   * set custom test header
   */
  afterResponse: async (response, { url, options }) => {
    console.log(`Received response from ${url} with status ${response.status}`)
  }
})