Get started on Grafana Labs

Write your first test

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

Write your first test

k6 is a reliability testing tool. It helps developers simulate realistic user behavior and test how their systems behave as a result. Writing tests in k6 allows you to identify potential issues, such as slow response times or system failures, before they occur in production.

The goal of your test can vary. You might want to check performance, reliability, or scalability. Depending on your goal, your script may need different configurations, such as simulating many users, or running tests for a long time.

k6 tests are written using the JavaScript or TypeScript programming language, making it accessible to developers, and easy to integrate in existing codebases and projects. By writing k6 test scripts, you control what the k6 does, the action it performs, and how it behaves.

Follow along and learn how to write your first test script, and start testing the reliability of your application.

Start your learning experience with Grafana Learning Paths

Grafana Learning Paths provide a clear, structured path that leads you from beginner concepts to advanced use cases. Learn about this Grafana feature on Run your first k6 performance test.

Start learning

Before you start

To write k6 scripts, you’ll need:

A basic knowledge of JavaScript or TypeScript.
- If you’re unfamiliar with these languages, check out k6 Studio, which helps users generate tests without writing code. Alternatively, explore our test authoring methods.
Install k6 in your machine.
A code editor to write your scripts, such as Visual Studio Code or JetBrains editors.
- Refer to Configure your code editor to learn how to enable auto-completion and other features.

Basic structure of a k6 test

For k6 to be able to interpret and execute your test, every k6 script follows a common structure, revolving around a few core components:

Default function: This is where the test logic resides. It defines what your test will do and how it will behave during execution. It should be exported as the default function in your script.
Imports: You can import additional k6 modules or JavaScript libraries (jslibs) to extend your script’s functionality, such as making HTTP requests or simulating browser interactions. Note that k6 is not built upon Node.js, and instead uses its own JavaScript runtime. Compatibility with some npm modules may vary.
Options (optional): Enable you to configure the execution of the test, such as defining the number of virtual users, the test duration, or setting performance thresholds. Refer to Options for more details.
Lifecycle operations (optional): Because your test might need to run code before and/or after the execution of the test logic, such as parsing data from a file, or download an object from Amazon S3, lifecycle operations allow you to write code, either as predefined functions or within specific code scopes, that will be executed at different stages of the test execution.

Writing your first test script

Let’s walk through creating a simple test which performs 10 GET HTTP requests to a URL and waits for 1 second between requests. This script will help you understand the basic structure of a k6 test script.

Create a test file: A test file can be named anything you like, and live wherever you see fit in your project, but it should have a .js or .ts extension. In this example, create a JavaScript file named my-first-test.js. Open your terminal and run the following command:
Bash
```
touch my-first-test.js
```

Import k6 modules: As the end goal here is to perform HTTP requests, import the k6 http module at the top of the file. To help simulate a real-world scenario, import the sleep function from the k6 module as well.

// Import the http module to make HTTP requests. From this point, you can use `http` methods to make HTTP requests.
import http from 'k6/http';

// Import the sleep function to introduce delays. From this point, you can use the `sleep` function to introduce delays in your test script.
import { sleep } from 'k6';

Define options: To perform 10 HTTP requests, define an options block to configure the test execution. In this case, set the number of iterations to 10 to instruct k6 to execute the default function 10 times. Right beneath the imports, add the following code:
JavaScript
```
import http from 'k6/http';
import { sleep } from 'k6';

export const options = {
  // Define the number of iterations for the test
  iterations: 10,
};
```

Define a default function: The default exported function is the entry point for the test script. It will be executed repeatedly the number of times you define with the iterations option. In this function, make a GET request to a URL and introduce a 1-second delay between requests. Add the following code to your script:

import http from 'k6/http';
import { sleep } from 'k6';

export const options = {
  iterations: 10,
};

// The default exported function is gonna be picked up by k6 as the entry point for the test script. It will be executed repeatedly in "iterations" for the whole duration of the test.
export default function () {
  // Make a GET request to the target URL
  http.get('https://quickpizza.grafana.com');

  // Sleep for 1 second to simulate real-world usage
  sleep(1);
}

Extending your script

After you’re comfortable with this basic script, you can extend its functionality in many ways. Here are a few ideas to get you started:

