Create a k6 Extension

Build custom k6 extensions in Go to add JavaScript APIs, output formats, secret sources, or CLI commands

If you find a gap in your testing process that no k6 extension can fix, consider building your own extension.

Before you begin

Anyone who can use the command line to edit files and install software should be able to follow along. However, if you want to create an extension for production use, you should have:

• Familiarity with both Go (Golang) and JavaScript, and their tooling
• Understanding of how the Go-to-JavaScript bridge works within k6

Prerequisites

Install the required tools:

1. Install Go

   Download and install Go (version 1.19 or higher).

2. Install Git

   Install Git for version control.

3. Install xk6

   Install the xk6 extension builder:

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

Verify your installation:

xk6 version

Avoid unneeded work

Before creating a new extension:

• Check existing extensions - Review the Extensions catalog and the xk6 topic on GitHub
• Prefer generic solutions - If you can test with a generic protocol like MQTT, use xk6-mqtt over building a custom protocol extension
• Consider pure JavaScript - A JavaScript library will be better supported, more straightforward, and reusable than an extension

JavaScript extensions

JavaScript extensions extend the JavaScript APIs available to your test scripts. They can add support for new network protocols, improve performance, or add features.

Create a simple extension

1. Set up the project

   Create a directory and initialize a Go module:

   mkdir xk6-compare
   cd xk6-compare
   go mod init xk6-compare
   
2. Write the Go code

   Create compare.go with a struct that exposes methods:

   package compare
   
   import (
       "fmt"
       "go.k6.io/k6/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.
   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
       }
   }
   
3. Build the extension

   Compile k6 with your extension:

   xk6 build --with xk6-compare=.
   
4. Use in a test script

   Create test.js:

   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:

   ./k6 run test.js
   

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

Advanced module API

For extensions that need access to internal k6 objects (VU state, runtime), implement the advanced module API:

package compare

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

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

type (
    // RootModule is the global module instance.
    RootModule struct{}
    
    // ModuleInstance represents an instance for each VU.
    ModuleInstance struct {
        vu modules.VU
        comparator *Compare
    }
)

var (
    _ modules.Instance = &ModuleInstance{}
    _ modules.Module   = &RootModule{}
)

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

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

type Compare struct{
    vu modules.VU
    ComparisonResult string
}

func (c *Compare) IsGreater(a, b int) bool {
    // Implementation with access to c.vu for VU state
    // ...
}

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

Output extensions

Output extensions send metrics to a custom file format or service. They can add custom processing and dispatching methods.

Create an output extension

1. Set up the project

   mkdir xk6-output-logger
   cd xk6-output-logger
   go mod init xk6-output-logger
   
2. Implement the Output interface

   Create logger.go:

   package log
   
   import (
       "fmt"
       "io"
       "strings"
       "time"
       
       "go.k6.io/k6/metrics"
       "go.k6.io/k6/output"
   )
   
   func init() {
       output.RegisterExtension("logger", New)
   }
   
   type Logger struct {
       out io.Writer
   }
   
   func New(params output.Params) (output.Output, error) {
       return &Logger{params.StdOut}, nil
   }
   
   func (*Logger) Description() string {
       return "logger"
   }
   
   func (*Logger) Start() error {
       return nil
   }
   
   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))
       }
   }
   
   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, ", ")
   }
   
   func (*Logger) Stop() error {
       return nil
   }
   
3. Build and test

   xk6 build --with xk6-output-logger=.
   ./k6 run test.js --out logger --quiet --no-summary --iterations 2
   

Secret source extensions

Secret source extensions provide secrets to your k6 script at runtime from external sources like HashiCorp Vault or AWS Secrets Manager.

Subcommand extensions

Subcommand extensions add custom CLI commands under the k6 x namespace for setup, validation, and integration tools.

Best practices

Performance

Code in the default function executes many times. Ensure operations are performant and thread-safe.

Initialization

Do heavy initialization in the init context, not in the default function.

Custom metrics

Use Registry.NewMetric() to create custom metrics and emit them with metrics.PushIfNotDone().

Templates

Use the xk6-example or xk6-output-example templates.

Quick start with templates

The fastest way to get started is using GitHub templates:

1. Create a repository from grafana/xk6-example for JavaScript extensions
2. Or use grafana/xk6-output-example for output extensions
3. Open in GitHub Codespaces for instant development environment
4. Run xk6 run script.js to test immediately

Registry requirements

If you maintain a public xk6 repository and wish to have your extension listed in the registry, review the requirements in the k6 documentation.

Next steps

Bundle Extensions

Build custom k6 binaries with xk6

Explore Extensions

See what others have built

Community Forum

Ask questions and share your extensions

GitHub Template

Start with the official template