This is documentation for the next version of Grafana k6 documentation. For the latest stable release, go to the latest version.

Using k6

Test authoring

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:

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:

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:

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:

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.

Options

You can use the following configuration options when running openapi-to-k6 in the CLI.

`--mode`

The --mode or -m option specifies the mode to be used when generating the client. The options are:

single: This is the default mode. It generates the TypeScript client with all the types and implementation as a single file.
split: This mode splits the types and implementation into separate files.
tags: This modes splits your OpenAPI definition based on the tags and generates a separate client for each tag. If a route has no tag set, the client is included in the default.ts file.

`--only-tags`

--only-tags filters the generated client to only include routes with specific tags from your OpenAPI definition. You can specify multiple tags to include routes matching any of those tags. Routes without tags are excluded. This is useful for generating focused clients that only contain the endpoints you need.

For example: openapi-to-k6 <path-to-openapi-schema> <output path> --only-tags ItemsHeader generates a client with only the routes that have the ItemsHeader tag. You can specify multiple tags by using multiple --only-tags flags or by separating them with spaces: --only-tags tag1 --only-tags tag2.

`--disable-analytics`

--disable-analytics disables anonymous usage analytics reporting. You can also use the DISABLE_ANALYTICS=true environment variable to turn off this feature.

`--include-sample-script`

--include-sample-script generates a sample k6 script. The generated sample script uses the examples defined in the OpenAPI definition requests to make the script usable out of the box. If the examples aren’t defined, it uses Faker to generate random data.