Multiple requests: You can add more http.get() or http.post() requests to simulate complex user flows.
Using TypeScript: If you prefer TypeScript, k6 also supports it. You can learn more in our TypeScript guide.
Thresholds, checks, and metrics: You can add conditions to monitor performance. For example, you can set thresholds to ensure the response time doesn’t exceed a certain limit. Refer to Thresholds and Checks for more details.
Browser tests: Use the browser module to simulate user interactions like clicking buttons or filling out forms. This is useful for testing web applications. Refer to Using k6 browser for more details.

You can also use the k6 new command to speed up the process of putting together a k6 test script when you’re testing a new service or application. Try it out!

Next steps

Now that you’ve written your first k6 test script, it’s time to run it. Refer to Running k6 to learn how to execute your script and analyze the results.

Running k6

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

Running k6

Follow along to learn how to:

Run a test.
Add virtual users.
Increase the test duration.
Ramp the number of requests up and down as the test runs.

With these example snippets, you’ll run the test with your machine’s resources. But, if you have a k6 Cloud account, you can also use the k6 cloud run command to outsource the test to k6 servers.

Before you begin

Install k6 on your machine.

Run local tests

To run a simple local script:

Create and initialize a new script by running the following command:
linux
k6 new
docker
docker run --rm -u $(id -u) -v $PWD:/app -w /app grafana/k6 new
windows
docker run --rm -i -v ${PWD}:/app -w /app grafana/k6 new
This command creates a new script file named script.js in the current directory. You can also specify a different file name as an argument to the k6 new command, for example k6 new my-test.js.

Run k6 with the following command:

k6 run script.js

# When using the `k6` docker image, you can't just give the script name since
# the script file will not be available to the container as it runs. Instead
# you must tell k6 to read `stdin` by passing the file name as `-`. Then you
# pipe the actual file into the container with `<` or equivalent. This will
# cause the file to be redirected into the container and be read by k6.

docker run --rm -i grafana/k6 run - <script.js

cat script.js | docker run --rm -i grafana/k6 run -

Add VUs

Now run a load test with more than one virtual user and a longer duration:

k6 run --vus 10 --duration 30s script.js

docker run --rm -i grafana/k6 run --vus 10 --duration 30s - <script.js

cat script.js | docker run --rm -i grafana/k6 run --vus 10 --duration 30s -

Running a 30-second, 10-VU load test

Note
k6 runs multiple iterations in parallel with virtual users (VUs). In general terms, more virtual users means more simulated traffic.

VUs are essentially parallel while(true) loops. Scripts are written in JavaScript, as ES6 modules, so you can break larger tests into smaller pieces or make reusable pieces as you like.

The init context and the default function

For a test to run, you need to have init code, which prepares the test, and VU code, which makes requests.

Code in the init context defines functions and configures the test options (like duration).

Every test also has a default function, which defines the VU logic.

// init

export default function () {
  // vu code: do things here...
}

Init code runs first and is called only once per VU. The default code runs as many times or as long as is configured in the test options.

To learn more about how k6 executes, read about the Test lifecycle.

Set options

Instead of typing --vus 10 and --duration 30s each time you run the script, you can set the options in your JavaScript file:

import http from 'k6/http';
import { sleep } from 'k6';
export const options = {
  vus: 10,
  duration: '30s',
};
export default function () {
  http.get('http://test.k6.io');
  sleep(1);
}

If you run the script without flags, k6 uses the options defined in the script:

k6 run script.js

docker run --rm -i grafana/k6 run - <script.js

cat script.js | docker run --rm -i grafana/k6 run -

Ramp VUs up and down in stages

You can ramp the number of VUs up and down during the test. To configure ramping, use the options.stages property.

import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  stages: [
    { duration: '30s', target: 20 },
    { duration: '1m30s', target: 10 },
    { duration: '20s', target: 0 },
  ],
};

export default function () {
  const res = http.get('https://quickpizza.grafana.com/');
  check(res, { 'status was 200': (r) => r.status == 200 });
  sleep(1);
}

For more granular ramp configuration, you can use scenarios and the ramping-vus executor.

Execution modes

Note
Portability is a major design goal of k6.

You can run the same test in different modes with minimal changes.

k6 supports three execution modes to run a k6 test: local, distributed, and cloud.

Local: the test execution happens entirely on a single machine, container, or CI server.
Bash
```
k6 run script.js
```

Distributed: the test execution is distributed across a Kubernetes cluster.

