Create a k6 extension on Grafana Labs

k6 extension quick start guide

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

k6 extension quick start guide

This guide covers the first steps to developing k6 extensions. By following these step-by-step instructions, you will learn how to create a functional extension under your GitHub account, run a k6 test that uses it, and create a custom build of k6 using xk6.

Before you begin

To follow along, you’ll need:

A GitHub account.

Having a GitHub account simplifies the process of developing k6 extensions, which the guide will cover. GitHub Codespaces provides a streamlined development experience for k6 extensions, reducing the need for local setup.

Create a GitHub repository

The first step is to create a GitHub repository using the grafana/xk6-example template repository. This can be done interactively in a browser by clicking here. Name the repository xk6-quickstart, and set the visibility to Public.

Alternatively, use the GitHub CLI to create the repository.

gh repo create -p grafana/xk6-example -d "Experimental k6 extension" --public xk6-quickstart

Create a codespace

GitHub Codespaces is a GitHub feature that lets you create and use a fully configured development environment in the cloud.

To create a GitHub Codespace:

Go to the xk6-quickstart repository you created in the previous step
On the repository page, click the green Code button and then select Codespaces from the dropdown menu.
Click Create new codespace.

Once the codespace is ready, it will open in your browser as a Visual Studio Code-like environment, letting you begin working on your project with the repository code already checked out.

Alternatively, use the GitHub CLI to create the codespace, replacing USER with your GitHub username:

gh codespace create --repo USER/xk6-quickstart --web

Run the example script

The repository’s root directory includes a script.js file. When developing k6 extensions, use the xk6 run command instead of k6 run to execute your scripts.

xk6 run script.js

xk6 will run script.js without creating an executable k6 file in the current directory.

Build a custom k6

To use a custom k6 extension, such as xk6-quickstart, a custom k6 binary must be built using the xk6 build subcommand.

xk6 build --with github.com/USER/xk6-quickstart=.

Replace USER with your GitHub username. This command builds a custom k6 executable in the current directory, including the xk6-quickstart extension, using the current directory as the extension’s source.

To execute the example k6 script, use the newly built k6 executable by running the following command.

./k6 run script.js

Customize the extension

You can modify the Go source code to change the extension’s functionality, and use new functionality from JavaScript.

The repository also includes a smoke test, Makefile, and Go test files that you can inspect and update as you change the extension’s code.

Set up a local development environment

While using a GitHub codespace in the browser is a good starting point, you can also set up a local development environment for a better developer experience.

Before you begin

To create a local development environment, you’ll need:

Clone and open the example repository

First, clone the xk6-quickstart repository to your machine and open it in Visual Studio Code. Make sure to replace USER with your GitHub username:

git clone https://github.com/USER/xk6-quickstart.git
code xk6-quickstart

Visual Studio Code will detect the development container configuration and show a pop-up to open the project in a dev container. Accept the prompt and the project opens in the dev container, and the container image is rebuilt if necessary.

After that, you can follow the same instructions as Run the example script.

Refer to Developing inside a Container for more details about dev containers.

Next steps

You have created a xk6-quickstart extension under your own GitHub account using the extension template, and learned how to build a custom k6 binary with the extension and run a test.

Next, explore the extensions catalog to see which extensions are available, and to learn more about how to build your custom extension.

The grafana/xk6-example GitHub template streamlines the creation of k6 extensions, letting you easily expand k6’s JavaScript features. If you’re looking to extend k6’s output functionalities instead, the grafana/xk6-output-example GitHub template provides a similar, easy-to-use starting point.

Create an extension with a template

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

Create an extension with a template

This guide explains a step-by-step process for creating a k6 extension using the GitHub k6 extension template repository.

In this guide, you’ll learn how to:

Create a GitHub repository using the k6 extension template repository.
Create a TypeScript declaration file to document your API.
Create ascii85 encoding and decoding implementation.
Build a k6 binary with the extension.
Use the custom k6 binary to run a test.
Best practices for creating tests, checking for security vulnerabilities, and static analysis for your extension.

For this guide, you’ll implement two functions that handle ascii85 encoding, which is a feature that’s not natively supported by k6. This will be implemented using Go.

Before you begin

To follow along, you’ll need:

A GitHub account.

Create a GitHub repository

The first step is to create a GitHub repository using the grafana/xk6-example template repository. This can be done interactively in a browser by clicking here. Name the repository “xk6-example-ascii85”, and set the visibility to Public.

Alternatively, use the GitHub CLI to create the repository.

gh repo create -p grafana/xk6-example -d "Experimental k6 extension" --public xk6-example-ascii85

Create a codespace

GitHub Codespaces is a GitHub feature that lets you create and use a fully configured development environment in the cloud.

To create a GitHub codespace:

Go to the xk6-example-ascii85 repository you created in the previous step.
On the repository page, click the green Code button and then select Codespaces from the dropdown menu.
Click Create new codespace.

Once the codespace is ready, it will open in your browser as a Visual Studio Code-like environment, letting you begin working on your project with the repository code already checked out.

Alternatively, use the GitHub CLI to create the codespace, replacing USER with your GitHub username:

gh codespace create --repo USER/xk6-example-ascii85 --web

API declaration

This step is optional but recommended. It is a good practice to document the API of the k6 extension before implementing it.

Create a TypeScript declaration file named index.d.ts and add the following code:

/**
 * **Example ascii85 encoding for k6**
 *
 * @module example_ascii85
 */

export as namespace example_ascii85;

