Using Extensions

How to build and use k6 with xk6 extensions

To use k6 extensions, you need to build a custom k6 binary that includes the extensions you want. This is done using xk6, the k6 extension builder.

Prerequisites

• Go 1.22 or later
• Git
• Basic command-line knowledge

You don’t need to write Go code to use extensions, only to build k6 with them included.

Installing xk6

Install xk6 using Go:

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

Verify installation:

xk6 version

Building k6 with Extensions

Build k6 with one or more extensions:

xk6 build --with github.com/grafana/xk6-redis@latest

This creates a k6 binary in the current directory with the Redis extension included.

Multiple Extensions

Include multiple extensions in a single build:

xk6 build \
  --with github.com/grafana/xk6-redis@latest \
  --with github.com/grafana/xk6-kafka@latest \
  --with github.com/grafana/xk6-sql@latest

You can specify any number of extensions in a single build command.

Specific Versions

Pin extensions to specific versions for reproducibility:

xk6 build --with github.com/grafana/xk6-redis@v0.2.0

Use Git references:

xk6 build --with github.com/user/xk6-custom@main
xk6 build --with github.com/user/xk6-custom@feature-branch
xk6 build --with github.com/user/xk6-custom@abc123

Local Development

Use local extension code during development:

xk6 build --with github.com/user/xk6-myext=/path/to/local/xk6-myext

This is useful when:

• Developing extensions
• Testing unreleased changes
• Making local modifications

Output Location

By default, xk6 creates the binary in the current directory. Specify a different location:

xk6 build --output /usr/local/bin/k6 --with github.com/grafana/xk6-redis@latest

You may need sudo to write to system directories like /usr/local/bin.

Using Extensions in Tests

Once you’ve built k6 with extensions, use them in your test scripts.

JavaScript Extensions

Import JavaScript extensions from the k6/x/ namespace:

import redis from 'k6/x/redis';
import sql from 'k6/x/sql';

export default function () {
  // Use extension functionality
  const client = redis.connect('localhost:6379');
  client.set('key', 'value');
}

The import name matches the extension’s registered name.

Output Extensions

Use output extensions with the --out flag:

./k6 run --out kafka=localhost:9092 script.js

Pass configuration:

./k6 run --out myoutput=config-value script.js

Or via script options:

export const options = {
  ext: {
    kafka: {
      brokers: ['localhost:9092'],
      topic: 'k6-metrics',
    },
  },
};

Subcommand Extensions

If an extension adds a subcommand, use it like any k6 command:

./k6 dashboard run script.js

Verifying Extensions

Check which extensions are included in your build:

./k6 version

Output shows k6 version and all compiled extensions:

k6 v0.50.0 (commit/abc123, go1.22.1, linux/amd64)
Extensions:
  github.com/grafana/xk6-redis v0.2.0
  github.com/grafana/xk6-kafka v0.7.0

If an extension doesn’t appear, it wasn’t properly included during the build.

Common Extension Use Cases

Testing Databases

xk6 build --with github.com/grafana/xk6-sql@latest

import sql from 'k6/x/sql';

const db = sql.open('postgres', 'connection-string');

export default function () {
  const results = db.query('SELECT * FROM users LIMIT 10');
  console.log(results);
}

Testing Message Queues

xk6 build --with github.com/mostafa/xk6-kafka@latest

import { Writer } from 'k6/x/kafka';

const writer = new Writer({
  brokers: ['localhost:9092'],
  topic: 'test-topic',
});

export default function () {
  writer.produce({
    messages: [{ value: 'test message' }],
  });
}

Browser Testing

xk6 build --with github.com/grafana/xk6-browser@latest

import { browser } from 'k6/x/browser';

export default async function () {
  const page = browser.newPage();
  await page.goto('https://example.com');
  await page.screenshot({ path: 'screenshot.png' });
  page.close();
}

Custom Outputs

xk6 build --with github.com/user/xk6-output-custom@latest

./k6 run --out custom=endpoint script.js

Environment-Specific Builds

Create different builds for different environments:

Development

xk6 build \
  --with github.com/grafana/xk6-dashboard@latest \
  --output k6-dev

Production

xk6 build \
  --with github.com/grafana/xk6-output-prometheus-remote@latest \
  --with github.com/grafana/xk6-kubernetes@latest \
  --output k6-prod

Automation

Build Script

Create a build script for consistent builds:

#!/bin/bash
# build-k6.sh

set -e

K6_VERSION="v0.50.0"
OUTPUT="./k6"

xk6 build "$K6_VERSION" \
  --output "$OUTPUT" \
  --with github.com/grafana/xk6-redis@latest \
  --with github.com/grafana/xk6-kafka@latest \
  --with github.com/grafana/xk6-sql@latest

echo "k6 built successfully: $OUTPUT"
./k6 version

Make it executable and run:

chmod +x build-k6.sh
./build-k6.sh

Docker

Create a Dockerfile with extensions:

FROM golang:1.22-alpine as builder

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

RUN xk6 build \
  --with github.com/grafana/xk6-redis@latest \
  --with github.com/grafana/xk6-kafka@latest \
  --output /k6

FROM alpine:latest
COPY --from=builder /k6 /usr/bin/k6

ENTRYPOINT ["k6"]

Build and use:

docker build -t k6-custom .
docker run -v $(pwd):/scripts k6-custom run /scripts/test.js

Using Docker ensures consistent builds across different environments and team members.

Troubleshooting

Build Failures

If the build fails:

1. Check Go version: Ensure Go 1.22+

   go version
   

2. Verify extension exists: Check the repository URL

   git ls-remote https://github.com/user/xk6-extension
   

3. Check version compatibility: Some extensions require specific k6 versions

4. Clear Go cache:

   go clean -modcache
   

Import Errors

If JavaScript imports fail:

1. Verify extension is included:

   ./k6 version
   

2. Check import path: Must use k6/x/ namespace

3. Rebuild: Ensure you’re using the custom binary

Extension Not Found

If an extension doesn’t appear:

1. Check registration: Extension must call ext.Register() in init()
2. Rebuild with verbose:
   xk6 build -v --with github.com/user/xk6-ext@latest
   
3. Check extension documentation: Some extensions have special requirements

Finding Extensions

Discover extensions:

• k6 Documentation: https://k6.io/docs/extensions/
• GitHub Topics: https://github.com/topics/xk6
• k6 Community: https://community.grafana.com/c/grafana-k6/
• Awesome k6: https://github.com/grafana/awesome-k6

Not all extensions are officially supported by Grafana. Community extensions may have varying quality and maintenance levels.

Best Practices

Next Steps

• Extensions Overview - Understand extension types
• Creating Extensions - Build your own
• Creating Custom Outputs - Specialized output guide