k6/execution

k6/execution provides the capability to get information about the current test execution state inside the test script. You can read in your script the execution state during the test execution and change your script logic based on the current state.

The k6/execution module provides the test execution information with the following properties:

• instance
• scenario
• test
• vu

import exec from 'k6/execution';

export const options = {
  scenarios: {
    myscenario: {
      // this will be the returned name
      executor: 'shared-iterations',
      maxDuration: '30m',
    },
  },
};

export default function () {
  console.log(exec.scenario.name); // myscenario
}

ℹ️ Identifiers

All unique identifiers are sequentially generated starting from a base of zero (iterations) or one (VU IDs). In distributed/cloud test runs, the test-wide iteration numbers and VU identifiers are still going to be unique across instances, though there might be gaps in the sequences when, for example, some instances execute faster iterations than others or allocate more VUs mid-test.

instance

The instance object provides information associated with the load generator instance. You can think of it as the current running k6 process, which will likely be a single process if you are running k6 on your local machine. When running a cloud/distributed test with multiple load generator instances, the values of the following properties can differ across instances.

scenario

Meta information and execution details about the current running scenario.

test

Control the test execution.

vu

Meta information and execution details about the current vu.

Examples and use cases

Getting unique data once

This is a common use case for data parameterization, you can read the examples using scenario.iterationInTest and vu.idInTest.

Timing operations

The startTime property from the scenario object can be used to time operations.

1import exec from 'k6/execution';
2
3export default function () {
4  // do some long operations
5  // ...
6  console.log(`step1: scenario ran for ${new Date() - new Date(exec.scenario.startTime)}ms`);
7
8  // some more long operations
9  //...
10  console.log(`step2: scenario ran for ${new Date() - new Date(exec.scenario.startTime)}ms`);
11}

Script naming

The name property can be used for executing the logic based on which script is currently running.

Tip: If you need to run multiple scenarios in your script you can use exec option achieve a similar goal

1import exec from 'k6/execution';
2
3export const options = {
4  scenarios: {
5    'the-first': {
6      // ...
7    },
8    'the-second': {
9      // ...
10    },
11  },
12};
13
14export default function () {
15  if (exec.scenario.name === 'the-first') {
16    // do some logic during this scenario
17  } else {
18    // do some other logic in the others
19  }
20}

Test Abort

Aborting is possible during initialization:

1import exec from 'k6/execution';
2exec.test.abort();

As well as inside the default function:

1import exec from 'k6/execution';
2
3export default function () {
4  // Note that you can abort with a specific message too
5  exec.test.abort('this is the reason');
6}
7
8export function teardown() {
9  console.log('teardown will still be called after test.abort()');
10}

Get test options

Get the consolidated and derived options' values

1import exec from 'k6/execution';
2
3export const options = {
4  stages: [
5    { duration: '5s', target: 100 },
6    { duration: '5s', target: 50 },
7  ],
8};
9
10export default function () {
11  console.log(exec.test.options.paused); // null
12  console.log(exec.test.options.scenarios.default.stages[0].target); // 100
13}

Tags

The vu.metrics.tags property can be used for getting or setting VU's tags.

1import http from 'k6/http';
2import exec from 'k6/execution';
3
4export default function () {
5  exec.vu.metrics.tags['mytag'] = 'value1';
6  exec.vu.metrics.tags['mytag2'] = 2;
7
8  // the metrics these HTTP requests emit will get tagged with `mytag` and `mytag2`:
9  http.batch(['https://test.k6.io', 'https://test-api.k6.io']);
10}

vu.tags (without metrics) can also be used, but is deprecated for the more context-specific variant.

Metadata

The vu.metrics.metadata property can be used for getting or setting VU's metadata. It is similar to tags, but can be used for high cardinality data. It also can not be used in thresholds and will likely be handled differently by each output.

1import http from 'k6/http';
2import exec from 'k6/execution';
3
4export default function () {
5  exec.vu.metrics.metadata['trace_id'] = 'somecoolide';
6
7  // the metrics these HTTP requests emit will get the metadata `trace_id`:
8  http.batch(['https://test.k6.io', 'https://test-api.k6.io']);
9
10  delete exec.vu.metrics.metadata['trace_id'] // this will unset it
11  // which will make the metrics these requests to not have the metadata `trace_id` set on them.
12  http.batch(['https://test.k6.io', 'https://test-api.k6.io']);
13}