%% date:: [[2023-03-17]], [[2023-05-12]] %% # [[Extensions for k6 using xk6]] xk6 is a framework announced by [[k6 (Company)]] in December 2020 that makes it easier to use extensions for k6. It allows users to build a new binary of k6 that includes combinations of existing extensions. Not all pull requests to [[k6 (tool)|k6]] are approved, as the [[k6 (Company)|k6 team]] makes a conscious effort to streamline what goes into the tool itself, for performance reasons. However, users who want to customize k6 can develop and maintain extensions to k6 using a tool called xk6. xk6 is a binary that [can be downloaded here](https://github.com/k6io/xk6/releases) and can be used to create a custom k6 binary that includes selected extensions. ## Using existing extensions To use existing extensions for k6, follow the instructions below. More information can be found [in this blog post from k6](https://k6.io/blog/extending-k6-with-xk6/). ### Download xk6 Download the latest release of the [xk6 binary](https://github.com/k6io/xk6/releases) for your application. Alternatively, get it with Go: ```shell go install go.k6.io/xk6/cmd/[email protected] ``` ### Clone the xk6 extension Find a k6 extension and download it locally. The [Ecosystem page](https://k6.io/docs/ecosystem/) has a list of extensions, but you can also search for extensions in GitHub. By convention, extension repos start with `xk6-`, such as [xk6-chaos](https://github.com/k6io/xk6-chaos). ### Create a custom k6 binary Use the [Bundle Builder](https://k6.io/docs/ecosystem/bundle-builder/) to select the extensions you require and generate a command that will create a custom version of k6 with those extensions bundled in. The Bundle Builder automatically uses the latest published version of k6. ```bash xk6 build v0.33.0 --with github.com/simskij/xk6-chaos ``` If you'd prefer to use a local version of the extension, use: ```bash xk6 build v0.33.0 --with github.com/simskij/xk6-chaos="/absolute/path/to/xk6-redis" ``` ## Developing a k6 extension with xk6 k6 extensions are written in [[Go]]. It's a good idea to have a look at existing extensions to see how they were made before creating your own. Below are some things to consider ### Goja k6 is packaged with [[Goja]], which translates [[JavaScript]] to [[Go]] and vice versa. This translation engine adds some interesting considerations outside of the scope of either JavaScript or Go. For example, in Go, struct and property names conventionally begin with capital letters to allow them to be accessed externally. ```go type Podkillers struct { Ready bool } ``` However, in JavaScript, class names conventionally begin with a lowercase letter. To access the above Go struct in JavaScript (after it's been run through Goja), the class `podkillers` would have to be imported as below: ```js import { podkillers as Podkillers } from 'k6/x/chaos/experiments'; ``` ### Building custom k6 binary with local extension The Build Bundler linked above only works for published extensions. If you're developing your own extension or modifying one locally, you will need to build a custom binary of k6 using your _local_ extension rather than the published version. If you're creating a new extension, run this: `xk6 build v0.32.0 --with /Users/nic/git/xk6-myextension` If you're modifying a published extension: `xk6 build v0.32.0 --with github.com/simskij/xk6-chaos="/Users/nic/git/xk6-chaos"` ## Notable extensions for k6 - [[k6 browser]] - [[xk6-output-prometheus-remote]] - [[xk6-disruptor]] - [[xk6-kubernetes]]