Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/grafana/k6/llms.txt

Use this file to discover all available pages before exploring further.

k6 extensions allow you to enhance k6’s functionality by adding custom JavaScript modules, output formats, secret sources, and subcommands. Extensions are built in Go and loaded into k6 using xk6.

​
What Are Extensions?

Extensions are Go packages that integrate with k6 to provide additional capabilities beyond the core functionality. They enable you to:
  • Add custom JavaScript APIs
  • Integrate with proprietary systems
  • Create specialized output formats
  • Implement custom authentication sources
  • Add new CLI subcommands
Extensions are compiled into k6 at build time, creating a custom k6 binary with your additional functionality.

​
Extension Types

k6 supports four types of extensions (ext/ext.go:26):

​
JavaScript Extensions

Add custom JavaScript modules that can be imported in your test scripts. 
import custom from 'k6/x/custom';

export default function () {
  custom.doSomething();
}
Use cases:
  • Protocol implementations (MQTT, Kafka, gRPC)
  • Custom encodings or cryptography
  • Proprietary API clients
  • Specialized data generation

​
Output Extensions

Create custom outputs to send test results to any backend or format. 
k6 run --out myoutput=config script.js
Use cases:
  • Proprietary monitoring systems
  • Custom database storage
  • Specialized file formats
  • Real-time streaming platforms
See Creating Custom Outputs for details.

​
Secret Source Extensions

Implement custom secret sources for retrieving sensitive configuration values. Use cases:
  • Corporate secret management systems
  • Hardware security modules (HSM)
  • Cloud provider secret managers
  • Custom encryption schemes

​
Subcommand Extensions

Add new CLI subcommands to k6. 
k6 mycommand [args]
Use cases:
  • Custom test orchestration
  • Specialized reporting tools
  • Configuration generators
  • Integration utilities

​
Extension Registry

Extensions are registered globally using the extension registry (ext/ext.go:18). The registry:
  • Maintains a map of extensions by type
  • Prevents duplicate registrations
  • Tracks module path and version information
  • Provides lookup by extension type

​
Registration

Extensions self-register using the Register() function: 
import "go.k6.io/k6/ext"

func init() {
    ext.Register("myextension", ext.JSExtension, &MyExtension{})
}
Attempting to register an extension with a duplicate name will cause a panic. Ensure your extension names are unique.

​
Extension Metadata

Each extension contains metadata (ext/ext.go:49): 
type Extension struct {
    Name    string        // Extension name
    Path    string        // Go module path
    Version string        // Module version
    Type    ExtensionType // Extension type
    Module  any           // Extension implementation
}
This metadata is used for:
  • Version tracking and compatibility
  • Debugging and diagnostics
  • Extension discovery
  • Conflict detection

​
Viewing Extensions

List all loaded extensions: 
k6 version
The output shows k6 version and all compiled-in extensions with their versions.

​
How Extensions Work

1
Build Time
2
Extensions are compiled into k6 using xk6:
3
xk6 build --with github.com/user/xk6-extension@latest
4
Initialization
5
When k6 starts, extension init() functions run and register extensions.
6
Runtime
7
k6 looks up registered extensions when:
8
  • Importing JavaScript modules
  • Processing --out flags
  • Loading secret sources
  • Executing CLI commands
    • 9
    Execution
    10
    Extensions integrate with k6’s core systems:
    11
  • JS extensions expose APIs to test scripts
  • Output extensions receive metric samples
  • Secret sources are queried for values
  • Subcommands execute custom logic

    • ​
    Extension Naming

    Follow these conventions:

    ​
    Repository Names

    Prefix with xk6- for discoverability:
    • xk6-output-kafka
    • xk6-redis
    • xk6-crypto

    ​
    Extension Names

    Use lowercase, descriptive names: 
    ext.Register("redis", ext.JSExtension, module)

    ​
    JavaScript Import Paths

    JS extensions use the k6/x/ namespace: 
    import redis from 'k6/x/redis';
    Consistent naming helps users discover and use your extensions easily.

    ​
    Official Extensions

    • xk6-browser: Browser automation and testing
    • xk6-dashboard: Web-based results dashboard
    • xk6-kubernetes: Kubernetes testing utilities
    • xk6-sql: SQL database testing

    ​
    Community Extensions

    • xk6-kafka: Apache Kafka protocol support
    • xk6-redis: Redis client functionality
    • xk6-mqtt: MQTT protocol implementation
    • xk6-output-influxdb: InfluxDB v2 output
    • xk6-prometheus-remote: Prometheus remote write
    Explore more at k6 Extension Registry.

    ​
    Building Blocks

    Extensions leverage k6’s internal packages:

    ​
    For JavaScript Extensions

    • js/modules: Module registration and lifecycle
    • metrics: Creating and emitting custom metrics

    ​
    For Output Extensions

    • output: Output interface and utilities
    • metrics: Receiving and processing samples

    ​
    Common Packages

    • lib: Core k6 types and utilities
    • stats: Statistical calculations
    • lib/types: Common type definitions

    ​
    Version Compatibility

    Extensions should specify compatible k6 versions: 
    // go.mod
module github.com/user/xk6-myext

go 1.22

require go.k6.io/k6 v0.50.0
    k6’s internal APIs may change between versions. Pin your extension to compatible k6 versions and test thoroughly when upgrading.

    ​
    Performance Considerations

    • JavaScript extensions: Minimize CGO calls and data conversions
    • Output extensions: Use buffering and async processing
    • All extensions: Avoid blocking operations in hot paths
    Badly performing extensions can significantly impact test accuracy by consuming VU execution time.

    ​
    Security Considerations

    • Validate all inputs from JavaScript
    • Sanitize data sent to external systems
    • Handle secrets securely
    • Avoid logging sensitive information
    • Review dependencies for vulnerabilities

    ​
    Extension Development

    Ready to build your own extension?

    ​
    Community Resources

    Build docs developers (and LLMs) love

    Get started for freeTalk to us