Get started with k6 on Grafana Labs

Test for functional behavior

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

Test for functional behavior

In this tutorial, learn how to write a test that does the following:

Sends a POST request to the new endpoint
Creates a check for the response status

Script the Request

The first thing to do is to add logic for the endpoint. To do that, you need to make an HTTP request:

Import the HTTP module.
Create a payload to authenticate the user.
Use the http.post method to send your request with the payload to an endpoint.

To test, copy this file and save it as api-test.js.

// import necessary module
import http from 'k6/http';

export default function () {
  // define URL and payload
  const url = 'https://quickpizza.grafana.com/api/users/token/login';
  const payload = JSON.stringify({
    username: 'default',
    password: '12345678',
  });

  const params = {
    headers: {
      'Content-Type': 'application/json',
    },
  };

  // send a post request and save response as a variable
  const res = http.post(url, payload, params);
}

Run the script using the k6 run command:

k6 run api-test.js

After the test finishes, k6 reports the default result summary.

          /\      |‾‾| /‾‾/   /‾‾/
     /\  /  \     |  |/  /   /  /
    /  \/    \    |     (   /   ‾‾\
   /          \   |  |\  \ |  (‾)  |
  / __________ \  |__| \__\ \_____/ .io

  execution: local
     script: api-test.js
     output: -
  ...

As an optional step, you can log the response body to the console to make sure you’re getting the right response.

export default function () {
  // ...

  const res = http.post(url, payload, params);

  // Log the request body
  console.log(res.body);
}

Add response checks

Once you’re sure the request is well-formed, add a check that validates whether the system responds with the expected status code.

Update your script so it has the following check function.

// Import necessary modules
import { check } from 'k6';
import http from 'k6/http';

export default function () {
  // define URL and payload
  const url = 'https://quickpizza.grafana.com/api/users/token/login';
  const payload = JSON.stringify({
    username: 'default',
    password: '12345678',
  });
  const params = {
    headers: {
      'Content-Type': 'application/json',
    },
  };

  // send a post request and save response as a variable
  const res = http.post(url, payload, params);

  // check that response is 200
  check(res, {
    'response code was 200': (res) => res.status == 200,
  });
}

Run the script again.

k6 run api-test.js

Inspect the result output for your check. It should look something like this.
```
✓ response code was 200
```

Note
Under larger loads, this check will fail in some iterations. Failed checks do not stop tests.

Rather, k6 tracks the success rate and presents it in your end of test summary.

Next steps

In this tutorial, you’ve used k6 to make a POST request and check that it responds with a 200 status.

However, these tests make only one request, which doesn’t say much about how the system will respond under load. For that, you need to test under load.

Test for performance

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

Test for performance

In the previous section, you made a working script to test an endpoint functionality. The next step is to test how this system responds under load. This requires setting up a few options to configure the parts of the test that don’t deal with test logic.

In this tutorial, learn how to:

Use thresholds to assert for performance criteria
Configure load increases through scenarios

These examples build on the script from the previous section.

Context: meet service-level objectives

To assess the login endpoint’s performance, your team may have defined service level objectives (SLOs). For example:

99% of requests should be successful
99% of requests should have a latency of 1000ms or less

The service must meet these SLOs under different types of usual traffic.

Assert for performance with thresholds

To codify the SLOs, add thresholds to test that your system performs to its goal criteria.

Thresholds are set in the options object.

export const options = {
  // define thresholds
  thresholds: {
    http_req_failed: ['rate<0.01'], // http errors should be less than 1%
    http_req_duration: ['p(99)<1000'], // 99% of requests should be below 1s
  },
};

Add this options object with thresholds to your script api-test.js.

// import necessary modules
import { check } from 'k6';
import http from 'k6/http';

// define configuration
export const options = {
  // define thresholds
  thresholds: {
    http_req_failed: ['rate<0.01'], // http errors should be less than 1%
    http_req_duration: ['p(99)<1000'], // 99% of requests should be below 1s
  },
};

export default function () {
  // define URL and request body
  const url = 'https://quickpizza.grafana.com/api/users/token/login';
  const payload = JSON.stringify({
    username: 'default',
    password: '1234',
  });
  const params = {
    headers: {
      'Content-Type': 'application/json',
    },
  };

  // send a post request and save response as a variable
  const res = http.post(url, payload, params);

  // check that response is 200
  check(res, {
    'response code was 200': (res) => res.status == 200,
  });
}

Run the test.

k6 run api-test.js

Inspect the console output to determine whether performance crossed a threshold.

  █ THRESHOLDS

    http_req_duration
    ✓ 'p(99)<1000' p(99)=148.21ms

    http_req_failed
    ✗ 'rate<0.01' rate=20.%

The ✓ and ✗ symbols indicate whether the performance thresholds passed or failed.

Test performance under increasing load

Now your script has logic to simulate user behavior, and assertions for functionality (checks) and performance (thresholds).

It’s time to increase the load to see how it performs. To increase the load, use the scenarios property. Scenarios schedule load according to the number of virtual users (VUs), number of iterations, VUs, or by iteration rate.

Run a smoke test

Start small. Run a smoke test to check that your script can handle a minimal load.

To do so, use the --iterations flag with an argument of 10 or fewer.

k6 run --iterations 10 api-test.js

If the service can’t receive 10 iterations, the system has some serious performance issues to debug. Good thing you ran the test early!

Run a test against an average load

Generally, traffic doesn’t arrive all at once. Rather, it gradually increases to a peak load. To simulate this, testers increase the load in stages.

Add the following scenario property to your options object and rerun the test.

export const options = {
  // define thresholds
  thresholds: {
    http_req_failed: ['rate<0.01'], // http errors should be less than 1%
    http_req_duration: ['p(99)<1000'], // 99% of requests should be below 1s
  },
  // define scenarios
  scenarios: {
    // arbitrary name of scenario
    average_load: {
      executor: 'ramping-vus',
      stages: [
        // ramp up to average load of 20 virtual users
        { duration: '10s', target: 20 },
        // maintain load
        { duration: '50s', target: 20 },
        // ramp down to zero
        { duration: '5s', target: 0 },
      ],
    },
  },
};

Since this is a learning environment, the stages are still quite short. Where the smoke test defined the load in terms of iterations, this configuration uses the ramping-vus executor to express load through virtual users and duration.

Run the test with no command-line flags:

k6 run api-test.js

The load is small, so the server should perform within thresholds. However, this test server may be under load by many k6 learners, so the results are unpredictable.

Note
At this point, it’d be nice to have a graphical interface to visualize metrics as they occur. k6 has many output formats, which can serve as inputs for many visualization tools, both open source and commercial. For ideas, read Ways to visualize k6 results.

Ramp up until threshold fails

Finally, run a breakpoint test, where you probe the system’s limits. In this case, run the test until the availability (error rate) threshold is crossed.

To do this:

Add the abortOnFail property to http_req_failed.

export const options = {
  // define thresholds
  thresholds: {
    http_req_failed: [{ threshold: 'rate<0.01', abortOnFail: true }], // http errors should be less than 1%, otherwise abort the test
    http_req_duration: ['p(99)<1000'], // 99% of requests should be below 1s
  },
  // ...
};

Update the scenarios property to ramp the test up until it fails.

export const options = {
  thresholds: {
    http_req_failed: [{ threshold: 'rate<0.01', abortOnFail: true }],
    http_req_duration: ['p(99)<1000'],
  },
  scenarios: {
    // define scenarios
    breaking: {
      executor: 'ramping-vus',
      stages: [
        { duration: '10s', target: 20 },
        { duration: '50s', target: 20 },
        { duration: '50s', target: 40 },
        { duration: '50s', target: 60 },
        { duration: '50s', target: 80 },
        { duration: '50s', target: 100 },
        { duration: '50s', target: 120 },
        { duration: '50s', target: 140 },
        //....
      ],
    },
  },
};

Here is the full script.

// import necessary modules
import { check } from 'k6';
import http from 'k6/http';

// define configuration
export const options = {
  // define thresholds
  thresholds: {
    http_req_failed: [{ threshold: 'rate<0.01', abortOnFail: true }], // availability threshold for error rate
    http_req_duration: ['p(99)<1000'], // Latency threshold for percentile
  },
  // define scenarios
  scenarios: {
    breaking: {
      executor: 'ramping-vus',
      stages: [
        { duration: '10s', target: 20 },
        { duration: '50s', target: 20 },
        { duration: '50s', target: 40 },
        { duration: '50s', target: 60 },
        { duration: '50s', target: 80 },
        { duration: '50s', target: 100 },
        { duration: '50s', target: 120 },
        { duration: '50s', target: 140 },
        //....
      ],
    },
  },
};

export default function () {
  // define URL and request body
  const url = 'https://quickpizza.grafana.com/api/users/token/login';
  const payload = JSON.stringify({
    username: 'default',
    password: '1234',
  });
  const params = {
    headers: {
      'Content-Type': 'application/json',
    },
  };

  // send a post request and save response as a variable
  const res = http.post(url, payload, params);

  // check that response is 200
  check(res, {
    'response code was 200': (res) => res.status == 200,
  });
}

Run the test.

k6 run api-test.js

Did the threshold fail? If not, add another stage with a higher target and try again. Repeat until the threshold aborts the test:

ERRO[0010] thresholds on metrics 'http_req_duration, http_req_failed' were breached; at least one has abortOnFail enabled, stopping test prematurely

Next steps

In this tutorial, you used thresholds to assert performance and Scenarios to schedule different load patterns. To learn more about the usual load patterns and their goals, read Load Test Types

The next step of this tutorial shows how to interpret test results. This involves filtering results and adding custom metrics.

Analyze results

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

Analyze results

In this tutorial, learn how to:

Apply tags to filter specific results
Learn about k6 metrics
Use jq to filter JSON results
Define groups to organize the test
Create custom metrics

Context: k6 result outputs

k6 provides many result outputs. By default, the end-of-test summary provides the aggregated results of the test metrics.

  █ THRESHOLDS

    http_req_duration
    ✓ 'p(95)<1500' p(95)=148.21ms
    ✓ 'p(90)<2000' p(90)=146.88ms

    http_req_failed
    ✓ 'rate<0.01' rate=0.00%


  █ TOTAL RESULTS

    checks_total.......................: 90      13.122179/s
    checks_succeeded...................: 100.00% 90 out of 90
    checks_failed......................: 0.00%   0 out of 90

    ✓ test-api.k6.io is up
    ✓ status is 200

    CUSTOM
    custom_waiting_time................: avg=152.355556 min=120      med=141      max=684      p(90)=147.2    p(95)=148.8

    HTTP
    http_req_duration..................: avg=140.36ms   min=119.08ms med=140.96ms max=154.63ms p(90)=146.88ms p(95)=148.21ms
      { expected_response:true }.......: avg=140.36ms   min=119.08ms med=140.96ms max=154.63ms p(90)=146.88ms p(95)=148.21ms
    http_req_failed....................: 0.00%  0 out of 45
    http_reqs..........................: 45     6.56109/s

    EXECUTION
    iteration_duration.................: avg=152.38ms   min=119.37ms med=141.27ms max=684.62ms p(90)=147.11ms p(95)=148.39ms
    iterations.........................: 45     6.56109/s
    vus................................: 1      min=1       max=1
    vus_max............................: 1      min=1       max=1

    NETWORK
    data_received......................: 519 kB 76 kB/s
    data_sent..........................: 4.9 kB 718 B/s

For simplicity to learn about k6 metric results, this tutorial uses the JSON output and jq to filter results.

For other options to analyze test results such as storage and time-series visualizations in real-time, refer to:

Write time-series results to a JSON file

To output results to a JSON file, use the --out flag.

k6 run --out json=results.json api-test.js

Then run this jq command to filter the latency results; http_req_duration metric.

jq '. | select(.type == "Point" and .metric == "http_req_duration")' results.json

k6 results have a number of built-in tags. For example, filter results to only results where the status is 200.

jq '. | select(.type == "Point" and .data.tags.status == "200")' results.json

Or calculate the aggregated value of any metric with any particular tags.

average

min

max

jq '. | select(.type == "Point" and .metric == "http_req_duration") | .data.value' results.json | jq -s 'add/length'

jq '. | select(.type == "Point" and .metric == "http_req_duration") | .data.value' results.json | jq -s min

jq '. | select(.type == "Point" and .metric == "http_req_duration") | .data.value' results.json | jq -s max

Apply custom tags

You can also apply Tags to requests or code blocks. For example, this is how you can add a tags to the request params.

const params = {
  headers: {
    'Content-Type': 'application/json',
  },
  tags: {
    'my-custom-tag': 'auth-api',
  },
};

Create a new script named “tagged-login.js”, and add a custom tag to it.

import http from 'k6/http';

export default function () {
  const url = 'https://quickpizza.grafana.com';
  const payload = JSON.stringify({
    username: 'test_case',
    password: '12345678',
  });

  const params = {
    headers: {
      'Content-Type': 'application/json',
    },
    //apply tags
    tags: {
      'my-custom-tag': 'auth-api',
    },
  };

  //Create user, with tags
  http.post(`${url}/api/users`, payload, params);
}

Run the test:

k6 run --out json=results.json tagged-login.js

Filter the results for this custom tag:

jq '. | select(.type == "Point" and .metric == "http_req_duration" and .data.tags."my-custom-tag" == "auth-api")' results.json

Organize requests in groups

You can also organize your test logic into Groups. Test logic inside a group tags all requests and metrics within its block. Groups can help you organize the test as a series of logical transactions or blocks.

Context: a new test to group test logic

Results filtering isn’t very meaningful in a test that makes one request. And the API test script is getting long. To learn more about how to compare results and other k6 APIs, write a test for the following situation:

A dummy example: your development team wants to evaluate the performance of two user-facing flows.

visit an endpoint, then another one

A GET request to https://test.k6.io/contacts.php

A GET to https://test.k6.io/

play the coinflip game:

A POST request to https://test.k6.io/flip_coin.php with the query param bet=heads

Another POST to https://test.k6.io/flip_coin.php with the query param bet=tails

Can you figure out how to script the requests? If not, use the following script. Since this example simulates a human user rather than an API call, it has a sleep between each request. Run with k6 run multiple-flows.js.

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

//set URL as variable
const baseUrl = 'https://test.k6.io';

export default function () {
  // visit contacts
  http.get(`${baseUrl}/contacts.php`);
  sleep(1);
  // return to the home page
  http.get(`${baseUrl}/`);
  sleep(1);

  //play coinflip game
  http.get(`${baseUrl}/flip_coin.php?bet=heads`);
  sleep(1);
  http.get(`${baseUrl}/flip_coin.php?bet=tails`);
  sleep(1);
}

Add Group functions

Wrap the two endpoints in different groups. Name one group Contacts flow and another Coinflip game.

//import necessary modules
import http from 'k6/http';
import { group, sleep } from 'k6';

//set baseURL
const baseUrl = 'https://test.k6.io';

export default function () {
  // visit some endpoints in one group
  group('Contacts flow', function () {
    http.get(`${baseUrl}/contacts.php`);
    sleep(1);
    // return to the home page
    http.get(`${baseUrl}/`);
    sleep(1);
  });

  // Coinflip players in another group
  group('Coinflip game', function () {
    http.get(`${baseUrl}/flip_coin.php?bet=heads`);
    sleep(1);
    http.get(`${baseUrl}/flip_coin.php?bet=tails`);
    sleep(1);
  });
}

Run and filter

Inspect the results for only the Coinflip game group. To do so:

Save the preceding script as multiple-flows.js.
Run the script with the command:

k6 run multiple-flows.js --out json=results.json --iterations 10

Inspect the results with jq. Group names have a :: prefix.

jq '. | select(.data.tags.group == "::Coinflip game")' results.json

Add a custom metric

As you have seen in the output, all k6 tests emit metrics. However, if the built-in metrics aren’t enough, you can create custom metrics. A common use case is to collect metrics of a particular scope of your test.

As an example, create a metric that collects latency results for each group:

Import Trend from the k6 metrics module.
Create two duration trend metric functions.
In each group, add the duration time to the trend for requests to contacts and the coin_flip endpoints.

//import necessary modules
import http from 'k6/http';
import { group, sleep } from 'k6';
import { Trend } from 'k6/metrics';

//set baseURL
const baseUrl = 'https://test.k6.io';

// Create custom trend metrics
const contactsLatency = new Trend('contacts_duration');
const coinflipLatency = new Trend('coinflip_duration');

export default function () {
  // Put visits to contact page in one group
  let res;
  group('Contacts flow', function () {
    // save response as variable
    res = http.get(`${baseUrl}/contacts.php`);
    // add duration property to metric
    contactsLatency.add(res.timings.duration);
    sleep(1);

    res = http.get(`${baseUrl}/`);
    // add duration property to metric
    contactsLatency.add(res.timings.duration);
    sleep(1);
  });

  // Coinflip players in another group

  group('Coinflip game', function () {
    // save response as variable
    let res = http.get(`${baseUrl}/flip_coin.php?bet=heads`);
    // add duration property to metric
    coinflipLatency.add(res.timings.duration);
    sleep(1);

    res = http.get(`${baseUrl}/flip_coin.php?bet=tails`);
    // add duration property to metric
    coinflipLatency.add(res.timings.duration);
    sleep(1);
  });
}

Run the test with small number of iterations and output the results to results.json.

k6 run multiple-flows.js --out json=results.json --iterations 10

Look for the custom trend metrics in the end-of-test console summary.

coinflip_duration..............: avg=119.6438  min=116.481  med=118.4755 max=135.498  p(90)=121.8459 p(95)=123.89565
contacts_duration..............: avg=125.76985 min=116.973  med=120.6735 max=200.507  p(90)=127.9271 p(95)=153.87245

You can also query custom metric results from the JSON results. For example, to get the aggregated results as.

avg

min

max

jq '. | select(.type == "Point" and .metric == "coinflip_duration") | .data.value' results.json | jq -s 'add/length'

jq '. | select(.type == "Point" and .metric == "coinflip_duration") | .data.value' results.json | jq -s min

jq '. | select(.type == "Point" and .metric == "coinflip_duration") | .data.value' results.json | jq -s max

Next steps

In this tutorial, you looked at granular output and filtered by built-in and custom tags. Then you made a new script with groups. Finally, you added a new metric for each group. A next step would be to create a Custom end-of-test summary or to stream the results to a database.

For ongoing operations, you can modularize your logic and configuration. That’s the subject of the next step of this tutorial.

Reuse and re-run tests

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

Reuse and re-run tests

In the previous tutorials, you designed k6 scripts to assert performance and make comparing results easy.

In this tutorial, learn how to:

Modularize test scripts into reusable components
Dynamically configure scripts with environment variables

Example script

For fun, let’s combine the scripts from the previous tutorials. Use the logic of the multiple-flows.js test with the thresholds and scenario of the api-test.js (feel free to add more checks, requests, groups, and so on). Take note of the features of this script:

The default function has two groups, Contacts flow, and Coinflip game
The options object has two properties, thresholds and scenarios

In the following sections, learn how to split these components into separate files, and combine them dynamically at run time.

import http from 'k6/http';
import { group, sleep } from 'k6';
import { Trend } from 'k6/metrics';

//define configuration
export const options = {
  scenarios: {
    //arbitrary name of scenario:
    breaking: {
      executor: 'ramping-vus',
      stages: [
        { duration: '10s', target: 20 },
        { duration: '50s', target: 20 },
        { duration: '50s', target: 40 },
        { duration: '50s', target: 60 },
        { duration: '50s', target: 80 },
        { duration: '50s', target: 100 },
        { duration: '50s', target: 120 },
        { duration: '50s', target: 140 },
        //....
      ],
    },
  },
  //define thresholds
  thresholds: {
    http_req_failed: [{ threshold: 'rate<0.01', abortOnFail: true }], // availability threshold for error rate
    http_req_duration: ['p(99)<1000'], // Latency threshold for percentile
  },
};

//set baseURL
const baseUrl = 'https://test.k6.io';

// Create custom trends
const contactsLatency = new Trend('contacts_duration');
const coinflipLatency = new Trend('coinflip_duration');

export default function () {
  // Put visits to contact page in one group
  let res;
  group('Contacts flow', function () {
    // save response as variable
    res = http.get(`${baseUrl}/contacts.php`);
    // add duration property to metric
    contactsLatency.add(res.timings.duration);
    sleep(1);

    res = http.get(`${baseUrl}/`);
    // add duration property to metric
    contactsLatency.add(res.timings.duration);
    sleep(1);
  });

  // Coinflip players in another group

  group('Coinflip game', function () {
    // save response as variable
    let res = http.get(`${baseUrl}/flip_coin.php?bet=heads`);
    // add duration property to metric
    coinflipLatency.add(res.timings.duration);
    sleep(1);

    res = http.get(`${baseUrl}/flip_coin.php?bet=tails`);
    // add duration property to metric
    coinflipLatency.add(res.timings.duration);
    sleep(1);
  });
}

Modularize logic

With modules, you can use logic and variables from other files. Use modules to extract the functions to their own files.

To do so, follow these steps:

Copy the previous script (whole-tutorial.js) and save it as main.js.

Extract the Contacts flow group function from main.js script file and paste it into a new file called contacts.js

export function contacts() {
  group('Contacts flow', function () {
    // save response as variable
    let res = http.get(`${baseUrl}/contacts.php`);
    // add duration property to metric
    contactsLatency.add(res.timings.duration);
    sleep(1);

    res = http.get(`${baseUrl}/`);
    // add duration property to metric
    contactsLatency.add(res.timings.duration);
    sleep(1);
  });
}

As is, this script won’t work, since it has undeclared functions and variables.

Add the necessary imports and variables. This script uses the group, sleep, and http functions or libraries. It also has a custom metric. Since this metric is specific to the group, you can add it contacts.js.

Finally, pass baseUrl as a parameter of the contacts function.

import http from 'k6/http';
import { Trend } from 'k6/metrics';
import { group, sleep } from 'k6';

const contactsLatency = new Trend('contact_duration');

export function contacts(baseUrl) {
  group('Contacts flow', function () {
    // save response as variable
    let res = http.get(`${baseUrl}/contacts.php`);
    // add duration property to metric
    contactsLatency.add(res.timings.duration);
    sleep(1);

    res = http.get(`${baseUrl}/`);
    // add duration property to metric
    contactsLatency.add(res.timings.duration);
    sleep(1);
  });
}

Repeat the process with the coinflip group in a file called coinflip.js. Use the tabs to see the final three files should (options moved to the bottom of main.js for better readability).

main

contacts

coinflip

import { contacts } from './contacts.js';
import { coinflip } from './coinflip.js';

const baseUrl = 'https://test.k6.io';

export default function () {
  // Put visits to contact page in one group
  contacts(baseUrl);
  // Coinflip players in another group
  coinflip(baseUrl);
}

//define configuration
export const options = {
  scenarios: {
    //arbitrary name of scenario:
    breaking: {
      executor: 'ramping-vus',
      stages: [
        { duration: '10s', target: 20 },
        { duration: '50s', target: 20 },
        { duration: '50s', target: 40 },
        { duration: '50s', target: 60 },
        { duration: '50s', target: 80 },
        { duration: '50s', target: 100 },
        { duration: '50s', target: 120 },
        { duration: '50s', target: 140 },
        //....
      ],
    },
  },
  //define thresholds
  thresholds: {
    http_req_failed: [{ threshold: 'rate<0.01', abortOnFail: true }], // availability threshold for error rate
    http_req_duration: ['p(99)<1000'], // Latency threshold for percentile
  },
};

import http from 'k6/http';
import { Trend } from 'k6/metrics';
import { group, sleep } from 'k6';

const contactsLatency = new Trend('contact_duration');

export function contacts(baseUrl) {
  group('Contacts flow', function () {
    // save response as variable
    let res = http.get(`${baseUrl}/contacts.php`);
    // add duration property to metric
    contactsLatency.add(res.timings.duration);
    sleep(1);

    res = http.get(`${baseUrl}/`);
    // add duration property to metric
    contactsLatency.add(res.timings.duration);
    sleep(1);
  });
}

import http from 'k6/http';
import { Trend } from 'k6/metrics';
import { group, sleep } from 'k6';

const coinflipLatency = new Trend('coinflip_duration');

export function coinflip(baseUrl) {
  group('Coinflip game', function () {
    // save response as variable
    let res = http.get(`${baseUrl}/flip_coin.php?bet=heads`);
    // add duration property to metric
    coinflipLatency.add(res.timings.duration);
    sleep(1);
    // mutate for new request
    res = http.get(`${baseUrl}/flip_coin.php?bet=tails`);
    // add duration property to metric
    coinflipLatency.add(res.timings.duration);
    sleep(1);
  });
}

Run the test:

# setting the workload to 10 iterations to limit run time
k6 run main.js --iterations 10

The results should be very similar to running the script in a combined file, since these are the same test.

Modularize workload

Now that the iteration code is totally modularized, you might modularize your options, too.

The following example creates a module config.js to export the threshold and workload settings.

main

config

import { coinflip } from './coinflip.js';
import { contacts } from './contacts.js';
import { thresholdsSettings, breakingWorkload } from './config.js';

export const options = {
  scenarios: { breaking: breakingWorkload },
  thresholds: thresholdsSettings,
};

const baseUrl = 'https://test.k6.io';

export default function () {
  contacts(baseUrl);
  coinflip(baseUrl);
}

export const thresholdsSettings = {
  http_req_failed: [{ threshold: 'rate<0.01', abortOnFail: true }],
  http_req_duration: ['p(99)<1000'],
};

export const breakingWorkload = {
  executor: 'ramping-vus',
  stages: [
    { duration: '10s', target: 20 },
    { duration: '50s', target: 20 },
    { duration: '50s', target: 40 },
    { duration: '50s', target: 60 },
    { duration: '50s', target: 80 },
    { duration: '50s', target: 100 },
    { duration: '50s', target: 120 },
    { duration: '50s', target: 140 },
    //....
  ],
};

Notice the length of this final script and compare it with the script at the beginning of this page. Though the final execution is the same, it’s half the size and more readable.

Besides shortness, this modularity lets you compose scripts from many parts, or dynamically configure scripts at run time.

Mix and match logic

With modularized configuration and logic, you can define named scenarios for different workloads and select one with --scenario.

Change main.js and config.js to define a smoke test with five iterations and a breaking test, then choose the workload when you run the script.

To do this, follow these steps:

Add the workload settings for configuring the smoke test to config.js:

export const smokeWorkload = {
  executor: 'shared-iterations',
  iterations: 5,
  vus: 1,
};

export const thresholdsSettings = {
  http_req_failed: [{ threshold: 'rate<0.01', abortOnFail: true }],
  http_req_duration: ['p(99)<1000'],
};

export const breakingWorkload = {
  executor: 'ramping-vus',
  stages: [
    { duration: '10s', target: 20 },
    { duration: '50s', target: 20 },
    { duration: '50s', target: 40 },
    { duration: '50s', target: 60 },
    { duration: '50s', target: 80 },
    { duration: '50s', target: 100 },
    { duration: '50s', target: 120 },
    { duration: '50s', target: 140 },
    //....
  ],
};

Edit main.js to define a named scenario for each workload:

import { coinflip } from './coinflip.js';
import { contacts } from './contacts.js';
import { thresholdsSettings, breakingWorkload, smokeWorkload } from './config.js';

export const options = {
  scenarios: {
    smoke: smokeWorkload,
    breaking: breakingWorkload,
  },
  thresholds: thresholdsSettings,
};

const baseUrl = 'https://test.k6.io';

export default function () {
  contacts(baseUrl);
  coinflip(baseUrl);
}

Select the smoke test:
Bash
```
k6 run --scenario smoke main.js
```
When you want to run the breaking test, select that workload instead:
Bash
```
k6 run --scenario breaking main.js
```
Always select the intended workload for this example. Without --scenario, k6 runs both scenarios, including the breaking test.

This was a simple example to showcase how you can modularize a test. As your test suite grows and more people are involved in performance testing, your modularization strategy becomes essential to building and maintaining an efficient testing suite.

Next steps

Now you’ve seen examples to write tests, assert for performance, filter results, and modularize scripts. Notice how the tests progress in complexity: from single endpoints to holistic tests, from small to large loads, and from single tests to reusable modules. These progressions are typical in testing, with the next step being to automate. It might be impractical to automate a tutorial, but if you are interested, read the Automated performance testing guide.

More likely, you want to learn more about k6. The k6-learn repository has more details to practice. Or, you can read and explore the testing guides and try to build out your testing strategy.

Happy testing!