/**
 * ascii85encode returns the ASCII85 encoding of src.
 *
 * @param src The input to encode.
 */
export declare function encode(src: ArrayBuffer): string;

/**
 * ascii85decode returns the decoded bytes represented by the string str.
 *
 * @param str The string to decode.
 */
export declare function decode(str: string): ArrayBuffer;

Add encoding and decoding functions

The encode() function’s implementation is straightforward, as the k6 runtime handles all type conversions. The Go standard ascii85 package provides the ASCII85 encoding implementation, requiring only a parameter for its use.

Add the following function to the module.go file. The ascii85 package import will be added automatically by the IDE.

func (*module) encode(data []byte) string {
    dst := make([]byte, ascii85.MaxEncodedLen(len(data)))
    n := ascii85.Encode(dst, data)

    return string(dst[:n])
}

The decode() function should return an ArrayBuffer, which requires type conversion by the JavaScript runtime. The sobek.ArrayBuffer go struct corresponds to the JavaScript ArrayBuffer, so an instance of it must be returned. Refer to the sobek.Runtime#ExportTo() documentation for mapping details.

Add the following function to the module.go file:

func (m *module) decode(str string) (sobek.ArrayBuffer, error) {
    dst := make([]byte, len(str))

    n, _, err := ascii85.Decode(dst, []byte(str), true)
    if err != nil {
        return sobek.ArrayBuffer{}, err
    }

    return m.vu.Runtime().NewArrayBuffer(dst[:n]), nil
}

To make the encode() and decode() functions usable within the JavaScript runtime, you have to export them. Add them to the exported symbols in the module.go file.

func (m *module) Exports() modules.Exports {
    return modules.Exports{
        Named: map[string]any{
            "encode": m.encode,
            "decode": m.decode,
        },
    }
}

The Go implementation of the extension is complete.

Build a custom k6 binary

To use the xk6-example-ascii85 extension, a custom k6 build must be created using the xk6 build subcommand.

xk6 build --with github.com/USER/xk6-example-ascii85=.

Replace USER with your GitHub username.

This command creates a custom k6 executable in the current folder.

Run a test with the custom k6 binary

To showcase the extension’s functionality, create a JavaScript file named script.js and add the following code to it:

import { encode } from 'k6/x/example_ascii85';

export default function () {
  console.log(encode(new Uint8Array([72, 101, 108, 108, 111, 33]).buffer)); // 87cURD]o
}

And then run the script using the custom k6 binary:

./k6 run script.js

The script outputs 87cURD]o to the console. This string is the ascii85 encoded representation of Hello!.

Best practices

Create a smoke test

For initial verification before writing comprehensive integration tests, you can create a basic smoke test in test/smoke.test.js.

import { encode, decode } from 'k6/x/example_ascii85';
import { check } from 'k6';

export const options = {
  thresholds: {
    checks: ['rate==1'],
  },
};

export default function () {
  const bytes = new Uint8Array([72, 101, 108, 108, 111, 33]).buffer;

  check(encode(bytes), {
    encoded: (str) => str == '87cURD]o',
    reverse: (str) => equal(bytes, decode(str)),
  });
}

const equal = (a, b) => new Uint8Array(a).toString() === new Uint8Array(b).toString();

This test ensures the correctness of ascii85 encoding and decoding. It uses a fixed Hello! string as a test case for both encoding and decoding processes.

Create Go module tests

Go tests offer the quickest method for verifying extension implementations. Standard unit testing practices apply. For a module-level integration test example, refer to the module_test.go file. This setup facilitates comprehensive integration testing between the Go implementation and the JavaScript runtime.

package example_ascii85

import (
    _ "embed"
    "testing"

    "github.com/stretchr/testify/require"
    "go.k6.io/k6/v2/js/modulestest"
)

func Test_module(t *testing.T) { //nolint:tparallel
    t.Parallel()

    runtime := modulestest.NewRuntime(t)
    err := runtime.SetupModuleSystem(map[string]any{importPath: new(rootModule)}, nil, nil)
    require.NoError(t, err)

    _, err = runtime.RunOnEventLoop(`let mod = require("` + importPath + `")`)
    require.NoError(t, err)

    tests := []struct {
        name  string
        check string
    }{
        // Add your test cases here
        // Example: {name: "myFunc()", check: `mod.myFunc() == expectedValue`},
        {
            name:  "encode()",
            check: `mod.encode(new Uint8Array([72, 101, 108, 108, 111, 33]).buffer) == "87cURD]o"`,
        },
    }
    for _, tt := range tests { //nolint:paralleltest
        t.Run(tt.name, func(t *testing.T) {
            got, err := runtime.RunOnEventLoop(tt.check)

            require.NoError(t, err)
            require.True(t, got.ToBoolean())
        })
    }
}

The provided test code creates an extension instance and integrates it into the JavaScript runtime, accessible as mod. The JavaScript code defining the test is then executed within the JavaScript runtime’s event loop.

Generate API documentation

You can generate HTML API documentation from the index.d.ts API declaration file using TypeDoc. To do this, run the following command that creates the extension API documentation from the index.d.ts file and saves it in the build/docs directory.

bun x typedoc --out build/docs

Security and vulnerability

Ensure the Go source code of your k6 extension is checked for security vulnerabilities using the gosec tool. Like any Go project, security scanning is crucial for your extension’s codebase.

gosec -quiet ./...

Generally, extensions rely on external Go module dependencies. It is advisable to use the govulncheck tool to identify potential vulnerabilities within these dependencies.