Save the following YAML as k6-testrun-resource.yaml:

---
apiVersion: k6.io/v1alpha1
kind: TestRun
metadata:
  name: k6-sample
spec:
  parallelism: 4
  script:
    configMap:
      name: 'k6-test'
      file: 'script.js'

Apply the resource with the following command:

kubectl apply -f /path/to/k6-testrun-resource.yaml

Cloud: the test runs on Grafana Cloud k6.
Bash
```
k6 cloud run script.js
```
Additionally, cloud-based solutions can run cloud tests on your own cloud infrastructure, and accept the test results from a local or distributed test.

Results output

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

Results output

As k6 generates load for your test, it also makes metrics that measure the performance of the system. Broadly, you can analyze metrics in two ways:

As summary statistics, in an end-of-test summary report.
In granular detail, with measurements for every data point across test (and timestamps)

You can customize almost every aspect of result output:

Create custom metrics
Configure new summary statistics and print them to any text format.
Stream the results to one or multiple services of your choice (for example, InfluxDB or Prometheus).

Metrics

Documentation: Using metrics

k6 comes with built-in metrics about the test load and the system response. Key metrics include:

http_req_duration, the end-to-end time of all requests (that is, the total latency)
http_req_failed, the total number of failed requests
iterations, the total number of iterations

End-of-test summary

Documentation: End-of-test summary

By default, k6 prints summarized results to stdout.

When you run a test, k6 outputs a plain-text logo, your test progress, and some test details. After the test finishes, k6 prints the full details and summary statistics of the test metrics.

The end-of-test summary shows aggregated statistical values for your result metrics, including:

Median and average values
Minimum and maximum values
p90, p95, and p99 values

You can configure the statistics to report with the --summary-trend-stats option. For example, this command displays only median, p95, and p99.9 values.

k6 run --iterations=100 --vus=10 \
--summary-trend-stats="med,p(95),p(99.9)" script.js

Custom reports with `handleSummary()`

For completely customized end-of-summary reports, k6 provides the handleSummary() function.

At the end of the test, k6 automatically creates an object with all aggregated statistics. The handleSummary() function can process this object into a custom report in any text format: JSON, HTML, XML, and whatever else.

Time series and external outputs

Documentation: Real-time metrics

The condensed end-of-test summary provides a top-level view of the test. For deeper analysis, you need to look at granular time-series data, which has metrics and timestamps for every point of the test.

You can access time-series metrics in two ways:

Write them to a JSON or CSV file.
Stream them to an external service.

In both cases, you can use the --out flag and declare your export format as the flag argument. If you want to send the metrics to multiple sources, you can use multiple flags with multiple arguments:

k6 run \
--out json=test.json \
--out influxdb=http://localhost:8086/k6

The available built-in outputs include:

k6 resources

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

k6 resources

The docs aim to cover everything necessary to use the core k6 products in your daily operational work. But scripting and testing are skills that take time to learn. What’s more, k6 is an extensible tool, already incorporated with many other functionalities and protocols.

These resources help you write and run k6 tests in a safe environment and explore how to use k6 with other applications.

Learning

Getting started with k6 performance testing. A Learning Hub course that walks you from your first script to automated baselines with Grafana Cloud.
Run your first k6 performance test. A hands-on learning path to write, run, and analyze your first test.
Get started with k6 tutorial. The getting started tutorial provides some procedures for common real-life uses of k6 and does not require prior knowledge of k6 or JavaScript.
k6 Learn. A repository with a course and a ton of learning resources.
k6 OSS workshop. A 2-3 hour k6 workshop with practical k6 examples using the QuickPizza demo app.
k6 YouTube channel. Office hours, specific playlists, and other interesting videos from the community.
Awesome k6. A list of awesome stuff about k6.
Examples. A directory full of example k6 scripts for different use cases.

Community

The Grafana k6 community forum. Get support from the k6 team and community.

Test servers

If you need a place to learn k6 and test your scripts, you can use these demo applications:

grafana/quickpizza. A demo web application.

Note
These are testing environments shared by everyone - avoid high-load tests.

If you want to run tests with high loads, you can deploy and host them on your infrastructure and run the examples in the repository.

k6 + your favorite tool

Kubernetes Operator. Distribute test execution across a Kubernetes cluster.
xk6 extensions. Custom k6 binaries to support the tool you need.
Use TypeScript in k6 scripts
Integrations

