Creating Extensions

Build custom k6 extensions in Go to add new functionality

Create custom k6 extensions to add JavaScript modules, output formats, secret sources, or CLI subcommands. Extensions are written in Go and compiled into k6 using xk6.

Prerequisites

• Go 1.22 or later
• Understanding of Go programming
• Familiarity with k6 concepts
• Git for version control

Extension Types

You can create four types of extensions:

1. JavaScript Extensions: Add custom JavaScript APIs
2. Output Extensions: Create custom result outputs
3. Secret Source Extensions: Implement secret providers
4. Subcommand Extensions: Add CLI subcommands

See Extensions Overview for details on each type.

Project Setup

Follow the xk6- naming convention for discoverability. Name your extension repository xk6-extensionname.

Creating a JavaScript Extension

JavaScript extensions add custom modules that can be imported in test scripts.

Basic Structure

package myextension

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

func init() {
    modules.Register("k6/x/myextension", New())
}

type RootModule struct{}
type ModuleInstance struct {
    vu modules.VU
}

func New() *RootModule {
    return &RootModule{}
}

func (r *RootModule) NewModuleInstance(vu modules.VU) modules.Instance {
    return &ModuleInstance{vu: vu}
}

func (mi *ModuleInstance) Exports() modules.Exports {
    return modules.Exports{Default: mi}
}

Adding Functionality

Add methods that will be available in JavaScript:

func (mi *ModuleInstance) Greet(name string) string {
    return "Hello, " + name + "!"
}

func (mi *ModuleInstance) Add(a, b int) int {
    return a + b
}

Use in JavaScript:

import myext from 'k6/x/myextension';

export default function () {
  console.log(myext.greet('World'));
  console.log(myext.add(2, 3));
}

Working with Metrics

Create custom metrics in your extension:

import (
    "go.k6.io/k6/js/modules"
    "go.k6.io/k6/metrics"
    "time"
)

type ModuleInstance struct {
    vu     modules.VU
    custom *metrics.Metric
}

func (r *RootModule) NewModuleInstance(vu modules.VU) modules.Instance {
    return &ModuleInstance{
        vu:     vu,
        custom: vu.InitEnv().Registry.MustNewMetric("custom_metric", metrics.Counter),
    }
}

func (mi *ModuleInstance) RecordValue(value float64) {
    state := mi.vu.State()
    ctx := mi.vu.Context()
    
    tags := state.Tags.GetCurrentValues().Tags
    metrics.PushIfNotDone(ctx, state.Samples, metrics.Sample{
        Time:       time.Now(),
        TimeSeries: metrics.TimeSeries{Metric: mi.custom, Tags: tags},
        Value:      value,
    })
}

Always check if vu.State() is nil. It will be nil in the init context where metric emission is not allowed.

Real Example

Here’s a real JavaScript extension from k6’s test suite (xk6-js-test/jstest.go:1):

package jstest

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

func init() {
    modules.Register("k6/x/jsexttest", New())
}

type (
    RootModule struct{}
    JSTest struct {
        vu   modules.VU
        foos *metrics.Metric
    }
)

func New() *RootModule {
    return &RootModule{}
}

func (*RootModule) NewModuleInstance(vu modules.VU) modules.Instance {
    return &JSTest{
        vu:   vu,
        foos: vu.InitEnv().Registry.MustNewMetric("foos", metrics.Counter),
    }
}

func (j *JSTest) Exports() modules.Exports {
    return modules.Exports{Default: j}
}

func (j *JSTest) Foo(arg float64) (bool, error) {
    state := j.vu.State()
    if state == nil {
        return false, fmt.Errorf("the VU State is not available in the init context")
    }
    
    ctx := j.vu.Context()
    tags := state.Tags.GetCurrentValues().Tags.With("foo", "bar")
    metrics.PushIfNotDone(ctx, state.Samples, metrics.Sample{
        Time:       time.Now(),
        TimeSeries: metrics.TimeSeries{Metric: j.foos, Tags: tags},
        Value:      arg,
    })
    
    return true, nil
}

Creating an Output Extension

Output extensions send test results to custom backends.

Basic Implementation

See Creating Custom Outputs for a comprehensive guide.

Quick example:

package myoutput

import (
    "go.k6.io/k6/output"
    "go.k6.io/k6/metrics"
)