govulncheck ./...

Security and vulnerability checks are a requirement for registering the extension in the k6 Extension Registry.

Static analysis

Analyzing the Go source code of your k6 extension statically can proactively identify subtle bugs. golangci-lint is a popular static code analysis tool that even can be used without configuration.

golangci-lint run ./...

Reference

The complete Go source code (module.go) for the extension implementation is provided for reference.

// Package example_ascii85 contains the xk6-example-ascii85 extension.
package example_ascii85

import (
    "encoding/ascii85"

    "github.com/grafana/sobek"
    "go.k6.io/k6/v2/js/modules"
)

type rootModule struct{}

func (*rootModule) NewModuleInstance(vu modules.VU) modules.Instance {
    return &module{vu}
}

type module struct {
    vu modules.VU
}

func (m *module) Exports() modules.Exports {
    return modules.Exports{
        Named: map[string]any{
            "encode": m.encode,
            "decode": m.decode,
        },
    }
}

func (*module) encode(data []byte) string {
    dst := make([]byte, ascii85.MaxEncodedLen(len(data)))
    n := ascii85.Encode(dst, data)

    return string(dst[:n])
}

func (m *module) decode(str string) (sobek.ArrayBuffer, error) {
    dst := make([]byte, len(str))

    n, _, err := ascii85.Decode(dst, []byte(str), true)
    if err != nil {
        return sobek.ArrayBuffer{}, err
    }

    return m.vu.Runtime().NewArrayBuffer(dst[:n]), nil
}

var _ modules.Module = (*rootModule)(nil)

In addition, register.go contains the registration of the extension with the k6 runtime.

package example_ascii85

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

const importPath = "k6/x/example_ascii85"

func init() {
    modules.Register(importPath, new(rootModule))
}

Reference to the JavaScript runtime

In the k6 runtime, each VU (data structure representing a virtual user) has a dedicated JavaScript runtime instance, which can be accessed with the Runtime() function.

m.vu.Runtime()

Additional resources

JavaScript extensions

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

JavaScript extensions

Take advantage of Go’s speed, power, and efficiency while providing the flexibility of using JavaScript APIs within your test scripts.

By implementing k6 interfaces, you can close various gaps in your testing setup:

New network protocols
Improved performance
Features not supported by k6 core

Before you start

To run this tutorial, you’ll need the following applications installed:

You also need to install xk6:

go install go.k6.io/xk6/cmd/xk6@latest

Write a simple extension

First, set up a directory to work in:

mkdir xk6-compare; cd xk6-compare; go mod init xk6-compare

In the directory, make a Go file for your JavaScript extension.

A simple JavaScript extension requires a struct that exposes methods called by the test script.

package compare

import "fmt"

// Compare is the type for our custom API.
type Compare struct{
    ComparisonResult string // textual description of the most recent comparison
}

// IsGreater returns true if a is greater than b, or false otherwise, setting textual result message.
func (c *Compare) IsGreater(a, b int) bool {
    if a > b {
        c.ComparisonResult = fmt.Sprintf("%d is greater than %d", a, b)
        return true
    } else {
        c.ComparisonResult = fmt.Sprintf("%d is NOT greater than %d", a, b)
        return false
    }
}

Note
k6 extensions must have the k6/x/ prefix, and the short name must be unique among all extensions built in the same k6 binary.

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

// init is called by the Go runtime at application startup.
func init() {
    modules.Register("k6/x/compare", new(Compare))
}

Save the file as something like compare.go. The final code looks like this:

package compare

import (
    "fmt"
    "go.k6.io/k6/v2/js/modules"
)

// init is called by the Go runtime at application startup.
func init() {
    modules.Register("k6/x/compare", new(Compare))
}

// Compare is the type for our custom API.
type Compare struct{
    ComparisonResult string // textual description of the most recent comparison
}

// IsGreater returns true if a is greater than b, or false otherwise, setting textual result message.
func (c *Compare) IsGreater(a, b int) bool {
    if a > b {
        c.ComparisonResult = fmt.Sprintf("%d is greater than %d", a, b)
        return true
    } else {
        c.ComparisonResult = fmt.Sprintf("%d is NOT greater than %d", a, b)
        return false
    }
}

Compile your extended k6

To build a k6 binary with this extension, run this command:

xk6 build --with xk6-compare=.

Note
When building from source code, xk6-compare is the Go module name passed to go mod init. Usually, this would be a URL similar to github.com/grafana/xk6-compare.

Use your extension

Now, use the extension in a test script!

Make a file with a name like test.js then add this code:

import compare from 'k6/x/compare';

export default function () {
  console.log(`${compare.isGreater(2, 1)}, ${compare.comparison_result}`);
  console.log(`${compare.isGreater(1, 3)}, ${compare.comparison_result}`);
}

Run the test with ./k6 run test.js.

It should output the following:

INFO[0000] true, 2 is greater than 1                     source=console
INFO[0000] false, 1 is NOT greater than 3                source=console

Use the advanced module API

Caution
The advanced module API adds significant complexity to your extension. Consider whether you actually need access to internal k6 objects before implementing this pattern. For simple modules that don’t need VU state or runtime access, the basic approach shown above is sufficient.

Suppose your extension needs access to internal k6 objects to, for example, inspect the state of the test during execution. We will need to make slightly more complicated changes to the above example.

Our main Compare struct should implement the modules.Instance interface to access the modules.VU to inspect internal k6 objects such as:

lib.State, the VU state with values like the VU ID and iteration number
sobek.Runtime, the JavaScript runtime used by the VU
a global context.Context containing objects like the lib.ExecutionState

Additionally, there should be a root module implementation of the modules.Module interface to serve as a factory of Compare instances for each VU.

Here’s what that would look like:

package compare

import (
    "fmt"
    "go.k6.io/k6/v2/js/modules"
)

// init is called by the Go runtime at application startup.
func init() {
    modules.Register("k6/x/compare", New())
}

type (
    // RootModule is the global module instance that will create module
    // instances for each VU.
    RootModule struct{}

    // ModuleInstance represents an instance of the JS module.
    ModuleInstance struct {
        // vu provides methods for accessing internal k6 objects for a VU
        vu modules.VU
        // comparator is the exported type
        comparator *Compare
    }
)

// Ensure the interfaces are implemented correctly.
var (
    _ modules.Instance = &ModuleInstance{}
    _ modules.Module   = &RootModule{}
)

// New returns a pointer to a new RootModule instance.
func New() *RootModule {
    return &RootModule{}
}

// NewModuleInstance implements the modules.Module interface returning a new instance for each VU.
func (*RootModule) NewModuleInstance(vu modules.VU) modules.Instance {
    return &ModuleInstance{
        vu: vu,
        comparator: &Compare{vu: vu},
    }
}

// Compare is the type for our custom API.
type Compare struct{
    vu modules.VU           // provides methods for accessing internal k6 objects
    ComparisonResult string // textual description of the most recent comparison
}

// IsGreater returns true if a is greater than b, or false otherwise, setting textual result message.
func (c *Compare) IsGreater(a, b int) bool {
    if a > b {
        c.ComparisonResult = fmt.Sprintf("%d is greater than %d", a, b)
        return true
    } else {
        c.ComparisonResult = fmt.Sprintf("%d is NOT greater than %d", a, b)
    return false
    }
}

// Exports implements the modules.Instance interface and returns the exported types for the JS module.
func (mi *ModuleInstance) Exports() modules.Exports {
    return modules.Exports{
        Default: mi.comparator,
    }
}

Note
Notice that we implemented the Module API and now modules.Register the root module rather than our Compare object!

Accessing runtime state

At this time, we’ve provided access to the modules.VU from the Compare type; however, we aren’t taking advantage of the methods provided. Here is a contrived example of how we can utilize the runtime state:

// InternalState holds basic metadata from the runtime state.
type InternalState struct {
	ActiveVUs       int64       `js:"activeVUs"`
	Iteration       int64
	VUID            uint64      `js:"vuID"`
	VUIDFromRuntime sobek.Value `js:"vuIDFromRuntime"`
}

// GetInternalState interrogates the current virtual user for state information.
func (c *Compare) GetInternalState() *InternalState {
	state := c.vu.State()
	ctx := c.vu.Context()
	es := lib.GetExecutionState(ctx)
	rt := c.vu.Runtime()

	return &InternalState{
		VUID:            state.VUID,
		VUIDFromRuntime: rt.Get("__VU"),
		Iteration:       state.Iteration,
		ActiveVUs:       es.GetCurrentlyActiveVUsCount(),
	}
}

Create a test script to utilize the new getInternalState() function as in the following:

import compare from 'k6/x/compare';

export default function () {
  const state = compare.getInternalState();
  console.log(
    `Active VUs: ${state.activeVUs}, Iteration: ${state.iteration}, VU ID: ${state.vuID}, VU ID from runtime: ${state.vuIDFromRuntime}`
  );
}

Executing the script as ./k6 run test-state.js --vus 2 --iterations 5 will produce output similar to the following:

INFO[0000] Active VUs: 2, Iteration: 0, VU ID: 2, VU ID from runtime: 2  source=console
INFO[0000] Active VUs: 2, Iteration: 0, VU ID: 1, VU ID from runtime: 1  source=console
INFO[0000] Active VUs: 2, Iteration: 1, VU ID: 2, VU ID from runtime: 2  source=console
INFO[0000] Active VUs: 2, Iteration: 1, VU ID: 1, VU ID from runtime: 1  source=console
INFO[0000] Active VUs: 2, Iteration: 2, VU ID: 2, VU ID from runtime: 2  source=console

Things to keep in mind

The code in the default function (or another function specified by exec) will be executed many times during a test run and possibly in parallel by thousands of VUs. Any operation of your extension should therefore be performant and thread-safe.
Any heavy initialization should be done in the init context, if possible, and not as part of the default function execution.
Use the registry’s NewMetric method to create custom metrics; to emit them, use metrics.PushIfNotDone().

Questions? Feel free to join the discussion on extensions in the k6 Community Forum.

Next, create an Output extension to publish test metrics to a destination not already supported by k6.

Output extensions

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

Output extensions

k6 provides many metrics and output formats, but it cannot directly support all possibilities. To store or alter metrics captured during an active k6 test, you can create a custom output extension.

Output extension binaries can use the --out flag to send metrics to a custom place. Some potential reasons for a custom extension could include:

To support a time-series database not already supported
To add derived metrics data for storage
To filter metrics to only the data you care about

Like JavaScript extensions, output extensions rely on the extension author to implement specific APIs.

Before you start:

To run this tutorial, you’ll need the following applications installed:

You also need to install xk6:

go install go.k6.io/xk6/cmd/xk6@latest

Write a simple extension

Set up a directory to work in.

mkdir xk6-output-logger; cd xk6-output-logger; go mod init xk6-output-logger