Migrate to k6 v2

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

Migrate to k6 v2

This page covers all breaking changes introduced in k6 v2 and the steps to update your scripts, extensions, and configuration.

Go module path changed to `go.k6.io/k6/v2`

The k6 Go module path has changed from go.k6.io/k6 to go.k6.io/k6/v2.

If you maintain a k6 extension, update all import paths in your Go code:

// Before
import "go.k6.io/k6/js/modules"

// After
import "go.k6.io/k6/v2/js/modules"

Update your go.mod file and run go mod tidy after changing the import paths.

Removed CLI commands: `k6 pause`, `k6 resume`, `k6 scale`, `k6 status`

The pause, resume, scale, and status top-level CLI commands have been removed. There is no replacement — these commands relied on the externally-controlled executor, which has also been removed.

Removed `externally-controlled` executor

The externally-controlled executor has been removed. There is no replacement. Any test script with executor: externally-controlled will fail to start. Migrate to a different executor based on the desired load profile, for example ramping-vus, constant-vus, or constant-arrival-rate.

Removed CLI command: `k6 login`

The top-level k6 login command and its subcommands have been removed:

Replace k6 login cloud with k6 cloud login. Running it without arguments prompts you interactively for your token and stack:
Bash
```
k6 cloud login
```
k6 login influxdb has no replacement command. Configure the InfluxDB output directly using environment variables instead:
Bash
```
K6_INFLUXDB_ADDR=http://localhost:8086 k6 run --out influxdb script.js
```

Stack is now required for all `k6 cloud` commands

A Grafana Cloud stack must be provided for all k6 cloud commands. Run k6 cloud login once — it prompts interactively for your token and stack:

k6 cloud login

For non-interactive environments, pass the values via flags or the K6_CLOUD_STACK_ID environment variable, or set it in your script using the stackID option:

K6_CLOUD_TOKEN=<YOUR_API_TOKEN> K6_CLOUD_STACK_ID=<YOUR_STACK_ID> k6 cloud run script.js

Cloud run non-threshold aborts now exit with code 97

Previously, Grafana Cloud k6 runs aborted for reasons other than threshold violations (user abort, system error, timeout, script error) returned exit code 0. They now return exit code 97.

Scenario	Before	After
Finished	`0`	`0`
Aborted by threshold	`99`	`99`
Aborted by user, system, timeout, or script error	`0`	`97`

Review any CI pipeline logic that treats exit code 0 as an unconditional success for k6 cloud run — those checks now need to handle 97 as a distinct failure state.

`k6 cloud` positional argument removed

The old positional form k6 cloud script.js has been removed. Use the explicit subcommand instead:

k6 cloud run script.js

Removed `--upload-only` flag

The --upload-only flag has been removed. Use the k6 cloud upload command instead:

k6 cloud upload script.js

Removed `--no-summary` flag

The --no-summary flag has been removed. Use --summary-mode=disabled instead:

# Before
k6 run --no-summary script.js

# After
k6 run --summary-mode=disabled script.js

Removed `--summary-mode=legacy`

The legacy value for --summary-mode has been removed. The available modes are now compact (default), full, and disabled.

Removed `options.ext.loadimpact`

The options.ext.loadimpact configuration block has been removed. Use options.cloud instead:

// Before
export const options = {
  ext: {
    loadimpact: {
      name: 'My test name',
    },
  },
};

// After
export const options = {
  cloud: {
    name: 'My test name',
  },
};

Removed `k6/experimental/redis`

The k6/experimental/redis module has been removed. Use k6/x/redis instead:

// Before
import { Client } from 'k6/experimental/redis';

// After
import { Client } from 'k6/x/redis';

With automatic extension resolution, k6 provisions the xk6-redis extension automatically when it sees the k6/x/redis import — no manual binary build required.

OTel output: `K6_OTEL_EXPORTER_TYPE` renamed to `K6_OTEL_EXPORTER_PROTOCOL`

The accepted values are grpc and http/protobuf:

# Before
K6_OTEL_EXPORTER_TYPE=http k6 run --out opentelemetry script.js

# After
K6_OTEL_EXPORTER_PROTOCOL=http/protobuf k6 run --out opentelemetry script.js

OTel output: `K6_OTEL_SINGLE_COUNTER_FOR_RATE` removed