func init() {
    output.RegisterExtension("myoutput", New)
}

type Output struct {
    output.SampleBuffer
    params output.Params
}

func New(params output.Params) (output.Output, error) {
    return &Output{params: params}, nil
}

func (o *Output) Description() string {
    return "my-custom-output"
}

func (o *Output) Start() error {
    return nil
}

func (o *Output) Stop() error {
    samples := o.GetBufferedSamples()
    // Process samples
    return nil
}

Creating a Secret Source Extension

Secret source extensions provide secure configuration values.

Implementation

package mysecrets

import (
    "go.k6.io/k6/ext"
)

func init() {
    ext.Register("mysecrets", ext.SecretSourceExtension, &SecretSource{})
}

type SecretSource struct{}

func (s *SecretSource) GetSecret(key string) (string, error) {
    // Fetch secret from your backend
    return fetchSecretFromVault(key)
}

Creating a Subcommand Extension

Subcommand extensions add new CLI commands to k6.

Implementation

package mycommand

import (
    "github.com/spf13/cobra"
    "go.k6.io/k6/ext"
)

func init() {
    ext.Register("mycommand", ext.SubcommandExtension, NewCommand)
}

func NewCommand() *cobra.Command {
    return &cobra.Command{
        Use:   "mycommand",
        Short: "My custom command",
        RunE: func(cmd *cobra.Command, args []string) error {
            // Command implementation
            return nil
        },
    }
}

Use it:

k6 mycommand [args]

Extension Registration

All extensions must register in an init() function using ext.Register() (ext/ext.go:62):

import "go.k6.io/k6/ext"

func init() {
    ext.Register(
        "extensionname",           // Name
        ext.JSExtension,            // Type
        New(),                      // Module/implementation
    )
}

Registration happens automatically when the extension package is imported during build.

Testing Your Extension

Unit Tests

package myextension

import (
    "testing"
    "github.com/stretchr/testify/assert"
)

func TestGreet(t *testing.T) {
    mi := &ModuleInstance{}
    result := mi.Greet("World")
    assert.Equal(t, "Hello, World!", result)
}

Integration Tests

Create a test script:

// test.js
import myext from 'k6/x/myextension';
import { check } from 'k6';

export default function () {
  const result = myext.greet('k6');
  check(result, {
    'greeting works': (r) => r === 'Hello, k6!',
  });
}

Build and test:

xk6 build --with github.com/yourname/xk6-myextension=.
./k6 run test.js

Building and Using

Local Development

Build k6 with your local extension:

xk6 build --with github.com/yourname/xk6-myextension=.

Publishing

Best Practices

Common Patterns

Connection Pooling

type ModuleInstance struct {
    vu   modules.VU
    pool *ConnectionPool
}

func (r *RootModule) NewModuleInstance(vu modules.VU) modules.Instance {
    return &ModuleInstance{
        vu:   vu,
        pool: getOrCreatePool(vu),
    }
}

Configuration

type Config struct {
    Host string `json:"host"`
    Port int    `json:"port"`
}

func (r *RootModule) NewModuleInstance(vu modules.VU) modules.Instance {
    var config Config
    if err := json.Unmarshal(vu.InitEnv().Options, &config); err != nil {
        // Handle error
    }
    return &ModuleInstance{config: config}
}

Resource Cleanup

func (mi *ModuleInstance) Close() error {
    if mi.connection != nil {
        return mi.connection.Close()
    }
    return nil
}

Debugging

Enable Verbose Logging

import "github.com/sirupsen/logrus"

func (mi *ModuleInstance) Debug(msg string) {
    logger := mi.vu.InitEnv().Logger
    logger.WithField("extension", "myext").Debug(msg)
}

Use k6 Verbose Mode

./k6 run --verbose test.js

Example Extensions

Study these official examples:

• xk6-redis: https://github.com/grafana/xk6-redis
• xk6-kafka: https://github.com/mostafa/xk6-kafka
• xk6-sql: https://github.com/grafana/xk6-sql
• xk6-browser: https://github.com/grafana/xk6-browser

Resources

• k6 Extension Registry
• xk6 Documentation
• k6 API Documentation
• Community Forum

Next Steps

• Using Extensions - Learn to use extensions
• Extensions Overview - Understand extension types
• Creating Custom Outputs - Specialized output guide