k6

A modern load testing tool, using Go and JavaScript

"like unit testing, for performance"

k6 is a modern load testing tool, building on Load Impact's years of experience. It provides a clean, approachable JavaScript scripting API, distributed and cloud execution, and orchestration via a REST API.

Get Started    Guides

Tags and Groups

The analysis of your load results is a required step to find performance issues; a load test usually targets a service involving different subsystems and resources, making it hard to find the issue/s degrading your performance.

k6 provides two scripting APIs to help you during the analysis and easily visualize, sort and filter your test results.

  • Groups: organize your load script around common logic.
  • Tags: categorize your checks, thresholds, custom metrics and requests with tags for in-depth filtering.

Groups

Groups are optional, and it allows you to “group” your load script. Groups can be nested, allowing you the BDD-style of testing.

import { group } from "k6";

export default function() {
  group("user flow: returning user", function() {
    group("visit homepage", function() {
      // load homepage resources
    });
    group("login", function() {
      // perform login
    });
  });
};

Your test results will be grouped based on your group names for easily visualization. Each execution of the supplied group() function also emits a group_duration metric that contains the total time it took to execute that group function. This, combined with the metric tags described below, enables very flexible performance monitoring of different groups in your test suite.

Tags

Tags are a simple and powerful way to categorize your k6 entities for later results filtering.

k6 provides two types of tags:

  • User-defined tags: the ones you've added when writing your script.
  • System tags: tags automatically assigned by k6.

System tags

Currently, k6 automatically creates the following tags by default:

  • proto - the used protocol name (e.g. HTTP/1.1)
  • subproto - the subprotocol name (used by websockets)
  • status - the HTTP status code (e.g. 200, 404, etc.)
  • method - the HTTP method name (e.g. GET, POST, etc.)
  • url - the HTTP request URL
  • name - the HTTP request name
  • group - the full group path
  • check - the Check name
  • error - a string with a non-HTTP error message (e.g. network or DNS error)
  • tls_version - the TLS version

If you choose, you could disable some of the above tags by using the systemTags option, just keep in mind that some data collectors (e.g. cloud) may require that certain tags be present. Also, you can enable some additional system tags, if you need them:

User-defined tags

User-defined tags allow you to categorize k6 entities based on your own logic. The following entities can be tagged:

  • checks
  • thresholds
  • custom metrics
  • requests
import http from "k6/http";
import { Trend } from "k6/metrics";
import { check } from "k6";

let myTrend = new Trend("my_trend");

export default function() {
    // Add tag to request metric data
    let res = http.get("http://httpbin.org/", { tags: { my_tag: "I'm a tag" } });

    // Add tag to check
    check(res, { "status is 200": (r) => r.status === 200 }, { my_tag: "I'm a tag" });

    // Add tag to custom metric
    myTrend.add(res.timings.connecting, { my_tag: "I'm a tag" });
}

Test wide tags

Besides attaching tags on requests, checks and custom metrics you can set test wide tags that will be set across all metrics. You can either set the tags on the CLI using one or more --tag NAME=VALUE flags or in the script:

export let options = {
    tags: {
        "name": "value"
    }
};

Tags in results output

{"type":"Point","data":{"time":"2017-05-09T14:34:45.625742514+02:00","value":5,"tags":null},"metric":"vus"}
{"type":"Point","data":{"time":"2017-05-09T14:34:45.239531499+02:00","value":459.865729,"tags":{"group":"::my group::json","method":"GET","status":"200","url":"https://httpbin.org/get"}},"metric":"http_req_duration"}

Read more about the k6 results output syntax (https://docs.k6.io/docs/results-output#section-json-output) to see how tags affect your test result output.

Tags and Groups