The core of an Output extension is a struct that implements the output.Output interface.

Create a simple example that outputs each set of metrics to the console as received by the AddMetricSamples(samples []metrics.SampleContainer) method of the output interface.

package log

import (
    "fmt"
    "strings"
    "time"

    "go.k6.io/k6/v2/metrics"
    "go.k6.io/k6/v2/output"
)

// AddMetricSamples receives metric samples from the k6 Engine as they're emitted.
func (l *Logger) AddMetricSamples(samples []metrics.SampleContainer) {
    for _, sample := range samples {
        all := sample.GetSamples()
        fmt.Fprintf(l.out, "%s [%s]\n", all[0].GetTime().Format(time.RFC3339Nano), metricKeyValues(all))
    }
}

// metricKeyValues returns a string of key-value pairs for all metrics in the sample.
func metricKeyValues(samples []metrics.Sample) string {
    names := make([]string, 0, len(samples))
    for _, sample := range samples {
        names = append(names, fmt.Sprintf("%s=%v", sample.Metric.Name, sample.Value))
    }
    return strings.Join(names, ", ")
}

import "go.k6.io/k6/v2/output"

// init is called by the Go runtime at application startup.
func init() {
    output.RegisterExtension("logger", New)
}

Note
You must use the registered with the -o, or --out flag when running k6!

The final extension code looks like this:

package log

import (
    "fmt"
    "io"
    "strings"
    "time"

    "go.k6.io/k6/v2/metrics"
    "go.k6.io/k6/v2/output"
)

// init is called by the Go runtime at application startup.
func init() {
    output.RegisterExtension("logger", New)
}

// Logger writes k6 metric samples to stdout.
type Logger struct {
    out io.Writer
}

// New returns a new instance of Logger.
func New(params output.Params) (output.Output, error) {
    return &Logger{params.StdOut}, nil
}

// Description returns a short human-readable description of the output.
func (*Logger) Description() string {
    return "logger"
}

// Start initializes any state needed for the output, establishes network
// connections, etc.
func (*Logger) Start() error {
    return nil
}

// AddMetricSamples receives metric samples from the k6 Engine as they're emitted.
func (l *Logger) AddMetricSamples(samples []metrics.SampleContainer) {
    for _, sample := range samples {
        all := sample.GetSamples()
        fmt.Fprintf(l.out, "%s [%s]\n", all[0].GetTime().Format(time.RFC3339Nano), metricKeyValues(all))
    }
}

// metricKeyValues returns a string of key-value pairs for all metrics in the sample.
func metricKeyValues(samples []metrics.Sample) string {
    names := make([]string, 0, len(samples))
    for _, sample := range samples {
        names = append(names, fmt.Sprintf("%s=%v", sample.Metric.Name, sample.Value))
    }
    return strings.Join(names, ", ")
}

// Stop finalizes any tasks in progress, closes network connections, etc.
func (*Logger) Stop() error {
    return nil
}

Notice a couple of things:

The module initializer New() receives an instance of output.Params. With this object, the extension can access the output-specific configuration, interfaces to the filesystem, synchronized stdout and stderr, and more.
AddMetricSamples in this example writes to stdout. This output might have to be buffered and flushed periodically in a real-world scenario to avoid memory leaks. Below we’ll discuss some helpers you can use for that.

Compile your extended k6

To build a k6 binary with this extension, run:

xk6 build --with xk6-output-logger=.

Note
xk6-output-logger is the Go module name passed to go mod init

Usually, this would be a URL similar to github.com/grafana/xk6-output-logger.

Use your extension

Now we can use the extension with a test script.

In new JavaScript file, make some simple test logic.

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

export default function () {
  http.get('https://quickpizza.grafana.com');
  sleep(0.5);
}

Now, run the test.

./k6 run test.js --out logger --quiet --summary-mode=disabled --iterations 2

Note
The --out logger argument tells k6 to use your custom output. The flag --quiet --summary-mode=disabled configures k6 to show only custom output.

Your output should look something like this:

2022-07-01T08:55:09.59272-05:00 [http_reqs=1, http_req_duration=117.003, http_req_blocked=558.983, http_req_connecting=54.135, http_req_tls_handshaking=477.198, http_req_sending=0.102, http_req_waiting=116.544, http_req_receiving=0.357, http_req_failed=0]
2022-07-01T08:55:09.917036-05:00 [vus=1, vus_max=1]
2022-07-01T08:55:10.094196-05:00 [data_sent=446, data_received=21364, iteration_duration=1177.505083, iterations=1]
2022-07-01T08:55:10.213926-05:00 [http_reqs=1, http_req_duration=119.122, http_req_blocked=0.015, http_req_connecting=0, http_req_tls_handshaking=0, http_req_sending=0.103, http_req_waiting=118.726, http_req_receiving=0.293, http_req_failed=0]
2022-07-01T08:55:10.715323-05:00 [data_sent=102, data_received=15904, iteration_duration=620.862459, iterations=1]

Things to keep in mind

Output structs can optionally implement additional interfaces that allow them to receive thresholds or run-status updates and even interrupt a test.
Consider using output.SampleBuffer and output.PeriodicFlusher to improve performance given the large amounts of data produced by k6. Refer to statsd output for an example.
Use the project template as a starting point for your output extension.

Questions? Feel free to join the discussion on extensions in the k6 Community Forum.

Secret source extensions

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

Secret Source extensions

