Distributed load testing with Grafana K6

Running large load tests with Grafana K6 often requires distributing test executions across multiple nodes. This approach is necessary when a single node lacks the capacity to generate the target load or when you need to simulate load from multiple geographic locations.

This tutorial shows how to distribute existing Grafana K6 tests across multiple nodes using Step.

Prerequisites

• Access to a Step cluster: Get started quickly by setting up a free SaaS cluster in the Step Portal, or, if preferred, follow the Installation page to configure your own on-premise cluster.
• Install the Step CLI on your local machine as described on the Download page of Step

Test scenario

For the sake of this tutorial, we’ll simulate 10 parallel users visiting our demo online store. The user journey that we’ll simulate consists of the following actions: navigate to the online store, search for a product, add it to the shopping cart, and complete the order.

For this simulation we have an existing K6 test: K6 sample test

Checkout the sample

Clone the sample project from GitHub:

  git clone https://github.com/exense/step-samples
  Copy

Navigate to the sample directory:

  cd step-samples/automation-packages/load-testing-k6/
  Copy

Project structure

Automation package descriptor

The automation-package.yaml file located at the root of our sample project serves as the automation package descriptor, outlining the details of our load test scenario:

  ---
schemaVersion: 1.0.0
name: "load-testing-k6-automation-package"
keywords:
  # Declare a Keyword which runs the K6 test 'opencart-test.js' with 1 VU and 10 iterations
  - K6:
      name: 'OpenCart Journey 10x'
      vus: 1
      iterations: 10
      scriptFile: "k6-tests/opencart-test.js"
plans:
  - name: "Load Testing OpenCart"
    # The agents (workers) are automatically determined and provisioned upon execution
    agents: auto_detect
    root:
      testScenario:
        children:
          # Declare a ThreadGroup that distributes the execution of the Keyword (and thus the K6 test)
          - threadGroup:
              # Distributes across 5 workers
              users: 5
              # Each worker executes the Keyword 10 times (which leads to 10 x 100 = 1000 executions of the script 'opencart-test.js' per worker)
              iterations: 100
              children:
                - callKeyword:
                    # Call the defined Keyword
                    keyword: "OpenCart Journey 10x"
  Copy

For more details about the syntax, refer to the official documentation of the Automation Package Descriptor.

K6 test script

The K6 test simulating our user journey is located in k6-test/opencart-test.js. It is a standard K6 script written in JavaScript.

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

export default function () {
    // Home page
    var r = http.get('https://opencart-prf.exense.ch/',
        { tags: { name: "OpenCart Home" } });
    check(r, {
        'response is status 200': (r) => r.status === 200,
    });

    // Adding a Macbook
    r = http.get('https://opencart-prf.exense.ch/macbook',
        { tags: { name: "OpenCart Add MacBook - Step 1" } });
    check(r, {
        'response is status 200': (r) => r.status === 200,
    });
  Copy

For more details about K6 scripts, refer to the official documentation of the K6.

Execute locally

Optionally, you can run the K6 test locally:

  cd k6-tests
k6 run opencart-test.js
# Navigate back to the base directory
cd ..
  Copy

You can also run the full Automation Package plan locally with the Step CLI. In the base directory load-testing-k6:

  step ap execute --local
  Copy

Note that this will launch the full load test from the machine where the command is executed. You may want to change the automation package descriptor to use a lower number of simulated users and/or iterations when launching the test this way.

Execute in Step

Before executing the test in Step, you’ll need the URL of your Step instance and an API key. For instructions on generating an API key, refer to Generate an API Key.

To execute the test in Step, run the following command at the root of the sample directory load-testing-k6:

  step ap execute --stepUrl=https://<Hostname of your Step cluster> --projectName=Common --token=<Your API key>
  Copy

This command uploads the content of the automation package to Step and triggers the execution of the plans contained in the automation package descriptor.

Refer to the official documentation of the Step CLI for more details.

The execute command outputs a direct link to the execution report in Step:

  Execute automation package with parameters: {}
The automation package source is ...\step-samples\automation-packages\load-testing-k6
Preparing AP archive: ...\Temp\stepcli97053271864881569\load-testing-k6.stz
Execution(s) started in Step:
- 'Load Testing OpenCart' (https://<Host name of your Step cluster>/#/executions/66fd1171fda0775568ae802f)
  Waiting for execution(s) to complete...
Execution 'Load Testing OpenCart' (https://<Host name of your Step cluster>/#/executions/66fd1171fda0775568ae802f) succeeded. Result status was PASSED
  Copy

Analyze the result

Open the execution report in Step by clicking the direct link printed by the execute command above.

In the Performance tab, you can explore the performance metrics:

There you’ll find all metrics relative to the transactions of your K6 test:

• The metrics reported by K6:
  • iteration_duration: the duration of each iteration i.e. of each execution of the test script
  • http_req_duration: the duration of each HTTP request
  • Refer to the Metrics page of the official K6 documentation for more details
• The total execution time of our Keyword: “OpenCart Journey 10x” which executes the K6 script 10 times according to the configuration of the automation package and thus correspond to the duration of 10 user journeys