{"id":14971874,"url":"https://github.com/grafana/xk6","last_synced_at":"2026-03-11T12:36:29.746Z","repository":{"id":40372269,"uuid":"305977666","full_name":"grafana/xk6","owner":"grafana","description":"Build k6 with extensions","archived":false,"fork":false,"pushed_at":"2025-05-15T17:35:08.000Z","size":22650,"stargazers_count":247,"open_issues_count":7,"forks_count":26,"subscribers_count":150,"default_branch":"master","last_synced_at":"2025-05-15T18:38:26.752Z","etag":null,"topics":["k6","xk6"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grafana.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-10-21T09:44:37.000Z","updated_at":"2025-05-14T07:27:52.000Z","dependencies_parsed_at":"2024-06-05T14:04:51.686Z","dependency_job_id":"a3cda2aa-cfe8-488c-9dd0-c697f108bdb7","html_url":"https://github.com/grafana/xk6","commit_stats":{"total_commits":126,"total_committers":23,"mean_commits":5.478260869565218,"dds":0.7222222222222222,"last_synced_commit":"3d1b684a454ef01d2cb919bb2a737c719d123bd5"},"previous_names":["k6io/xk6"],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fxk6","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fxk6/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fxk6/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fxk6/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grafana","download_url":"https://codeload.github.com/grafana/xk6/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254544146,"owners_count":22088807,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["k6","xk6"],"created_at":"2024-09-24T13:46:00.777Z","updated_at":"2026-03-11T12:36:29.737Z","avatar_url":"https://github.com/grafana.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- #region cli --\u003e\n# xk6\n\n**k6 extension development toolbox**\n\n\n\n### Main features\n\n- Create new extension skeleton (project scaffolding)\n- Build k6 with extensions\n- Run k6 with extensions\n- Run integration tests with extensions\n- Check the extension for compliance (lint)\n- Provide reusable GitHub workflows\n- Distribute xk6 as a Dev Container Feature\n\n### Use with Development Containers\n\nGet started developing k6 extensions quickly!\n\nxk6 is now a [Development containers] feature, meaning you can develop without installing any tooling or xk6.\n\nCheck out the [k6 extension development quickstart guide] and [k6 extension development tutorial] for details.\n\n[Development containers]: https://containers.dev/\n[k6 extension development quickstart guide]: https://github.com/grafana/xk6/wiki/k6-extension-development-quick-start-guide\n[k6 extension development tutorial]: https://github.com/grafana/xk6/wiki/k6-extension-development-tutorial\n\n### Use with Docker\n\nThe easiest way to use xk6 is via our [Docker image]. This avoids having to setup a local Go environment, and install xk6 manually.\n\n**Linux**\n\nFor example, to build a k6 v1.0.0 binary on Linux with the [xk6-faker] extension:\n\n    docker run --rm -it -u \"$(id -u):$(id -g)\" -v \"${PWD}:/xk6\" grafana/xk6 build v1.0.0 \\\n      --with github.com/grafana/xk6-faker\n\nThis would create a `k6` binary in the current working directory.\n\nNote the use of the `-u` (user) option to specify the user and group IDs of the account on the host machine. This is important for the `k6` file to have the same file permissions as the host user.\n\nThe `-v` (volume) option is also required to mount the current working directory inside the container, so that the `k6` binary can be written to it.\n\nNote that if you're using SELinux, you might need to add `:z` to the `--volume` option to avoid permission errors. E.g. `-v \"${PWD}:/xk6:z\"`.\n\n**macOS**\n\nOn macOS you will need to use `--os darwin` flag to build a macOS binary.\n\n    docker run --rm -it -u \"$(id -u):$(id -g)\" -v \"${PWD}:/xk6\" grafana/xk6 build --os darwin v1.0.0 \\\n      --with github.com/grafana/xk6-faker\n\n**Windows**\n\nOn Windows you can either build a native Windows binary, or, if you're using WSL2, a Linux binary you can use in WSL2.\n\nFor the native Windows binary if you're using PowerShell:\n\n    docker run --rm -it -u \"$(id -u):$(id -g)\" -v \"${PWD}:/xk6\" grafana/xk6 build --os windows v1.0.0 `\n      --with github.com/grafana/xk6-faker --output k6.exe \n\nFor the native Windows binary if you're using cmd.exe:\n\n    docker run --rm -it -v \"%cd%:/xk6\" grafana/xk6 build --os windows v1.0.0 ^\n      --with github.com/grafana/xk6-faker --output k6.exe\n\nFor the Linux binary on WSL2, you can use the same command as for Linux.\n\n**Tags**\n\nDocker images can be used with major version, minor version, and specific version tags.\n\nFor example, let's say `1.2.3` is the latest xk6 Docker image version.\n\n- the latest release of major version `1` is available using the `1` tag:\n\n      docker run --rm -it -u \"$(id -u):$(id -g)\" -v \"${PWD}:/xk6\" grafana/xk6:1\n\n- the latest release of minor version `1.2` is available using the `1.2` tag:\n\n      docker run --rm -it -u \"$(id -u):$(id -g)\" -v \"${PWD}:/xk6\" grafana/xk6:1.2\n\n- of course version `1.2.3` is still available using the `v1.2.3` tag:\n\n      docker run --rm -it -u \"$(id -u):$(id -g)\" -v \"${PWD}:/xk6\" grafana/xk6:1.2.3\n\n- the latest release is still available using the `latest` tag:\n\n      docker run --rm -it -u \"$(id -u):$(id -g)\" -v \"${PWD}:/xk6\" grafana/xk6:latest\n\n[Docker image]: https://hub.docker.com/r/grafana/xk6\n[xk6-faker]: https://github.com/grafana/xk6-faker\n\n### Local Installation\n\nPrecompiled binaries can be downloaded and installed from the [Releases] page.\n\n**Prerequisites**\n\nA [stable version] of the Go toolkit must be installed.\n\nThe xk6 tool can also be installed using the `go install` command.\n\n    go install go.k6.io/xk6@latest\n\nThis will install the `xk6` binary in `$GOPATH/bin` directory.\n\n[Releases]: https://github.com/grafana/xk6/releases\n[stable version]: https://go.dev/dl/\n\n### Building private extensions\n\nTo build an `xk6` extension from a private Git repository, you need to configure your environment to handle authentication.\n\n**Core Prerequisite**\n\nFirst, you must set the **`GOPRIVATE`** environment variable. This tells the Go compiler to bypass the standard Go proxy for your repository, allowing it to access the private module directly.\n\n    export GOPRIVATE=github.com/owner/repo\n\n**Method 1: Using SSH**\n\nTo handle authentication in non-interactive environments like CI/CD pipelines, configure Git to use the **SSH protocol** instead of HTTPS. This allows for authentication with an SSH key. This command globally configures Git to rewrite any `https://github.com/` URLs to `ssh://git@github.com/`.\n\n    git config --global url.ssh://git@github.com/.insteadOf https://github.com/\n\n**Method 2: Using GitHub CLI**\n\nAn alternative to using SSH is to leverage the **GitHub CLI** as a Git credential helper. In this case, Git will still access the repository over HTTPS, but it will use the GitHub CLI to handle the authentication process, eliminating the need to manually enter a password.\n\n    git config --global --add 'credential.https://github.com.helper' '!gh auth git-credential'\n\n## Commands\n\n* [xk6 version](#xk6-version)\t - Display version information\n* [xk6 new](#xk6-new)\t - Create a new k6 extension\n* [xk6 build](#xk6-build)\t - Build a custom k6 executable\n* [xk6 run](#xk6-run)\t - Execute the run command with the custom k6\n* [xk6 x](#xk6-x)\t - Execute a k6 subcommand provided by the current directory's extension\n* [xk6 lint](#xk6-lint)\t - Analyze k6 extension compliance\n* [xk6 test](#xk6-test)\t - Run integration tests with the custom k6\n* [xk6 sync](#xk6-sync)\t - Synchronize dependencies with k6\n\n---\n\n# xk6 version\n\nDisplay version information\n\n## Synopsis\n\nThe version is printed to standard output in the following format:\n\n    xk6 version XXX\n\nXXX is the semantic version of xk6, without the v prefix.\n\n## Usage\n\n```bash\nxk6 version [flags]\n```\n\n## Global Flags\n\n```\n  -h, --help      Help about any command \n  -q, --quiet     Suppress output\n  -v, --verbose   Verbose output\n```\n\n## SEE ALSO\n\n* [xk6](#xk6)\t - k6 extension development toolbox\n\n---\n\n# xk6 new\n\nCreate a new k6 extension\n\n## Synopsis\n\nCreate and initialize a new k6 extension using one of the predefined templates.\n\nThe go module path of the new extension must be passed as an argument.\n\nAn optional extension description can be specified as a flag.\nThe default description is generated from the go module path as follows:\n- remote git URL is generated from the go module path\n- the description is retrieved from the remote repository manager\n\nAn optional go package name can be specified as a flag.\nThe default go package name is generated from the go module path as follows:\n- the last element of the go module path is kept\n- the `xk6-output-` and `xk6-` prefixes are removed\n- the `-` characters are replaced with `_` characters\n\nA JavaScript type k6 extension will be generated by default.\nThe extension type can be optionally specified as a flag.\n\nThe `grafana/xk6-example` and `grafana/xk6-output-example` GitHub repositories are used as sources for generation. Certain files are automatically excluded from the template: `.git` directory, `CODEOWNERS`, and `renovate.json`. These files are specific to the template repository itself and not needed for new extensions.\n\n## Usage\n\n```bash\nxk6 new [flags] module\n```\n\n## Flags\n\n```\n  -t, --type string          The type of template to use (javascript or output)\n  -d, --description string   A short, on-sentence description of the extension\n  -p, --package string       The go package name for the extension\n  -C, --parent-dir string    The parent directory (default \".\")\n```\n\n## Global Flags\n\n```\n  -h, --help      Help about any command \n  -q, --quiet     Suppress output\n  -v, --verbose   Verbose output\n```\n\n## SEE ALSO\n\n* [xk6](#xk6)\t - k6 extension development toolbox\n\n---\n\n# xk6 build\n\nBuild a custom k6 executable\n\n## Synopsis\n\nThis command can be used to build custom k6 executables with or without extensions.\n\nThe target platform (operating system, architecture) can be specified with flags or environment variables.\n\nThe k6 version to be used and the k6 repository (for forks) can be specified with flags or environment variables.\n\n**Precedence**\n\nIf a setting can be specified with both a flag and an environment variable, the flag takes precedence.\n\n**Extensions**\n\nThe `--with` flag can be used to specify one or more extensions to be included. Extensions can be referenced with the go module path, optionally followed by a version specification. In the case of a fork, the path of the forked go module can be specified as replacement.\n\n**Fork**\n\nThe `--replace` flag can be used to specify a replacement for any go module. This allows forks to be used instead of extension dependencies.\n\nA k6 fork can be specified with the `--k6-repo` flag (or the `K6_REPO` environment variable).\n\n## Usage\n\n```bash\nxk6 build [flags] [k6-version]\n```\n\n## Flags\n\n```\n  -o, --output string                         Output filename (default \"./k6\")\n      --with module[@version][=replacement]   Add one or more k6 extensions with Go module path\n      --replace module=replacement            Replace one or more Go modules\n  -k, --k6-version string                     The k6 version to use for build (default \"latest\")\n      --k6-repo string                        The k6 repository to use for the build (default \"go.k6.io/k6\")\n      --os string                             The target operating system (default \"linux\")\n      --arch string                           The target architecture (default \"amd64\")\n      --arm string                            The target ARM version\n      --skip-cleanup int[=1]                  Keep the temporary build directory\n      --race-detector int[=1]                 Enable/disable race detector\n      --cgo int[=1]                           Enable/disable cgo\n      --build-flags stringArray               Specify Go build flags (default [-trimpath,-ldflags=-s -w])\n```\n\n## Global Flags\n\n```\n  -h, --help      Help about any command \n  -q, --quiet     Suppress output\n  -v, --verbose   Verbose output\n```\n\n## Environment\n\n```\n  K6_VERSION             The k6 version to use for build\n  XK6_K6_REPO            The k6 repository to use for the build\n  GOOS                   The target operating system\n  GOARCH                 The target architecture\n  GOARM                  The target ARM version\n  XK6_SKIP_CLEANUP       Keep the temporary build directory\n  XK6_RACE_DETECTOR      Enable/disable race detector\n  CGO_ENABLED            Enable/disable cgo\n  XK6_BUILD_FLAGS        Specify Go build flags\n```\n\n## SEE ALSO\n\n* [xk6](#xk6)\t - k6 extension development toolbox\n\n---\n\n# xk6 run\n\nExecute the run command with the custom k6\n\n## Synopsis\n\nThis is a useful command when developing the k6 extension. After modifying the source code of the extension, a k6 test script can simply be run without building the k6 executable.\n\nUnder the hood, the command builds a k6 executable into a temporary directory and runs it with the arguments. The usual flags for the build command can be used.\n\nTwo dashes are used to indicate that the following flags are no longer the flags of the `xk6 run` command but the flags of the `k6 run` command.\n\n## Usage\n\n```bash\nxk6 run [flags] [--] [k6-flags] script\n```\n\n## Flags\n\n```\n      --with module[@version][=replacement]   Add one or more k6 extensions with Go module path\n      --replace module=replacement            Replace one or more Go modules\n  -k, --k6-version string                     The k6 version to use for build (default \"latest\")\n      --k6-repo string                        The k6 repository to use for the build (default \"go.k6.io/k6\")\n      --os string                             The target operating system (default \"linux\")\n      --arch string                           The target architecture (default \"amd64\")\n      --arm string                            The target ARM version\n      --skip-cleanup int[=1]                  Keep the temporary build directory\n      --race-detector int[=1]                 Enable/disable race detector\n      --cgo int[=1]                           Enable/disable cgo\n      --build-flags stringArray               Specify Go build flags (default [-trimpath,-ldflags=-s -w])\n```\n\n## Global Flags\n\n```\n  -h, --help      Help about any command \n  -q, --quiet     Suppress output\n  -v, --verbose   Verbose output\n```\n\n## Environment\n\n```\n  K6_VERSION             The k6 version to use for build\n  XK6_K6_REPO            The k6 repository to use for the build\n  GOOS                   The target operating system\n  GOARCH                 The target architecture\n  GOARM                  The target ARM version\n  XK6_SKIP_CLEANUP       Keep the temporary build directory\n  XK6_RACE_DETECTOR      Enable/disable race detector\n  CGO_ENABLED            Enable/disable cgo\n  XK6_BUILD_FLAGS        Specify Go build flags\n```\n\n## SEE ALSO\n\n* [xk6](#xk6)\t - k6 extension development toolbox\n\n---\n\n# xk6 x\n\nExecute a k6 subcommand provided by the current directory's extension\n\n## Synopsis\n\nThis command is useful when developing k6 subcommand extensions. After modifying the extension source code in the current directory, you can execute the subcommand directly without manually building the k6 executable.\n\nUnder the hood, xk6 builds a temporary k6 executable with your extensions and runs it with the provided arguments. All standard build command flags are supported.\n\nUse two dashes (`--`) to separate xk6 flags from k6 subcommand flags.\n\n## Usage\n\n```bash\nxk6 x [flags] [--] [k6-flags] [subcommand] [subcommand-flags]\n```\n\n## Flags\n\n```\n      --with module[@version][=replacement]   Add one or more k6 extensions with Go module path\n      --replace module=replacement            Replace one or more Go modules\n  -k, --k6-version string                     The k6 version to use for build (default \"latest\")\n      --k6-repo string                        The k6 repository to use for the build (default \"go.k6.io/k6\")\n      --os string                             The target operating system (default \"linux\")\n      --arch string                           The target architecture (default \"amd64\")\n      --arm string                            The target ARM version\n      --skip-cleanup int[=1]                  Keep the temporary build directory\n      --race-detector int[=1]                 Enable/disable race detector\n      --cgo int[=1]                           Enable/disable cgo\n      --build-flags stringArray               Specify Go build flags (default [-trimpath,-ldflags=-s -w])\n```\n\n## Global Flags\n\n```\n  -h, --help      Help about any command \n  -q, --quiet     Suppress output\n  -v, --verbose   Verbose output\n```\n\n## Environment\n\n```\n  K6_VERSION             The k6 version to use for build\n  XK6_K6_REPO            The k6 repository to use for the build\n  GOOS                   The target operating system\n  GOARCH                 The target architecture\n  GOARM                  The target ARM version\n  XK6_SKIP_CLEANUP       Keep the temporary build directory\n  XK6_RACE_DETECTOR      Enable/disable race detector\n  CGO_ENABLED            Enable/disable cgo\n  XK6_BUILD_FLAGS        Specify Go build flags\n```\n\n## SEE ALSO\n\n* [xk6](#xk6)\t - k6 extension development toolbox\n\n---\n\n# xk6 lint\n\nAnalyze k6 extension compliance\n\n## Synopsis\n\nValidate k6 extension source code against quality, security, and compatibility standards.\nPerforms static analysis, builds the extension with k6, and checks compliance requirements.\n\nUse presets to run predefined sets of checks, or customize with individual checkers.\nThe analysis is performed locally using the source directory contents and Git metadata.\n\nExit Codes:\n  - `0`   All checks passed\n  - `1`   Unexpected execution error\n  - `2`   One or more checks failed\n\n## Usage\n\n```bash\nxk6 lint [flags] [directory]\n```\n\n## Examples\n\n```\n# Analyze current directory with default preset\nxk6 lint\n\n# Use strict preset for production validation\nxk6 lint --preset strict\n\n# Add smoke and examples checks to default preset\nxk6 lint --enable smoke,examples\n\n# Run only security checks\nxk6 lint --enable-only security,vulnerability  \n\n```\n\n### Available Checks\n\nThe following checks are available for use with the `xk6 lint` command.\n\n#### `security`\n\nPerforms static security analysis on Go source code using the `gosec` tool to identify potential security vulnerabilities, insecure coding patterns, and compliance violations.\n\n_Security vulnerabilities in extensions can compromise the entire k6 testing environment and potentially expose sensitive data or system resources. Early detection of security flaws through static analysis helps maintain the integrity of the k6 ecosystem and protects users from malicious or poorly secured extensions._\n\nResolution\n\nInstall `gosec` with `go install github.com/securecodewarrior/gosec/v2/cmd/gosec@latest`, then run `gosec ./...` to scan your codebase. Address all HIGH and MEDIUM severity findings by following secure coding practices, input validation, and proper error handling. Consider adding `// #gosec` comments only for verified false positives with clear justification.\n\n#### `vulnerability`\n\nScans for known security vulnerabilities in Go modules and their dependencies using the official `govulncheck` tool from the Go security team.\n\n_Third-party dependencies often contain discovered vulnerabilities that could be exploited in production environments. This check ensures that extensions don't introduce known security risks through outdated or vulnerable dependencies, maintaining the security posture of k6 installations._\n\nResolution\n\nInstall `govulncheck` with `go install golang.org/x/vuln/cmd/govulncheck@latest`, then run `govulncheck ./...` to scan for vulnerabilities. Update vulnerable dependencies to patched versions using `go get -u package@version`. If no patch is available, consider alternative packages or implement additional security measures.\n\n#### `module`\n\nValidates the presence and structure of a `go.mod` file, ensuring proper module declaration, Go version compatibility, and dependency specifications.\n\n_A properly configured `go.mod` file is fundamental for Go module system functionality, enabling reproducible builds, version management, and dependency resolution. Without it, the extension cannot be properly integrated into the k6 build process or distributed through Go's module system._\n\nResolution\n\nCreate a `go.mod` file in the extension root using `go mod init github.com/your-org/your-extension`, ensuring the Go version is specified as `go 1.23` (or appropriate minimum version). Run `go mod tidy` to populate dependencies and remove unused ones, then verify the module path matches your repository structure.\n\n#### `replace`\n\nDetects and flags any `replace` directives in the `go.mod` file that could cause dependency resolution issues or prevent proper extension distribution.\n\n_Replace directives create local overrides that only work in the development environment and break when the extension is built by xk6 or distributed to users. They can mask dependency conflicts, create irreproducible builds, and prevent proper version resolution in the broader Go ecosystem._\n\nResolution\n\nRemove all `replace` directives from `go.mod`. If you need to use a fork or modified dependency, publish it as a proper Go module with a different import path. For local development, consider using `go work` workspaces instead of replace directives, or contribute fixes upstream to the original repository.\n\n#### `readme`\n\nVerifies the existence of a README file in standard formats (Markdown, text, AsciiDoc, etc.) that provides essential information about the extension.\n\n_A comprehensive README serves as the primary documentation entry point, helping users understand the extension's purpose, installation process, usage examples, and contribution guidelines. It significantly impacts adoption rates and reduces support burden by providing self-service information for common questions._\n\nResolution\n\nCreate a `README.md` file in the extension root directory containing extension description and purpose, installation instructions via xk6, and usage examples with sample k6 scripts. Include API documentation or links to detailed docs, contributing guidelines and development setup, and license information and acknowledgments.\n\n#### `license`\n\nValidates that the extension includes a recognized open-source license file compatible with the k6 ecosystem and Go module distribution requirements.\n\n_A clear license is legally required for code distribution and defines usage rights for users, contributors, and organizations. Without proper licensing, extensions cannot be safely used in commercial environments or contributed to by the community. Accepted licenses ensure compatibility with k6's Apache 2.0 license._\n\nResolution\n\nAdd a `LICENSE` file to the repository root with one of the approved licenses: MIT (recommended for maximum compatibility), Apache-2.0 (best for corporate environments), BSD-2-Clause or BSD-3-Clause, or GPL-3.0, LGPL-3.0, or AGPL-3.0 (for copyleft requirements).\n\n#### `git`\n\nVerifies that the extension directory is a valid Git repository with proper version control initialization and configuration.\n\n_Git version control is essential for extension development, enabling change tracking, collaboration, release management, and integration with Go's module system which relies on Git tags for versioning. Extensions without Git cannot be properly distributed or versioned through standard Go tooling._\n\nResolution\n\nInitialize Git in the extension directory with `git init`, add a `.gitignore` file appropriate for the extension, then stage and commit all extension files using `git add . \u0026\u0026 git commit -m \"Initial commit\"`. Consider setting up a remote repository on GitHub, GitLab, or similar platform for collaboration and distribution.\n\n#### `versions`\n\nValidates the presence of proper semantic versioning Git tags following the vMAJOR.MINOR.PATCH format required by Go modules and xk6.\n\n_Semantic versioning tags are critical for Go module resolution, allowing users to specify version constraints and enabling automatic dependency management. Proper versioning communicates API compatibility, helps users understand upgrade risks, and enables tools like Dependabot to manage updates automatically._\n\nResolution\n\nCreate an initial release tag using `git tag v0.1.0 \u0026\u0026 git push origin v0.1.0`. For future releases, increment versions appropriately: PATCH (v1.0.1) for bug fixes with no API changes, MINOR (v1.1.0) for new features that are backward compatible, and MAJOR (v2.0.0) for breaking changes or API modifications. Always follow semantic versioning principles for predictable dependency management.\n\n#### `build`\n\nPerforms a complete build test of the extension using xk6 with the latest stable k6 version to verify compilation and linking compatibility.\n\n_Build compatibility is essential for user adoption and long-term maintainability. This check catches compilation errors, API compatibility issues, and dependency conflicts that would prevent users from successfully building custom k6 binaries with the extension, ensuring a smooth user experience._\n\nResolution\n\nTest the build locally using `xk6 build --with github.com/your-org/your-extension@latest`, then fix any compilation errors, missing imports, or API incompatibilities. Ensure your extension properly implements required k6 extension interfaces and update dependencies if needed using `go get -u \u0026\u0026 go mod tidy`.\n\n#### `smoke`\n\nLocates and executes a smoke test script to verify basic extension functionality works correctly in a real k6 runtime environment.\n\n_Smoke tests provide essential validation that the extension's core functionality operates as expected when loaded into k6. They catch runtime errors, API mismatches, and integration issues that static analysis cannot detect, serving as the minimum viable test to ensure the extension actually works for end users._\n\nResolution\n\nCreate a smoke test file as `smoke.js` or `smoke.ts` in root, `test/`, `tests/`, or `examples/` directory, including basic functionality tests that import the extension and call main functions. Ensure the test runs without errors when executed with your custom k6 build.\n\n#### `examples`\n\nEnsures the presence of an `examples/` directory containing practical k6 scripts that demonstrate the extension's functionality and usage patterns.\n\n_Example scripts are crucial for user onboarding and adoption, providing immediate practical value and reducing the learning curve. They serve as living documentation, showing real-world usage patterns and helping users quickly understand how to integrate the extension into their testing workflows._\n\nResolution\n\nCreate an `examples/` directory with multiple k6 JavaScript/TypeScript files including a basic usage example showing core functionality, advanced example demonstrating complex features, and integration examples with other k6 features. Include comments explaining key concepts and parameters. Add a README.md in examples/ explaining how to run each script.\n\n#### `types`\n\nValidates the presence of TypeScript declaration files (`index.d.ts`) that define the extension's API surface and enable type-safe usage in TypeScript k6 scripts.\n\n_TypeScript declarations significantly improve developer experience by providing IDE autocompletion, type checking, and inline documentation. As k6 increasingly supports TypeScript, providing accurate type definitions becomes essential for extension adoption and proper integration with modern development workflows._\n\nResolution\n\nCreate an `index.d.ts` file in the root, `docs/`, or `api-docs/` directory defining all exported functions, classes, and interfaces with parameter types and return types. Include JSDoc comments for function documentation and proper module declarations matching your extension's import path.\n\n#### `codeowners`\n\nValidates the existence of a `CODEOWNERS` file that defines maintainership responsibilities and automated review assignments for different parts of the codebase.\n\n_Code ownership is critical for maintaining extension quality and ensuring timely responses to issues and pull requests. CODEOWNERS enables automatic reviewer assignment, helps contributors identify the right people for questions, and establishes clear accountability for different components of the extension._\n\nResolution\n\nCreate a `CODEOWNERS` file in `.github/`, `docs/`, or the repository root defining global owners (`* @username @team`) and specifying path-based ownership (`docs/ @doc-team`). Include email contacts for critical components and use GitHub teams when possible for better maintainability. Ensure all specified owners have appropriate repository permissions.\n\n### Available Presets\n\nThe following presets are available for use with the `xk6 lint` command.\n\n#### `all`\n\nComprehensive preset that includes every available check in the xk6 linting system. Serves as a complete reference for all possible compliance checks and provides maximum validation coverage for development and testing purposes.\n\nIncluded Checks:\n  - `security`\n  - `vulnerability`\n  - `module`\n  - `replace`\n  - `readme`\n  - `license`\n  - `git`\n  - `versions`\n  - `build`\n  - `smoke`\n  - `examples`\n  - `types`\n  - `codeowners`\n\n#### `loose`\n\nMinimal preset focusing on essential quality and security compliance checks. Designed for development environments and initial extension development phases. Provides basic compliance requirements without restrictive validation that slows development cycles. This is the default preset.\n\nIncluded Checks:\n  - `security`\n  - `vulnerability`\n  - `module`\n  - `readme`\n  - `license`\n  - `git`\n  - `versions`\n  - `build`\n\n#### `strict`\n\nComprehensive preset for production-ready extensions, including all compliance checks except those reserved for official Grafana extensions (such as codeowners validation). Designed for third-party extensions that require high quality standards before release.\n\nIncluded Checks:\n  - `security`\n  - `vulnerability`\n  - `module`\n  - `replace`\n  - `readme`\n  - `license`\n  - `git`\n  - `versions`\n  - `build`\n  - `smoke`\n  - `examples`\n  - `types`\n\n#### `private`\n\nLightweight preset designed for private or internal extension development. Focuses on core security and functionality compliance while omitting documentation and public-facing requirements such as README formatting and licensing compliance.\n\nIncluded Checks:\n  - `security`\n  - `vulnerability`\n  - `module`\n  - `git`\n\n#### `community`\n\nBalanced preset tailored for community-contributed extension development. Includes essential quality, security, and documentation compliance to ensure extensions meet community standards while remaining accessible to contributors.\n\nIncluded Checks:\n  - `security`\n  - `vulnerability`\n  - `module`\n  - `readme`\n  - `license`\n  - `git`\n  - `versions`\n  - `build`\n\n#### `official`\n\nMost stringent preset for official Grafana-maintained extension development. Enforces the highest quality standards including code ownership compliance, comprehensive testing requirements, and complete documentation compliance.\n\nIncluded Checks:\n  - `security`\n  - `vulnerability`\n  - `module`\n  - `replace`\n  - `readme`\n  - `license`\n  - `git`\n  - `versions`\n  - `build`\n  - `smoke`\n  - `examples`\n  - `types`\n  - `codeowners`\n\n## Flags\n\n```\n  -o, --out string             Write output to file instead of stdout\n      --json                   Generate JSON output\n  -c, --compact                Compact instead of pretty-printed JSON output\n  -p, --preset preset          Check preset to use (default: loose) (default loose)\n      --enable checkers        Enable additional checks (comma-separated list)\n      --disable checkers       Disable specific checks (comma-separated list)\n      --enable-only checkers   Enable only specified checks, ignoring preset (comma-separated list)\n  -k, --k6-version string      The k6 version to use for build (default \"latest\")\n      --k6-repo string         The k6 repository to use for the build (default \"go.k6.io/k6\")\n```\n\n## Global Flags\n\n```\n  -h, --help      Help about any command \n  -q, --quiet     Suppress output\n  -v, --verbose   Verbose output\n```\n\n## Environment\n\n```\n  XK6_LINT_PRESET           Check preset to use (default: loose)\n  XK6_LINT_ENABLE           Enable additional checks (comma-separated list)\n  XK6_LINT_DISABLE          Disable specific checks (comma-separated list)\n  XK6_LINT_ENABLE_ONLY      Enable only specified checks, ignoring preset (comma-separated list)\n```\n\n## SEE ALSO\n\n* [xk6](#xk6)\t - k6 extension development toolbox\n\n---\n\n# xk6 test\n\nRun integration tests with the custom k6\n\n## Synopsis\n\nThis command is useful for testing k6 extensions during development. It builds k6 with the extension once and runs multiple test scripts, reporting test results based on exit codes.\n\nUnder the hood, the command builds a k6 executable into a temporary directory and executes each test script with it. The usual flags for the build command can be used.\n\n**Output Format**\n\nBy default, test results are reported in TAP (Test Anything Protocol) format for easy parsing and integration with CI systems. Use the `--json` flag to generate a CTRF (Common Test Report Format) JSON file for structured test reporting.\n\n**Exit Codes**\n\nThe command exits with:\n- `0` if all tests pass\n- `1` if a command error occurs (invalid arguments, build failure, etc.)\n- `2` if one or more tests fail\n\n**Test Scripts**\n\nOne or more test file patterns must be specified as arguments. \n\nA test passes if the k6 script exits with code 0, and fails otherwise. Tests can fail through:\n- Failed checks with threshold configurations\n- Calling the `test.fail()` API\n- Using k6 jslib testing/assertion frameworks\n- Any uncaught exception or k6-specific exit code (97-110)\n\n**Glob Patterns**\n\nGlob patterns are supported in filenames:\n- Asterisk wildcards (`*`)\n- Super-asterisk wildcards (`**`) for recursive directory matching\n- Single symbol wildcards (`?`)\n- Character list matchers with negation and ranges (`[abc]`, `[!abc]`, `[a-c]`)\n- Alternative matchers (`{a,b}`)\n- Nested globbing (`{a,[bc]}`)\n\n**Examples**\n\n    # Run a single test\n    xk6 test tests/integration.js\n\n    # Run multiple test files\n    xk6 test tests/test1.js tests/test2.js\n\n    # Use glob patterns (recursive)\n    xk6 test \"tests/**/*.test.js\"\n\n    # Multiple patterns\n    xk6 test \"tests/**/*.test.js\" \"integration/**/*.spec.js\"\n\n    # Generate CTRF JSON report\n    xk6 test --json --output report.json \"tests/**/*.js\"\n\n    # Verbose output for debugging\n    xk6 test --verbose tests/integration.js\n\n**Using Pre-built k6**\n\nThe `--k6` flag allows testing with a pre-built k6 binary instead of building from source. This is useful when the Go toolchain is not available or when k6 doesn't need to be rebuilt.\n\n    # Use pre-built k6 binary\n    xk6 test --k6 /path/to/k6 tests/integration.js\n\n## Usage\n\n```bash\nxk6 test [flags] pattern\n```\n\n## Flags\n\n```\n      --with module[@version][=replacement]   Add one or more k6 extensions with Go module path\n      --replace module=replacement            Replace one or more Go modules\n  -k, --k6-version string                     The k6 version to use for build (default \"latest\")\n      --k6-repo string                        The k6 repository to use for the build (default \"go.k6.io/k6\")\n      --os string                             The target operating system (default \"linux\")\n      --arch string                           The target architecture (default \"amd64\")\n      --arm string                            The target ARM version\n      --skip-cleanup int[=1]                  Keep the temporary build directory\n      --race-detector int[=1]                 Enable/disable race detector\n      --cgo int[=1]                           Enable/disable cgo\n      --build-flags stringArray               Specify Go build flags (default [-trimpath,-ldflags=-s -w])\n      --k6 string                             Specify the k6 binary to use instead of building one\n  -o, --out string                            Write output to file instead of stdout\n      --json                                  Generate JSON output\n  -c, --compact                               Compact instead of pretty-printed JSON output\n```\n\n## Global Flags\n\n```\n  -h, --help      Help about any command \n  -q, --quiet     Suppress output\n  -v, --verbose   Verbose output\n```\n\n## Environment\n\n```\n  K6_VERSION             The k6 version to use for build\n  XK6_K6_REPO            The k6 repository to use for the build\n  GOOS                   The target operating system\n  GOARCH                 The target architecture\n  GOARM                  The target ARM version\n  XK6_SKIP_CLEANUP       Keep the temporary build directory\n  XK6_RACE_DETECTOR      Enable/disable race detector\n  CGO_ENABLED            Enable/disable cgo\n  XK6_BUILD_FLAGS        Specify Go build flags\n  K6                     Specify the k6 binary to use instead of building one\n```\n\n## SEE ALSO\n\n* [xk6](#xk6)\t - k6 extension development toolbox\n\n---\n\n# xk6 sync\n\nSynchronize dependencies with k6\n\n## Synopsis\n\nSynchronizes the versions of dependencies in `go.mod` with those used in the k6 project. Dependencies not found in k6's `go.mod` remain unchanged. Future updates may include synchronization of other files.\n\nThe purpose of this subcommand is to avoid dependency conflicts when building the extension with k6 (and other extensions).\n\nIt is recommended to keep dependencies in common with k6 core in the same version k6 core uses. This guarantees binary compatibility of the JS runtime, and ensures uses will not have to face unforeseen build-time errors when compiling several extensions together with xk6.\n\nBy default, `xk6 sync` uses the k6 version specified in `go.mod`. This allows using any version supported by the `go get` command, including branch names like `master`. The `-k` or `--k6-version` flag can override this to sync with a specific k6 version. In this case only immutable versions can be used and `latest` which refers to latest immutable version.\n\n## Usage\n\n```bash\nxk6 sync [flags]\n```\n\n## Flags\n\n```\n  -k, --k6-version string   The k6 version to use. If not specified, uses the version from go.mod\n  -n, --dry-run             Do not make any changes, only log them\n  -o, --out string          Write output to file instead of stdout\n      --json                Generate JSON output\n  -c, --compact             Compact instead of pretty-printed JSON output\n  -m, --markdown            Generate Markdown output\n```\n\n## Global Flags\n\n```\n  -h, --help      Help about any command \n  -q, --quiet     Suppress output\n  -v, --verbose   Verbose output\n```\n\n## SEE ALSO\n\n* [xk6](#xk6)\t - k6 extension development toolbox\n\n\u003c!-- #endregion cli --\u003e\n\n---\n\n\u003e This project originally forked from the [xcaddy](https://github.com/caddyserver/xcaddy) project. **Thank you!**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrafana%2Fxk6","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrafana%2Fxk6","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrafana%2Fxk6/lists"}