Secret source extension allow users to write or use written by other users extensions in order to get secrets to be used within k6 tests.

Like JavaScript extensions, secret source extensions rely on the extension author to implement specific APIs.

Before you start:

To run this tutorial, you’ll need the following applications installed:

You also need to install xk6:

$ go install go.k6.io/xk6/cmd/xk6@latest

Write a simple extension

Set up a directory to work in.

$ mkdir xk6-secret-source-cli; cd xk6-secret-source-cli; go mod init xk6-secret-source-cli

The core of an Output extension is a struct that implements the secrets.Source interface.

Create a simple example secret source that just reads the secrets from the cli flag - similar to the in built mock one.

package cli

import (
	"errors"
	"fmt"
	"strings"

	"go.k6.io/k6/v2/secretsource"
)

func newCLISecretSourceFromParams(params secretsource.Params) (secretsource.Source, error) {
	list := strings.Split(params.ConfigArgument, ",")
	secrets := make(map[string]string, len(list))
	for _, kv := range list {
		k, v, ok := strings.Cut(kv, "=")
		if !ok {
			return nil, fmt.Errorf("parsing %q, needs =", kv)
		}

		secrets[k] = v
	}
	return &cliSecretSource{internal: secrets}
}

type cliSecretSource struct {
	internal map[string]string
}

func (*cliSecretSource) Description() string {
	return "this is an example secret source"
}

func (css *cliSecretSource) Get(key string) (string, error) {
	v, ok := css.internal[key]
	if !ok {
		return "", errors.New("no value")
	}
	return v, nil
}

package cli

import "go.k6.io/k6/v2/secretsource"

// init is called by the Go runtime at application startup.
func init() {
	secretsource.RegisterExtension("cli", newCLISecretSourceFromParams)
}

Note
You must use the registered with the --secret-source flag when running k6!

The final extension code looks like this:

package cli

import (
	"errors"
	"fmt"
	"strings"

	"go.k6.io/k6/v2/secretsource"
)

// init is called by the Go runtime at application startup.
func init() {
	secretsource.RegisterExtension("cli", newCLISecretSourceFromParams)
}

func newCLISecretSourceFromParams(params secretsource.Params) (secretsource.Source, error) {
	list := strings.Split(params.ConfigArgument, ",")
	secrets := make(map[string]string, len(list))
	for _, kv := range list {
		k, v, ok := strings.Cut(kv, "=")
		if !ok {
			return nil, fmt.Errorf("parsing %q, needs =", kv)
		}

		secrets[k] = v
	}
	return &cliSecretSource{internal: secrets}, nil
}

type cliSecretSource struct {
	internal map[string]string
}

func (*cliSecretSource) Description() string {
	return "this is an example secret source"
}

func (css *cliSecretSource) Get(key string) (string, error) {
	v, ok := css.internal[key]
	if !ok {
		return "", errors.New("no value")
	}
	return v, nil
}

Notice a couple of things:

The module initializer newCLISecretSourceFromParams() receives an instance of secretsource.Params. With this object, the extension can access the secret source specific configuration, interfaces to the filesystem, it cli args, logger, etc.
Get in this example just returns from an internal array, but it also can do network requests or anything else it needs to get secrets.

Compile your extended k6

To build a k6 binary with this extension, run:

$ go mod tidy # this is needed by the go toolchain
$ xk6 build --with xk6-secret-source-cli=.

Note
xk6-secret-source-cli is the Go module name passed to go mod init

Usually, this would be a URL similar to github.com/grafana/xk6-secret-source-cli.

Use your extension

Now we can use the extension with a test script.

In new JavaScript file, make some simple test logic.

import secrets from 'k6/secrets';

export default async () => {
  const my_secret = await secrets.get('cool'); // get secret from a source with the provided identifier
  console.log(my_secret);
  await secrets.get('else'); // get secret from a source with the provided identifier
  console.log(my_secret); // print the same old secret to see that the secret from above will also be redacted
  console.log('some'); // log the original secret but using its constant value
};

Now, run the test.

./k6 run test.js --secret-source=cli=cool=some,else=console --quiet --summary-mode=disabled

Note
The --secret-source=cli=cool=some,else=console argument tells k6 to use your custom secret source and gives its configuration. The flag --quiet --summary-mode=disabled configures k6 to show only custom output.

Your output should look something like this:

INFO[0000] ***SECRET_REDACTED***                         source=console
INFO[0000] ***SECRET_REDACTED***                         source="***SECRET_REDACTED***"
INFO[0000] ***SECRET_REDACTED***                         source="***SECRET_REDACTED***"

As you can see there is quite a lot of redacted secrets. And also that console is only redacted after it is accessed as before that k6 can not know it is actually a secret.

Note
Real world secrets are not expected to be common strings that will be found naturally in the k6 output as is in this example.

Things to keep in mind

Questions? Feel free to join the discussion on extensions in the k6 Community Forum.

Subcommand extensions

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

Subcommand extensions

k6 provides a rich set of built-in commands, but some use cases require custom CLI tools that integrate with k6’s runtime and state. Subcommand extensions allow you to register custom commands under the k6 x namespace, providing a standardized way to extend k6’s CLI functionality.

Subcommand extensions are useful for:

Setup and configuration tools (for example, verifying system requirements)
Custom validation and testing utilities
Integration tools that interact with k6’s runtime state
Helper commands specific to your testing infrastructure

You can use registered subcommand extensions directly without building a custom binary, or build a custom k6 binary for extensions you’re developing or that aren’t available in the registry.

