README
¶
k6registry
k6 Extension Registry Generator
k6registry is a CLI tool and a GitHub Action that enables the generation of the k6 extension registry. The generation source is a YAML (or JSON) file that contains the most important properties of extensions. The generator generates the missing properties from the repository metadata. Repository metadata is collected using the repository manager APIs. GitHub and GitLab APIs are currently supported.
The generator also performs static analysis of extensions using xk6 lint command. The result of the analysis is a list of issues detected.
Check k6 Extension Registry Concept for information on design considerations.
Example registry source
- module: github.com/grafana/xk6-dashboard
description: Web-based metrics dashboard for k6
outputs:
- dashboard
tier: official
- module: github.com/grafana/xk6-sql
description: Load test SQL Servers
imports:
- k6/x/sql
tier: official
- module: github.com/grafana/xk6-disruptor
description: Inject faults to test
imports:
- k6/x/disruptor
tier: official
- module: github.com/grafana/xk6-faker
description: Generate random fake data
imports:
- k6/x/faker
tier: official
- module: gitlab.com/szkiba/xk6-banner
description: Print ASCII art banner from k6 test
imports:
- k6/x/banner
Example registry
Registry generated from the source above.
[
{
"compliance": {},
"description": "Web-based metrics dashboard for k6",
"module": "github.com/grafana/xk6-dashboard",
"outputs": [
"dashboard"
],
"repo": {
"clone_url": "https://github.com/grafana/xk6-dashboard.git",
"description": "A k6 extension that makes k6 metrics available on a web-based dashboard.",
"homepage": "https://github.com/grafana/xk6-dashboard",
"license": "AGPL-3.0",
"name": "xk6-dashboard",
"owner": "grafana",
"public": true,
"stars": 367,
"timestamp": 1731922735,
"topics": [
"xk6",
"xk6-official",
"xk6-output-dashboard"
],
"url": "https://github.com/grafana/xk6-dashboard"
},
"tier": "official",
"versions": [
"v0.7.5",
"v0.7.4",
"v0.7.3",
"v0.7.3-alpha.1",
"v0.7.2",
"v0.7.1",
"v0.7.0",
"v0.7.0-apha.3",
"v0.7.0-alpha.5",
"v0.7.0-alpha.4",
"v0.7.0-alpha.3",
"v0.7.0-alpha.2",
"v0.7.0-alpha.1",
"v0.6.1",
"v0.6.0",
"v0.5.5",
"v0.5.4",
"v0.5.3",
"v0.5.2",
"v0.5.1",
"v0.5.0",
"v0.4.4",
"v0.4.3",
"v0.4.2",
"v0.4.1",
"v0.4.0",
"v0.3.2",
"v0.3.1",
"v0.3.0",
"v0.2.0",
"v0.1.3",
"v0.1.2",
"v0.1.1",
"v0.1.0"
]
},
{
"compliance": {
"issues": [
"smoke"
],
},
"description": "Load test SQL Servers",
"imports": [
"k6/x/sql"
],
"module": "github.com/grafana/xk6-sql",
"repo": {
"clone_url": "https://github.com/grafana/xk6-sql.git",
"description": "Use SQL databases from k6 tests.",
"homepage": "http://sql.x.k6.io",
"license": "Apache-2.0",
"name": "xk6-sql",
"owner": "grafana",
"public": true,
"stars": 120,
"timestamp": 1733736611,
"topics": [
"k6",
"sql",
"xk6"
],
"url": "https://github.com/grafana/xk6-sql"
},
"tier": "official",
"versions": [
"v1.0.0",
"v0.4.1",
"v0.4.0",
"v0.3.0",
"v0.2.1",
"v0.2.0",
"v0.1.1",
"v0.1.0",
"v0.0.1"
]
},
{
"compliance": {
"issues": [
"smoke",
"examples",
"types"
],
},
"description": "Inject faults to test",
"imports": [
"k6/x/disruptor"
],
"module": "github.com/grafana/xk6-disruptor",
"repo": {
"clone_url": "https://github.com/grafana/xk6-disruptor.git",
"description": "Extension for injecting faults into k6 tests",
"homepage": "https://k6.io/docs/javascript-api/xk6-disruptor/",
"license": "AGPL-3.0",
"name": "xk6-disruptor",
"owner": "grafana",
"public": true,
"stars": 97,
"timestamp": 1733824028,
"topics": [
"chaos-engineering",
"fault-injection",
"k6",
"testing",
"xk6"
],
"url": "https://github.com/grafana/xk6-disruptor"
},
"tier": "official",
"versions": [
"v0.3.13",
"v0.3.12",
"v0.3.11",
"v0.3.10",
"v0.3.9",
"v0.3.8",
"v0.3.7",
"v0.3.6",
"v0.3.5",
"v0.3.5-rc2",
"v0.3.5-rc1",
"v0.3.4",
"v0.3.3",
"v0.3.2",
"v0.3.1",
"v0.3.0",
"v0.2.1",
"v0.2.0",
"v0.1.3",
"v0.1.2",
"v0.1.1",
"v0.1.0"
]
},
{
"compliance": {
"issues": [
"smoke"
],
},
"description": "Generate random fake data",
"imports": [
"k6/x/faker"
],
"module": "github.com/grafana/xk6-faker",
"repo": {
"clone_url": "https://github.com/grafana/xk6-faker.git",
"description": "Random fake data generator for k6.",
"homepage": "https://faker.x.k6.io",
"license": "AGPL-3.0",
"name": "xk6-faker",
"owner": "grafana",
"public": true,
"stars": 63,
"timestamp": 1733979175,
"topics": [
"xk6"
],
"url": "https://github.com/grafana/xk6-faker"
},
"tier": "official",
"versions": [
"v0.4.0",
"v0.3.1",
"v0.3.0",
"v0.3.0-alpha.1",
"v0.2.2",
"v0.2.1",
"v0.2.0",
"v0.1.0"
]
},
{
"compliance": {
"issues": [
"smoke",
"types"
],
},
"description": "Print ASCII art banner from k6 test",
"imports": [
"k6/x/banner"
],
"module": "gitlab.com/szkiba/xk6-banner",
"repo": {
"clone_url": "https://gitlab.com/szkiba/xk6-banner.git",
"description": "Print ASCII art banner from k6 test.",
"homepage": "https://gitlab.com/szkiba/xk6-banner",
"license": "MIT",
"name": "xk6-banner",
"owner": "szkiba",
"public": true,
"timestamp": 1725896396,
"topics": [
"xk6"
],
"url": "https://gitlab.com/szkiba/xk6-banner"
},
"tier": "community",
"versions": [
"v0.1.0"
]
},
{
"description": "A modern load testing tool, using Go and JavaScript",
"imports": [
"k6"
],
"module": "go.k6.io/k6",
"repo": {
"description": "A modern load testing tool, using Go and JavaScript - https://k6.io",
"homepage": "https://github.com/grafana/k6",
"license": "AGPL-3.0",
"name": "k6",
"owner": "grafana",
"public": true,
"topics": [
"es6",
"go",
"golang",
"hacktoberfest",
"javascript",
"load-generator",
"load-testing",
"performance"
],
"url": "https://github.com/grafana/k6"
},
"tier": "official",
"versions": [
"v0.55.0",
"v0.54.0",
"v0.53.0",
"v0.52.0",
"v0.51.0",
"v0.50.0",
"v0.49.0",
"v0.48.0",
"v0.47.0",
"v0.46.0",
"v0.45.1",
"v0.45.0",
"v0.44.1",
"v0.44.0",
"v0.43.1",
"v0.43.0",
"v0.42.0",
"v0.41.0",
"v0.40.0",
"v0.39.0",
"v0.38.3",
"v0.38.2",
"v0.38.1",
"v0.38.0",
"v0.37.0",
"v0.36.0",
"v0.35.0",
"v0.34.1",
"v0.34.0",
"v0.33.0",
"v0.32.0",
"v0.31.1",
"v0.31.0",
"v0.30.0",
"v0.29.0",
"v0.28.0",
"v0.27.1",
"v0.27.0",
"v0.26.2",
"v0.26.1",
"v0.26.0",
"v0.25.1",
"v0.25.0",
"v0.24.0",
"v0.23.1",
"v0.23.0",
"v0.22.1",
"v0.22.0",
"v0.21.1",
"v0.21.0",
"v0.20.0",
"v0.19.0",
"v0.18.2",
"v0.18.1",
"v0.18.0",
"v0.17.2",
"v0.17.1",
"v0.17.0",
"v0.16.0",
"v0.15.0",
"v0.14.0",
"v0.13.0",
"v0.12.2",
"v0.12.1",
"v0.11.0",
"v0.10.0",
"v0.9.3",
"v0.9.2",
"v0.9.1",
"v0.9.0",
"v0.8.5",
"v0.8.4",
"v0.8.3",
"v0.8.2",
"v0.8.1",
"v0.8.0",
"v0.7.0",
"v0.6.0",
"v0.5.2",
"v0.5.1",
"v0.5.0",
"v0.4.5",
"v0.4.4",
"v0.4.3",
"v0.4.2",
"v0.4.1",
"v0.4.0",
"v0.3.0",
"v0.2.1",
"v0.2.0",
"v0.0.2",
"v0.0.1"
]
}
]
Install
Precompiled binaries can be downloaded and installed from the Releases page.
If you have a go development environment, the installation can also be done with the following command:
go install github.com/grafana/k6registry/cmd/k6registry@latest
GitHub Workflows
When used in GitHub Workflows, the change can be indicated by comparing the output to a reference output. The reference output URL can be passed in the --ref flag. The changed output variable will be true or false depending on whether the output has changed or not compared to the reference output.
Outputs
| name | description |
|---|---|
| changed | true if the output has changed compared to ref, otherwise false |
CLI
k6registry
k6 Extension Registry/Catalog Generator
Synopsis
Generate k6 extension registry from source.
The generation source is a YAML (or JSON) file that contains the most important properties of extensions. The generator generates the missing properties from the repository metadata. Repository metadata is collected using the repository manager APIs. GitHub and GitLab APIs are currently supported.
The generator also performs static analysis of extensions using xk6 lint command.
The source is read from file specified as command line argument. If it is missing, the source is read from the standard input.
The output of the generation will be written to the standard output by default. The output can be saved to a file using the -o/--out flag.
k6registry [flags] [source-file]
Flags
-o, --out string write output to file instead of stdout
--origin string external registry URL for default values
-q, --quiet no output, only validation
--loose skip JSON schema validation
--lint enable built-in linter
--ignore-lint-errors don't fail on lint errors
--lint-checks strings lint checks to apply. Check xk6 documentation for available options.
-c, --compact compact instead of pretty-printed output
-v, --verbose verbose logging
-V, --version print version
-h, --help help for k6registry
Commands
- k6registry schema - Output the JSON schema to stdout
k6registry schema
Output the JSON schema to stdout
Synopsis
Output the JSON schema for the k6 extension registry to stdout
k6registry schema [flags]
Flags
-h, --help help for schema
SEE ALSO
- k6registry - k6 Extension Registry/Catalog Generator
Contribure
If you want to contribute, start by reading CONTRIBUTING.md.
Documentation
¶
Overview ¶
Package k6registry contains the data model of the k6 extensions registry.
Index ¶
Constants ¶
This section is empty.
Variables ¶
View Source
var Schema []byte
Schema contains JSON schema for Grafana k6 Extension Registry JSON.
View Source
var ( // Tiers contains possible values for Tier. Tiers = []Tier{TierOfficial, TierCommunity} )
Functions ¶
This section is empty.
Types ¶
type Compliance ¶ added in v0.1.14
type Compliance struct {
// A list of compliance check IDs that failed.
//
// The `issues“ property is primarily used for debugging. It contains the
// (implementation-dependent) identifiers of those compliance checks that failed.
//
Issues []string `json:"issues,omitempty" yaml:"issues,omitempty" mapstructure:"issues,omitempty"`
}
The result of the extension's k6 compliance checks.
type Extension ¶
type Extension struct {
// Flag indicating the need for cgo.
//
// The `cgo` property value `true` indicates that cgo must be enabled to build the
// extension.
//
Cgo bool `json:"cgo,omitempty" yaml:"cgo,omitempty" mapstructure:"cgo,omitempty"`
// The result of the extension's k6 compliance checks.
//
Compliance ExtensionCompliance `json:"compliance,omitempty" yaml:"compliance,omitempty" mapstructure:"compliance,omitempty"`
// Version constraints.
//
// Version constraints are primarily used to filter automatically detected
// versions.
// It can also be used to filter the versions property imported from the origin
// registry.
//
Constraints string `json:"constraints,omitempty" yaml:"constraints,omitempty" mapstructure:"constraints,omitempty"`
// Brief description of the extension.
//
Description string `json:"description,omitempty" yaml:"description,omitempty" mapstructure:"description,omitempty"`
// List of JavaScript import paths registered by the extension.
//
// Currently, paths must start with the prefix `k6/x/`.
//
// The extensions used by k6 scripts are automatically detected based on the
// values specified here, therefore it is important that the values used here are
// consistent with the values registered by the extension at runtime.
//
Imports []string `json:"imports,omitempty" yaml:"imports,omitempty" mapstructure:"imports,omitempty"`
// The extension's go module path.
//
// This is the unique identifier of the extension.
// More info about module paths: https://go.dev/ref/mod#module-path
//
// The extension has no name property, the module path or part of it can be used
// as the extension name. For example, using the first two elements of the module
// path after the host name, the name `grafana/xk6-dashboard` can be formed from
// the module path `github.com/grafana/xk6-dashboard`. This is typically the
// repository owner name and the repository name in the repository manager.
//
// The extension has no URL property, a URL can be created from the module path
// that refers to the extension within the repository manager.
//
Module string `json:"module" yaml:"module" mapstructure:"module"`
// List of output names registered by the extension.
//
// The extensions used by k6 scripts are automatically detected based on the
// values specified here, therefore it is important that the values used here are
// consistent with the values registered by the extension at runtime.
//
Outputs []string `json:"outputs,omitempty" yaml:"outputs,omitempty" mapstructure:"outputs,omitempty"`
// Repository metadata.
//
// Metadata provided by the extension's git repository manager. Repository
// metadata are not registered, they are queried at runtime using the repository
// manager API.
//
Repo *Repository `json:"repo,omitempty" yaml:"repo,omitempty" mapstructure:"repo,omitempty"`
// Maintainer of the extension.
//
// Possible values:
//
// - official: Extensions owned, maintained, and designated by Grafana as
// "official"
// - community: Extensions are listed on the Registry by individual maintainers,
// groups of maintainers, or other members of the k6 community.
//
// Extensions owned by the `grafana` GitHub organization are not officially
// supported by Grafana by default.
// There are several k6 extensions owned by the `grafana` GitHub organization,
// which were created for experimental or example purposes only.
// The `official` tier value is needed so that officially supported extensions can
// be distinguished from them.
//
// If it is missing from the registry source, it will be set with the default
// "community" value during generation.
//
Tier Tier `json:"tier,omitempty" yaml:"tier,omitempty" mapstructure:"tier,omitempty"`
// List of supported versions.
//
// Versions are tags whose format meets the requirements of semantic versioning.
// Version tags often start with the letter `v`, which is not part of the semantic
// version.
//
Versions []string `json:"versions,omitempty" yaml:"versions,omitempty" mapstructure:"versions,omitempty"`
}
Properties of the registered k6 extension.
Only those properties of the extensions are registered, which either cannot be detected automatically, or delegation to the extension is not allowed.
Properties that are available using the repository manager API are intentionally not registered.
The string like properties that are included in the generated Grafana documentation are intentionally not accessed via the API of the repository manager. It is not allowed to inject arbitrary text into the Grafana documentation site without approval. Therefore, these properties are registered (eg `description`)
type ExtensionCompliance ¶ added in v0.5.0
type ExtensionCompliance map[string]Compliance
The result of the extension's k6 compliance checks.
type Metrics ¶ added in v0.1.36
type Metrics struct {
// Number of extensions requiring cgo.
CgoCount int `json:"cgo_count,omitempty" yaml:"cgo_count,omitempty" mapstructure:"cgo_count,omitempty"`
// The total number of extensions.
ExtensionCount int `json:"extension_count,omitempty" yaml:"extension_count,omitempty" mapstructure:"extension_count,omitempty"`
// Number of extensions not buildable with the latest k6 version.
IssueBuildCount int `json:"issue_build_count,omitempty" yaml:"issue_build_count,omitempty" mapstructure:"issue_build_count,omitempty"`
// Number of extensions without CODEOWNERS file.
IssueCodeownersCount int `` /* 127-byte string literal not displayed */
// Number of extensions without examples directory.
IssueExamplesCount int `json:"issue_examples_count,omitempty" yaml:"issue_examples_count,omitempty" mapstructure:"issue_examples_count,omitempty"`
// Number of extensions without git workdir.
IssueGitCount int `json:"issue_git_count,omitempty" yaml:"issue_git_count,omitempty" mapstructure:"issue_git_count,omitempty"`
// Number of extensions without suitable OSS license.
IssueLicenseCount int `json:"issue_license_count,omitempty" yaml:"issue_license_count,omitempty" mapstructure:"issue_license_count,omitempty"`
// Number of extensions without valid go.mod.
IssueModuleCount int `json:"issue_module_count,omitempty" yaml:"issue_module_count,omitempty" mapstructure:"issue_module_count,omitempty"`
// Number of extensions without readme file.
IssueReadmeCount int `json:"issue_readme_count,omitempty" yaml:"issue_readme_count,omitempty" mapstructure:"issue_readme_count,omitempty"`
// Number of extensions with replace directive in go.mod.
IssueReplaceCount int `json:"issue_replace_count,omitempty" yaml:"issue_replace_count,omitempty" mapstructure:"issue_replace_count,omitempty"`
// Number of extensions without smoke test script.
IssueSmokeCount int `json:"issue_smoke_count,omitempty" yaml:"issue_smoke_count,omitempty" mapstructure:"issue_smoke_count,omitempty"`
// Number of extensions without API declaration file.
IssueTypesCount int `json:"issue_types_count,omitempty" yaml:"issue_types_count,omitempty" mapstructure:"issue_types_count,omitempty"`
// Number of extensions without semantic versioning git tags.
IssueVersionsCount int `json:"issue_versions_count,omitempty" yaml:"issue_versions_count,omitempty" mapstructure:"issue_versions_count,omitempty"`
// Number of extension in the community' tier.
TierCommunityCount int `json:"tier_community_count,omitempty" yaml:"tier_community_count,omitempty" mapstructure:"tier_community_count,omitempty"`
// Number of extensions in the 'official' tier.
TierOfficialCount int `json:"tier_official_count,omitempty" yaml:"tier_official_count,omitempty" mapstructure:"tier_official_count,omitempty"`
// Number of JavaScript extension.
TypeJavaScriptCount int `json:"type_javascript_count,omitempty" yaml:"type_javascript_count,omitempty" mapstructure:"type_javascript_count,omitempty"`
// Number of Output extension.
TypeOutputCount int `json:"type_output_count,omitempty" yaml:"type_output_count,omitempty" mapstructure:"type_output_count,omitempty"`
}
Extension registry metrics.
type Registry ¶
type Registry []Extension
k6 Extension Registry.
The k6 extension registry contains the most important properties of registered extensions.
type Repository ¶ added in v0.1.1
type Repository struct {
// Archived repository flag.
//
// A `true` value indicates that the repository is archived, read only.
//
// If a repository is archived, it usually means that the owner has no intention
// of maintaining it. Such extensions should be removed from the registry.
//
Archived bool `json:"archived,omitempty" yaml:"archived,omitempty" mapstructure:"archived,omitempty"`
// URL for the git clone operation.
//
// The clone_url property contains a (typically HTTP) URL, which is used to clone
// the repository.
//
CloneURL string `json:"clone_url,omitempty" yaml:"clone_url,omitempty" mapstructure:"clone_url,omitempty"`
// Repository description.
//
Description string `json:"description,omitempty" yaml:"description,omitempty" mapstructure:"description,omitempty"`
// The URL to the project homepage.
//
// If no homepage is set, the value is the same as the url property.
//
Homepage string `json:"homepage,omitempty" yaml:"homepage,omitempty" mapstructure:"homepage,omitempty"`
// The SPDX ID of the extension's license.
//
// For more information about SPDX, visit https://spdx.org/licenses/
//
License string `json:"license,omitempty" yaml:"license,omitempty" mapstructure:"license,omitempty"`
// The name of the repository.
//
Name string `json:"name" yaml:"name" mapstructure:"name"`
// The owner of the repository.
//
Owner string `json:"owner" yaml:"owner" mapstructure:"owner"`
// Public repository flag.
//
// A `true` value indicates that the repository is public, available to anyone.
//
Public bool `json:"public,omitempty" yaml:"public,omitempty" mapstructure:"public,omitempty"`
// The number of stars in the extension's repository.
//
// The extension's popularity is indicated by how many users have starred the
// extension's repository.
//
Stars int `json:"stars,omitempty" yaml:"stars,omitempty" mapstructure:"stars,omitempty"`
// Last modification timestamp.
//
// The timestamp property contains the timestamp of the last modification of the
// repository in UNIX time format (the number of non-leap seconds that have
// elapsed since 00:00:00 UTC on 1st January 1970).
// Its value depends on the repository manager, in the case of GitHub it contains
// the time of the last push operation, in the case of GitLab the time of the last
// repository activity.
//
Timestamp float64 `json:"timestamp,omitempty" yaml:"timestamp,omitempty" mapstructure:"timestamp,omitempty"`
// Repository topics.
//
// Topics make it easier to find the repository. It is recommended to set the xk6
// topic to the extensions repository.
//
Topics []string `json:"topics,omitempty" yaml:"topics,omitempty" mapstructure:"topics,omitempty"`
// URL of the repository.
//
// The URL is provided by the repository manager and can be displayed in a
// browser.
//
URL string `json:"url" yaml:"url" mapstructure:"url"`
}
Repository metadata.
Metadata provided by the extension's git repository manager. Repository metadata are not registered, they are queried at runtime using the repository manager API.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cmd contains run cobra command factory function.
|
Package cmd contains run cobra command factory function. |
|
k6registry
command
Package main contains the main function for k6registry CLI tool.
|
Package main contains the main function for k6registry CLI tool. |
|
tools
|
|
|
gendoc
command
Package main contains CLI documentation generator tool.
|
Package main contains CLI documentation generator tool. |
Click to show internal directories.
Click to hide internal directories.