Test authoring on Grafana Labs

Create a test script using the CLI

Mon, 21 Sep 2026 15:16:28 +0000

Create a test script using the CLI

Writing a k6 test script from scratch can seem challenging if you’re just getting started with k6, or repetitive if you’re already familiar with the tool. The k6 new command can help both new and experienced users quickly generate a test script, which they can use to try out k6, or use as a starting point to test out their applications and services.

Before you begin

To use the k6 new command, you’ll need:

k6 v0.57 or higher installed on your machine.
Custom templates require k6 v1.0.0-rc1 or higher.

Use the k6 new command

To create a script with the k6 new command, run the following in your terminal:

k6 new

The command creates a k6 test script file named script.js in the current directory.

You can customize the script filename by passing the name as an argument. For example, to create a script named test.js:

k6 new test.js

Options

You can customize the generated script using the following options: --template and --project-id.

–template

The --template flag allows you to specify a template that best fits your use case.

The options are:

minimal: Creates a minimal test script with a short options configuration, and a single request and check example. This is the default option.
protocol: Creates a script that includes environment variables, stages with different durations and VUs, thresholds, and a setup function. This is ideal for learning, and as a good starting point for real-world scenarios.
browser: Creates a browser script that checks if a websites successfully loaded, looks for elements on the screen, and takes a screenshot. Similar to the protocol option, this is ideal for learning, and a good starting point for creating browser tests.
An absolute or a relative path to a local file, such as ./my-template.js or /path/to/my-template.js to use a custom template. k6 uses Go templating syntax to render the script.

To generate a script using a template, run:

k6 new --template protocol

–project-id

The --project-id flag allows you to specify a Grafana Cloud k6 project ID. The generated script is then configured to run in that project. To include the project ID in your custom template, use {{ .ProjectID }} as a placeholder, for example:

export default function () {
  console.log('Hello from project {{ .ProjectID }}!');
}

To use the project ID flag, run:

k6 new --project-id 12345

Note
To run your test in a specific Grafana Cloud k6 project, you need a Grafana Cloud account with access to that project.

To learn more about Grafana Cloud k6, refer to Grafana Cloud k6 documentation.

Create a test script from an OpenAPI definition file

Mon, 21 Sep 2026 15:16:28 +0000

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 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.

`--verbose`

--verbose or -v enables verbose logging to show a more detailed logging output.

`--help`

--help or -h displays the openapi-to-k6 help message, including a list of all available configuration options.

Test builder

Mon, 21 Sep 2026 15:16:28 +0000

Test builder

The k6 Test Builder provides a graphical interface to generate a k6 test script based on your input. Then, you can copy the test script and run the test from the CLI.

Though we strongly believe that scriptable, code-based tools will help you get the most out of your performance-testing efforts, a GUI-based tool like the test builder could help you:

Speed up the test creation.
Learn the k6 API quickly.
Collaborate with non-coders to build tests.

The k6 Test Builder is free to use and is available in:

Grafana Cloud k6

Create tests from recordings

Mon, 21 Sep 2026 15:16:28 +0000

Create tests from recordings

A recording stores the sequence of requests and parameters of a user session or API interaction. You can use this recording to auto-generate your test logic.

Testers commonly use recordings to avoid writing complex tests from scratch. For example, testing advanced scenarios on websites or mobile applications, such as end-to-end (E2E) tests with dozens or hundreds of requests.

k6 provides two tools that can convert a recording into a k6 script:

Grafana k6 Studio is an open-source desktop application designed to help you record browser interactions and generate k6 test scripts.
HAR converter generates a k6 script from the requests included in a HAR file.

Steps

The steps to create a load test from a recording are as follows:

Record a user or API session.
Convert the recorded session into a test.
Set up the load and test options.
Handle correlation and dynamic data.

You can then debug or run the load test.

Be sure to record realistically

If you use a browser to simulate a user session and generate its recording, consider the following dos and don’ts.

It’s a good idea to:

Browse as a user would.
Take natural pauses that users would take to consume page content.
Focus on the most common use cases, rather than all the possible use cases.
Take note of pages where forms/logins occur. You will need to edit the script to handle correlation.

You probably do not want to:

Visit every page in one journey.
Click every possible option.
Navigate as fast as you can.
Navigate out of your actual site or application.

Consider hybrid approach for load testing websites

When you start the recording and navigate as a user, the recorder captures every HTTP(s) request loaded into the browser as you click. This includes all the requests for third-party services, ads, images, documents, etc.

When you finish the recording, the converter generates the k6 script from all the recorded requests and assets. The script could include dozens or hundreds of requests for each page visit or interaction.

These types of recorded tests are difficult to maintain. As the website changes, these tests must be updated to reflect assets and API changes.

An alternative approach to load test websites is to run a hybrid load test which:

Runs a browser test to validate the frontend.
While simultaneously running API tests to inject load to the backend.

As the browser test automatically handles website assets, these tests require fewer updates.

To learn more about this approach, check out the example mixing browser-level and protocol-level tests.