Before you begin

To run this tutorial, you’ll need the following applications installed:

You also need to install xk6:

go install go.k6.io/xk6/cmd/xk6@latest

Write a simple extension

Set up a directory to work in.

mkdir xk6-subcommand-mytool; cd xk6-subcommand-mytool; go mod init xk6-subcommand-mytool

The core of a subcommand extension is a constructor function that creates a Cobra command. The constructor receives k6’s GlobalState for read-only access to runtime configuration.

Create an example command named mytool:

package mytool

import (
    "github.com/spf13/cobra"
    "go.k6.io/k6/v2/cmd/state"
    "go.k6.io/k6/v2/subcommand"
)

func init() {
    subcommand.RegisterExtension("mytool", newCommand)
}

func newCommand(gs *state.GlobalState) *cobra.Command {
    return &cobra.Command{
        Use:   "mytool",
        Short: "My custom tool",
        Long:  "A custom tool that integrates with k6",
        Run: func(cmd *cobra.Command, args []string) {
            gs.Logger.Info("Running mytool")
            // Custom logic here
        },
    }
}

The extension uses the subcommand.RegisterExtension function to register itself during initialization. The first argument is the command name (which must match the command’s Use field), and the second is the constructor function.

Caution
The GlobalState provided to your command is read-only. Do not modify it, as this can cause core k6 instability.

Use automatic extension resolution

If your subcommand extension is registered in the k6 extension catalog, you can use it directly without building a custom binary. k6 automatically detects, builds, and loads the extension when you invoke it:

k6 x mytool

This works for any registered subcommand extension. k6 provisions the required extension transparently and executes your command.

Note
To use community extensions you must have K6_ENABLE_COMMUNITY_EXTENSIONS set to true.
Bash
K6_ENABLE_COMMUNITY_EXTENSIONS=true k6 x mytool

For real-world examples of official subcommand extensions that ship through this exact path, see the k6 MCP server (exposed as k6 x mcp) and k6 x agent, which scaffolds AI editor integrations on top of it.

Disable automatic extension resolution

You can disable this feature by setting the environment variable K6_AUTO_EXTENSION_RESOLUTION to false:

K6_AUTO_EXTENSION_RESOLUTION=false k6 x mytool

Discover available subcommands

Running k6 x without arguments lists the available subcommands, both the ones built into the binary and those advertised by the extension catalog (official and community):

$ k6 x
...
Available Commands:
  agent       Bootstrap an AI-assisted k6 testing workflow in any editor
  docs        CLI k6 docs for AI agents and users
  explore     Explore k6 extensions for Automatic Resolution
  mcp         An MCP server for k6 for AI agents

Shell tab-completion surfaces the same set once the catalog has been cached locally by a prior k6 x run, so completion never blocks on the network. This makes a k6 binary self-describing, which is particularly useful for AI agents driving k6.

Build a custom k6 binary

To use subcommand extensions you’re developing or that aren’t available in the registry, build a custom k6 binary with xk6:

xk6 build --with xk6-subcommand-mytool=.

This creates a k6 binary in your current directory that includes your extension.

After building, your subcommand is available under the k6 x namespace:

./k6 x mytool

To see all available extension subcommands:

./k6 x help

Constructor requirements

The constructor function passed to RegisterExtension must:

Accept a single *state.GlobalState parameter
Return a *cobra.Command
Create a command whose Use field matches the registered extension name

Violating these requirements causes the extension to panic at startup, ensuring configuration errors are caught early.

Example: Complete validation tool

Here’s a more complete example that checks system requirements:

package validate

import (
    "fmt"
    "os"
    "runtime"

    "github.com/spf13/cobra"
    "go.k6.io/k6/v2/cmd/state"
    "go.k6.io/k6/v2/subcommand"
)

func init() {
    subcommand.RegisterExtension("validate", newValidateCommand)
}

func newValidateCommand(gs *state.GlobalState) *cobra.Command {
    cmd := &cobra.Command{
        Use:   "validate",
        Short: "Verify system requirements",
        Long:  "Check if the system meets requirements for running tests",
        RunE: func(cmd *cobra.Command, args []string) error {
            gs.Logger.Info("Checking system requirements...")
            
            // Check Go version
            gs.Logger.Infof("Go version: %s", runtime.Version())
            
            // Check available memory
            var m runtime.MemStats
            runtime.ReadMemStats(&m)
            gs.Logger.Infof("Available memory: %d MB", m.Sys/1024/1024)
            
            // Check environment variables
            if broker := os.Getenv("MQTT_BROKER"); broker != "" {
                gs.Logger.Infof("MQTT broker configured: %s", broker)
            } else {
                gs.Logger.Warn("MQTT_BROKER not set")
            }
            
            gs.Logger.Info("Validation complete")
            return nil
        },
    }
    
    return cmd
}

Usage:

./k6 x validate

Access k6 runtime state

The GlobalState provides read-only access to k6’s configuration:

func newCommand(gs *state.GlobalState) *cobra.Command {
    return &cobra.Command{
        Use:   "validate",
        Short: "Validate k6 configuration",
        Run: func(cmd *cobra.Command, args []string) {
            // Access logger
            gs.Logger.Info("Validating k6 configuration...")
            
            // Access flags and options
            if gs.Flags.Verbose {
                gs.Logger.Debug("Verbose mode enabled")
            }
            
            // Access environment variables
            gs.Logger.Infof("Working directory: %s", gs.Getwd)
        },
    }
}

