Menu
Documentationbreadcrumb arrow Grafana k6breadcrumb arrow Using k6breadcrumb arrow Test authoringbreadcrumb arrow Create a test script from an OpenAPI definition file
Open source

Create a test script from an OpenAPI definition file

Creating a k6 test script from scratch requires some JavaScript/TypeScript knowledge, as well as understanding k6 concepts such as the test lifecycle and k6 JavaScript APIs.

The OpenAPI specification has become popular over the years and is commonly used across development teams. It lets developers create a schema that includes details about an API, including authentication methods, endpoints, responses, and more. Once teams have an OpenAPI definition file, they can also use third-party tools to automatically create documentation, integrate with testing tools, or create mock servers.

The openapi-to-k6 project lets you use an existing OpenAPI schema to generate a TypeScript client that can be used to quickly test API endpoints with k6. The generated client exports a class with methods for each endpoint in the OpenAPI schema. You can import the client into your script, create an instance of the class, and use the methods to call any endpoints.

In this guide, you’ll learn how to use the openapi-to-k6 project to generate a client and a sample script, and run the sample script to test your API endpoints.

Before you begin

To use openapi-to-k6, you’ll need to:

You’ll also need an OpenAPI definition file, or the URL to an OpenAPI definition file. openapi-to-k6 supports JSON and YAML files.

Install openapi-to-k6

To install openapi-to-k6, open your terminal and run:

Bash 
npm install -g @grafana/openapi-to-k6

That installs openapi-to-k6 globally in your system. You can then run the following command to check that it was installed correctly:

Bash 
openapi-to-k6 --version

Generate a client from an OpenAPI schema

To generate a client using openapi-to-k6, you’ll need an OpenAPI definition file in your system or a URL to an OpenAPI definition file. Open your terminal application and run:

Bash 
openapi-to-k6 --include-sample-script <OPENAPI_SCHEMA_PATH | OPENAPI_SCHEMA_URL> <OUTPUT_PATH>

Make sure to replace:

  • <OPENAPI_SCHEMA_PATH | OPENAPI_SCHEMA_URL> with the path or URL for your OpenAPI definition file.
  • <OUTPUT_PATH> with the path where you want the generated client to be saved.

In the output path, you’ll see two generated TypeScript files:

  • <OPENAPI_TITLE>.ts - the generated client uses the title property from the OpenAPI schema as its name. You can import this file into a k6 test script, and then generate scripts using specific endpoints you want to test.
  • script.sample.ts - the sample script generated by openapi-to-k6. This script is an example of how to import and use the generated client in a k6 test script.

Run the sample test script

You can run the generated test script with k6. Open your terminal, and run:

Bash 
k6 run script.sample.ts

Make sure to replace script.sample.ts with the name of your generated test script. Depending on the API you’re testing and the OpenAPI schema that you’re using, you may need to edit the TypeScript file to update any authentication parameters or headers to run the test script successfully.