The K6_OTEL_SINGLE_COUNTER_FOR_RATE environment variable has been removed. Rate metrics are now always exported as a single counter with a condition attribute (zero/nonzero). If you were using the old pair-of-counters format (metric_name.occurred / metric_name.total), update your dashboards and queries to filter on the condition attribute instead.

Removed `K6_BINARY_PROVISIONING`

The K6_BINARY_PROVISIONING environment variable has been removed. Auto-extension resolution is enabled by default. Remove K6_BINARY_PROVISIONING from your environment. If you need to disable auto-extension resolution, use K6_AUTO_EXTENSION_RESOLUTION=false instead.

Removed `K6_ENABLE_COMMUNITY_EXTENSIONS`

Community extensions no longer require an opt-in flag. Automatic extension resolution works for both official and community extensions by default. Remove any K6_ENABLE_COMMUNITY_EXTENSIONS=true from your environment.

Legacy configuration file path no longer migrated

k6 no longer automatically migrates configuration files from the old {USER_CONFIG_DIR}/loadimpact/config.json path used before k6 v1.0.0. If you still have a config file at that location, move it manually:

# Linux / macOS
mv ~/.config/loadimpact/config.json ~/.config/k6/config.json

# Windows
move %APPDATA%\loadimpact\config.json %APPDATA%\k6\config.json

Alternatively, run k6 cloud login to regenerate the config at the correct path.

Browser: `browser_web_vital_fid` metric removed

The browser_web_vital_fid metric has been removed as it’s no longer a Core Web Vital. Use browser_web_vital_inp instead, which measures Interaction to Next Paint.

Update any thresholds that reference browser_web_vital_fid:

// Before
export const options = {
  thresholds: {
    browser_web_vital_fid: ['p(75) < 100'],
  },
};

// After
export const options = {
  thresholds: {
    browser_web_vital_inp: ['p(75) < 200'],
  },
};

Get started on Grafana Labs

Write your first test

Write your first test

Before you start

Basic structure of a k6 test

Writing your first test script

Extending your script

Next steps

Running k6

Running k6

Before you begin

Run local tests

Add VUs

The init context and the default function

Set options

Ramp VUs up and down in stages

Execution modes

Results output

Results output

Metrics

End-of-test summary

Custom reports with handleSummary()

Time series and external outputs

k6 resources

k6 resources

Learning

Community

Test servers

k6 + your favorite tool

Migrate to k6 v2

Migrate to k6 v2

Go module path changed to go.k6.io/k6/v2

Removed CLI commands: k6 pause, k6 resume, k6 scale, k6 status

Removed externally-controlled executor

Removed CLI command: k6 login

Stack is now required for all k6 cloud commands

Cloud run non-threshold aborts now exit with code 97

k6 cloud positional argument removed

Removed --upload-only flag

Removed --no-summary flag

Removed --summary-mode=legacy

Removed options.ext.loadimpact

Removed k6/experimental/redis

OTel output: K6_OTEL_EXPORTER_TYPE renamed to K6_OTEL_EXPORTER_PROTOCOL

OTel output: K6_OTEL_SINGLE_COUNTER_FOR_RATE removed

Removed K6_BINARY_PROVISIONING

Removed K6_ENABLE_COMMUNITY_EXTENSIONS

Legacy configuration file path no longer migrated

Browser: browser_web_vital_fid metric removed

Custom reports with `handleSummary()`

Go module path changed to `go.k6.io/k6/v2`

Removed CLI commands: `k6 pause`, `k6 resume`, `k6 scale`, `k6 status`

Removed `externally-controlled` executor

Removed CLI command: `k6 login`

Stack is now required for all `k6 cloud` commands

`k6 cloud` positional argument removed

Removed `--upload-only` flag

Removed `--no-summary` flag

Removed `--summary-mode=legacy`

Removed `options.ext.loadimpact`

Removed `k6/experimental/redis`

OTel output: `K6_OTEL_EXPORTER_TYPE` renamed to `K6_OTEL_EXPORTER_PROTOCOL`

OTel output: `K6_OTEL_SINGLE_COUNTER_FOR_RATE` removed

Removed `K6_BINARY_PROVISIONING`

Removed `K6_ENABLE_COMMUNITY_EXTENSIONS`

Browser: `browser_web_vital_fid` metric removed