Add command flags

Use Cobra’s flag system to add options to your subcommand:

func newCommand(gs *state.GlobalState) *cobra.Command {
    var target string
    var verbose bool
    
    cmd := &cobra.Command{
        Use:   "validate",
        Short: "Validate configuration",
        Run: func(cmd *cobra.Command, args []string) {
            if verbose {
                gs.Logger.Info("Verbose mode enabled")
            }
            gs.Logger.Infof("Validating target: %s", target)
            // Validation logic here
        },
    }
    
    cmd.Flags().StringVarP(&target, "target", "t", "localhost", "Target to validate")
    cmd.Flags().BoolVarP(&verbose, "verbose", "v", false, "Enable verbose output")
    
    return cmd
}

Usage:

./k6 x validate --target example.com --verbose

Best practices

Read-only state: Never modify the GlobalState passed to your constructor
Naming: Use descriptive, kebab-case names for your commands
Documentation: Provide clear Short and Long descriptions
Error handling: Return errors from RunE rather than panicking in command execution
Logging: Use gs.Logger for consistent output with k6’s logging system

About the Extensions Registry

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

About the Extensions Registry

Did you create an extension and want to share it with your fellow k6 users? We’d love to spread word of this new feature adding to our registry of available extensions. However, before an extension is added to the registry, we must ensure that it is maintained to the registry standard.

Our desire is to provide the best developer experience when using k6. This extends to the extensions ecosystem as well. The adaptability provided by k6 extensions opens a wide array of potential use cases.

To ensure quality, we need a well-maintained, curated listing of extensions. Our pledge to the community is to make our best attempt to ensure the listed projects meet certain standards. While we cannot guarantee the quality of community-provided extensions, we can aid the evaluation by requiring certain consistencies.

Registry requirements

At minimum, each source code repository must have the following:

a README file

The README must contain documentation such as the project description, build and usage instructions, as well as k6 version compatibility. The goal is to provide enough information to quickly and easily evaluate the extension.
the xk6 topic set

GitHub allows setting topics for a repository. This supports querying all public repositories based upon a keyword for better discoverability, i.e. “xk6”. See the GitHub documentation to add topics.
a non-restrictive license

Any open source software (OSS) license will suffice, but Apache2 is preferred.
an examples folder with examples

Provide at least one script to show proper usage of your API. If a Docker Compose specification is provided, these could be used as integration tests to validate the extension works as intended.
at least one versioned release

As features or fixes are ready to be consumed, create a release. This promotes stability by allowing a user to utilize a particular version. Use semantic versioning to communicate changes as the extension evolves.
builds with a recent k6 version

Ideally, the extension should build with the latest release. But, it must build with a version of k6 that is no more than three releases old. For example, if latest version of k6 is v0.100, the extension must build with at least version v0.98. Be sure to also match the version of Go as determined by the version of k6.

Naming conventions

Some extensions may be very specific, where others are more general. Multiple extensions may even be created for the same product with different levels of support based upon version. By adhering to typical naming conventions, your extension name can remove some doubts as to what is supported.

For any extension, we recommend the xk6- prefix as well as an optional output- for Output extensions. Next, provide the product or protocol name; don’t be cryptic. Ensure the usage is explicit by adopting only well-known acronyms or abbreviations if necessary. If your extension supports only a specific version of a product, incorporate the version into the name, for example v2.

As an example, suppose an extension that outputs test metrics to the AwesomeLog application, and it uses only the v2 API. In this case, say the latest v3 API is not backward-compatible. Applying our conventions, we’d recommend naming this repository as xk6-output-awesomelog-v2.

Note
Our goal is to quickly understand the intent of the extension.

Potential for de-listing

Given our desire to provide the best developer experience when using k6, we reserve the right to de-list any extension we deem is no longer maintaining standards. Before any action takes place, the extension maintainers will be contacted to be given a chance to rectify the project and thus avoid de-listing. Such contact may be in the form of GitHub issues or merge requests.

Should any extension be de-listed, this does not constitute a permanent removal. Any extension that has been de-listed may be reinstated once the reasons for the initial removal have been remediated.

About the Go-to-JS bridge

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

About the Go-to-JS bridge

All k6 and xk6 binaries have an embedded JavaScript engine, sobek, which your test scripts run on.

You will deepen your conceptual knowledge of how your k6 extension works if you understand the bridge between Go internals and the JavaScript runtime.

Go-to-JavaScript bridge features

The bridge has a few features we should highlight:

Go method names are converted from Pascal to Camel case when accessed in JS. For example, IsGreater becomes isGreater.
Go field names convert from Pascal to Snake case. For example, the struct field ComparisonResult string becomes comparison_result in JS.
Field names may be explicit using js struct tags. For example, declaring the field as ComparisonResult string `js:“result”` or hiding from JS using `js:"-"`.

Type conversion and native constructors

The JavaScript runtime transparently converts Go types like int64 to their JS equivalent. For complex types where this is impossible, your script might fail with a TypeError, requiring you to explicitly convert your object to a sobek.Object or sobek.Value.

func (*Compare) XComparator(call sobek.ConstructorCall, rt *sobek.Runtime) *sobek.Object {
	return rt.ToValue(&Compare{}).ToObject(rt)
}

The preceding snippet also demonstrates the native constructors feature from sobek, where methods can become JS constructors. Methods with this signature can create Comparator instances in JS with new compare.Comparator(). While this is more idiomatic to JS, it still has the benefit of receiving the sobek.Runtime.