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
Building k6 with Extensions
Build k6 with one or more extensions:
xk6 build --with github.com/grafana/xk6-redis@latest
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:
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
- 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');
}
Output Extensions
Use output extensions with the --out flag:
./k6 run --out kafka=localhost:9092 script.js
./k6 run --out myoutput=config-value script.js
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:
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
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"]
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:
-
Check Go version: Ensure Go 1.22+
-
Verify extension exists: Check the repository URL
git ls-remote https://github.com/user/xk6-extension
-
Check version compatibility: Some extensions require specific k6 versions
-
Clear Go cache:
Import Errors
If JavaScript imports fail:
-
Verify extension is included:
-
Check import path: Must use
k6/x/ namespace
-
Rebuild: Ensure you’re using the custom binary
Extension Not Found
If an extension doesn’t appear:
- Check registration: Extension must call
ext.Register() in init()
- Rebuild with verbose:
xk6 build -v --with github.com/user/xk6-ext@latest
- Check extension documentation: Some extensions have special requirements
Finding Extensions
Discover extensions:
Not all extensions are officially supported by Grafana. Community extensions may have varying quality and maintenance levels.
Best Practices
Use specific versions in production for reproducibility:
Keep a record of which extensions and versions you’re using.
Verify all extensions work after building:
./k6 version
./k6 run test-extensions.js
Use scripts or CI/CD to ensure consistent builds.
Regularly check for extension updates and security fixes.
Next Steps