diff --git a/docs/sources/k6/next/extensions/_index.md b/docs/sources/k6/next/extensions/_index.md index 9ef78d94f4..618637e1a4 100644 --- a/docs/sources/k6/next/extensions/_index.md +++ b/docs/sources/k6/next/extensions/_index.md @@ -6,7 +6,10 @@ weight: 700 # Extensions - +With k6 extensions, you can extend the core k6 functionality with new features to support your specific reliability-testing needs. -{{< section >}} +k6 supports three types of extensions: +- **JavaScript extensions** extend the JavaScript APIs available to your test scripts. They can add support for new network protocols, improve performance compared to equivalent JS libraries, or add features. +- **Output extensions** send metrics to a custom file format or service. They can add custom processing and dispatching methods. +- **Secret Source extensions** provide secrets to your tests. diff --git a/docs/sources/k6/next/extensions/create/_index.md b/docs/sources/k6/next/extensions/create/_index.md index d223c2e476..c608aed65b 100644 --- a/docs/sources/k6/next/extensions/create/_index.md +++ b/docs/sources/k6/next/extensions/create/_index.md @@ -1,11 +1,11 @@ --- -title: 'Create a new extension' -menuTitle: 'Create a new extension' -description: 'Creating k6 extensions does not have to be a daunting task, but there are some prerequisites to succeed.' +title: 'Create a k6 extension' +menuTitle: 'Create an extension' +description: 'Learn how to create a k6 extension.' weight: 04 --- -# Create a new k6 extension +# Create a k6 extension If you find a gap in your testing process that no k6 extension can fix, consider building your own extension. Use the tutorials below to get started. diff --git a/docs/sources/k6/v1.2.x/extensions/explanations/extensions-registry.md b/docs/sources/k6/next/extensions/create/extensions-registry.md similarity index 98% rename from docs/sources/k6/v1.2.x/extensions/explanations/extensions-registry.md rename to docs/sources/k6/next/extensions/create/extensions-registry.md index dd1b6f93d7..8e851c5aac 100644 --- a/docs/sources/k6/v1.2.x/extensions/explanations/extensions-registry.md +++ b/docs/sources/k6/next/extensions/create/extensions-registry.md @@ -1,7 +1,7 @@ --- title: About the Extensions Registry description: Reasons for the registry and what is required to be included. -weight: 01 +weight: 600 --- # About the Extensions Registry @@ -18,7 +18,7 @@ To ensure quality, we need a well-maintained, curated listing of extensions. Our pledge to the community is to make our best attempt to ensure the listed projects meet certain standards. While we cannot guarantee the quality of community-provided extensions, we _can_ aid the evaluation by requiring certain consistencies. -## Registry Requirements +## Registry requirements At minimum, each source code repository must have the following: @@ -55,7 +55,7 @@ At minimum, each source code repository must have the following: For example, if latest version of k6 is `v0.100`, the extension must build with at least version `v0.98`. Be sure to also match the version of Go as determined by the version of k6. -## Naming Conventions +## Naming conventions Some extensions may be very specific, where others are more general. Multiple extensions may even be created for the same product with different levels of support based upon version. @@ -76,7 +76,7 @@ Our goal is to quickly understand the intent of the extension. {{< /admonition >}} -## Potential for De-listing +## Potential for de-listing Given our desire to provide the best developer experience when using k6, we reserve the right to de-list any extension we deem is no longer maintaining standards. Before any action takes place, the extension maintainers will be contacted to be given a chance to rectify the project and thus avoid de-listing. diff --git a/docs/sources/k6/v1.2.x/extensions/explanations/go-js-bridge.md b/docs/sources/k6/next/extensions/create/go-js-bridge.md similarity index 99% rename from docs/sources/k6/v1.2.x/extensions/explanations/go-js-bridge.md rename to docs/sources/k6/next/extensions/create/go-js-bridge.md index 5fc85940bd..e4cac578f2 100644 --- a/docs/sources/k6/v1.2.x/extensions/explanations/go-js-bridge.md +++ b/docs/sources/k6/next/extensions/create/go-js-bridge.md @@ -1,7 +1,7 @@ --- title: About the Go-to-JS bridge description: Technical details about how JavaScript works in the sobek engine. -weight: 02 +weight: 700 --- # About the Go-to-JS bridge diff --git a/docs/sources/k6/next/extensions/create/javascript-extensions.md b/docs/sources/k6/next/extensions/create/javascript-extensions.md index 21386283cf..9ae19c2c41 100644 --- a/docs/sources/k6/next/extensions/create/javascript-extensions.md +++ b/docs/sources/k6/next/extensions/create/javascript-extensions.md @@ -1,10 +1,10 @@ --- -title: 'JavaScript Extensions' +title: 'JavaScript extensions' description: 'Follow these steps to build a JS extension for k6.' weight: 300 --- -# JavaScript Extensions +# JavaScript extensions Take advantage of Go's speed, power, and efficiency while providing the flexibility of using JavaScript APIs within your test scripts. diff --git a/docs/sources/k6/next/extensions/create/output-extensions.md b/docs/sources/k6/next/extensions/create/output-extensions.md index 2e1ec715f8..aa5a307503 100644 --- a/docs/sources/k6/next/extensions/create/output-extensions.md +++ b/docs/sources/k6/next/extensions/create/output-extensions.md @@ -1,10 +1,10 @@ --- -title: 'Output Extensions' +title: 'Output extensions' description: 'Follow these steps to build an output extension for k6.' weight: 400 --- -# Output Extensions +# Output extensions k6 provides many [metrics](https://grafana.com/docs/k6//using-k6/metrics) and [output formats](https://grafana.com/docs/k6//results-output/), but it cannot directly support all possibilities. To store or alter metrics captured during an active k6 test, diff --git a/docs/sources/k6/next/extensions/create/secret-source_extensions.md b/docs/sources/k6/next/extensions/create/secret-source_extensions.md index 4171ed5833..b2a7cb47a0 100644 --- a/docs/sources/k6/next/extensions/create/secret-source_extensions.md +++ b/docs/sources/k6/next/extensions/create/secret-source_extensions.md @@ -1,10 +1,10 @@ --- -title: 'Secret source Extensions' +title: 'Secret source extensions' description: 'Follow these steps to build an secret source extension for k6.' weight: 500 --- -# Secret Source Extensions +# Secret Source extensions Secret source extension allow users to write or use written by other users extensions in order to get secrets to be used within k6 tests. diff --git a/docs/sources/k6/next/extensions/explanations/_index.md b/docs/sources/k6/next/extensions/explanations/_index.md deleted file mode 100644 index b8ac554667..0000000000 --- a/docs/sources/k6/next/extensions/explanations/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Explanations -weight: 05 ---- - -# Explanations - - - -{{< section >}} diff --git a/docs/sources/k6/next/extensions/explore.md b/docs/sources/k6/next/extensions/explore.md index 662494021b..6366a6cc1e 100644 --- a/docs/sources/k6/next/extensions/explore.md +++ b/docs/sources/k6/next/extensions/explore.md @@ -1,67 +1,65 @@ --- title: 'Explore extensions' menuTitle: 'Explore extensions' -description: 'Explore the k6 extension ecosystem to find extensions that meet your requirements.' +description: 'Explore the k6 extension ecosystem to find extensions that fit your use cases.' weight: 01 --- # Explore extensions -## Supported by automatic extension resolution +Extensions can be used to extend the core k6 features to fit your performance-testing use cases. There are two main categories of extensions: -These extensions can be used in your test without any additional configuration. They are automatically resolved and loaded by k6 when you [import them in your test script](https://grafana.com/docs/k6//extensions/run/#using-automatic-extension-loading). - -We have two categories of extensions: - -| Category | Maintainer | Audited | Cloud support | -| ------------- | ----------------------------------- | ------- | ------------- | -| **Official** | Grafana Labs | ✅ Yes | ✅ Yes | -| **Community** | Community | ✅ Yes | ⚠️ Partial\* | +| Category | Maintainer | Audited | Cloud support | +| ------------- | ------------ | ------- | ------------- | +| **Official** | Grafana Labs | ✅ Yes | ✅ Yes | +| **Community** | Community | ✅ Yes | ⚠️ Partial\* | -\* *Partial* means that they can be used in the CLI with the `--local-execution` mode. Also, on Private Load Zones if a custom image is build. They don't work on Grafana Cloud k6 Public Load Zones. +\* _Partial_ cloud support means that the extensions can be used in the CLI with the `--local-execution` mode, and on Private Load Zones with a custom image. They don't work on Grafana Cloud k6 Public Load Zones. -### Official extensions +## Official extensions -| Extension | Description | Versions | -| --------- | ----------- | -------- | -| [xk6-client-prometheus-remote](https://github.com/grafana/xk6-client-prometheus-remote) | Test Prometheus Remote Write-compatible endpoints | 0.3.2 | -| [xk6-faker](https://github.com/grafana/xk6-faker) | Generate fake data in your tests | 0.4.0, 0.4.1, 0.4.2, 0.4.3, 0.4.4 | -| [xk6-loki](https://github.com/grafana/xk6-loki) | Test Grafana Loki log ingestion endpoints | 1.0.0, 1.0.1 | +| Extension | Description | Versions | +| --------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------- | +| [xk6-client-prometheus-remote](https://github.com/grafana/xk6-client-prometheus-remote) | Test Prometheus Remote Write-compatible endpoints | 0.3.2 | +| [xk6-faker](https://github.com/grafana/xk6-faker) | Generate fake data in your tests | 0.4.0, 0.4.1, 0.4.2, 0.4.3, 0.4.4 | +| [xk6-loki](https://github.com/grafana/xk6-loki) | Test Grafana Loki log ingestion endpoints | 1.0.0, 1.0.1 | | [xk6-sql](https://github.com/grafana/xk6-sql) | Test SQL servers | 1.0.0, 1.0.1, 1.0.2, 1.0.3, 1.0.4, 1.0.5 | -| [xk6-sql-driver-mysql](https://github.com/grafana/xk6-sql-driver-mysql) | SQL driver for MySQL | 0.1.0, 0.2.0, 0.2.1 | -| [xk6-sql-driver-postgres](https://github.com/grafana/xk6-sql-driver-postgres) | SQL driver for Postgres | 0.1.0, 0.1.1 | -| [xk6-ssh](https://github.com/grafana/xk6-ssh) | Use SSH connections in your tests | 0.1.0, 0.1.1, 0.1.2, 0.1.3 | +| [xk6-sql-driver-mysql](https://github.com/grafana/xk6-sql-driver-mysql) | SQL driver for MySQL | 0.1.0, 0.2.0, 0.2.1 | +| [xk6-sql-driver-postgres](https://github.com/grafana/xk6-sql-driver-postgres) | SQL driver for Postgres | 0.1.0, 0.1.1 | +| [xk6-ssh](https://github.com/grafana/xk6-ssh) | Use SSH connections in your tests | 0.1.0, 0.1.1, 0.1.2, 0.1.3 | -### Community extensions +## Community extensions {{< admonition type="note" >}} -We are working on process for community folks to submit their extensions to be included here. +We're working on a process for community folks to submit their extensions. {{< /admonition >}} -| Extension | Description | Versions | -| --------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------- | -| [xk6-kafka](https://github.com/mostafa/xk6-kafka) | Load test Apache Kafka | 1.0.0 | -| [xk6-sql-driver-azuresql](https://github.com/grafana/xk6-sql-driver-azuresql) | SQL driver for AzureSQL | 0.1.0, 0.1.1 | -| [xk6-sql-driver-clickhouse](https://github.com/grafana/xk6-sql-driver-clickhouse) | SQL driver for Clickhouse | 0.1.0, 0.1.1 | -| [xk6-sql-driver-sqlserver](https://github.com/grafana/xk6-sql-driver-sqlserver) | SQL driver for SQLite3 | 0.1.0, 0.1.1 | -| [xk6-sse](https://github.com/phymbert/xk6-sse) | Test with Server-Sent Events (SSE) | 0.1.10, 0.1.11 | +| Extension | Description | Versions | +| --------------------------------------------------------------------------------- | ---------------------------------- | -------------- | +| [xk6-kafka](https://github.com/mostafa/xk6-kafka) | Load test Apache Kafka | 1.0.0 | +| [xk6-sql-driver-azuresql](https://github.com/grafana/xk6-sql-driver-azuresql) | SQL driver for AzureSQL | 0.1.0, 0.1.1 | +| [xk6-sql-driver-clickhouse](https://github.com/grafana/xk6-sql-driver-clickhouse) | SQL driver for Clickhouse | 0.1.0, 0.1.1 | +| [xk6-sql-driver-sqlserver](https://github.com/grafana/xk6-sql-driver-sqlserver) | SQL driver for SQLite3 | 0.1.0, 0.1.1 | +| [xk6-sse](https://github.com/phymbert/xk6-sse) | Test with Server-Sent Events (SSE) | 0.1.10, 0.1.11 | + +## Use extensions -## Require building a custom k6 binary +There are two ways to use extensions when running a k6 test script. -### Your own extensions +### Automatic extension resolution -If you have developed your own k6 extension or want to use an extension that's not available through automatic extension resolution, you'll need to build a custom k6 binary. This process involves using the xk6 tool to compile k6 with your desired extensions included. Custom binaries give you the flexibility to incorporate any extension from the k6 ecosystem. +These extensions can be used in your test without any additional configuration. They are automatically resolved and loaded by k6 when you [import them in your test script](https://grafana.com/docs/k6//extensions/run/#using-automatic-extension-loading). -Check out how to [build a custom k6 binary guide](https://grafana.com/docs/k6//extensions/run/#using-extensions-that-require-building-a-custom-k6-binary) to learn how to create your own k6 binary with custom extensions. +### Custom k6 binary -### More ecosystem extensions +If you have developed your own k6 extension or want to use an extension that's not available through automatic extension resolution, you have to build a custom k6 binary. The process involves using the xk6 tool to compile k6 with your desired extensions included. Custom binaries give you the flexibility to incorporate any extension from the k6 ecosystem. + +Refer to [build a custom k6 binary guide](https://grafana.com/docs/k6//extensions/run/#use-extensions-with-a-custom-k6-binary) to learn how to create your own k6 binary with custom extensions. {{< admonition type="caution" >}} -The extensions in this category are not maintained nor audited by Grafana Labs. +Many other extensions maintained by members of the k6 ecosystem are available in [GitHub](https://github.com/topics/xk6). These extensions aren't maintained nor audited by Grafana Labs. {{< /admonition >}} - -Many other extensions, maintained by members of the k6 ecosystem are available in [GitHub](https://github.com/topics/xk6). diff --git a/docs/sources/k6/next/extensions/run/_index.md b/docs/sources/k6/next/extensions/run/_index.md index dc8de23863..8f4ff7f406 100644 --- a/docs/sources/k6/next/extensions/run/_index.md +++ b/docs/sources/k6/next/extensions/run/_index.md @@ -1,17 +1,21 @@ --- title: 'Run a test with extensions' menuTitle: 'Run a test with extensions' -description: 'Run k6 with extensions to cover use cases not supported natively in the core.' +description: 'Learn how to run a k6 test with extensions.' weight: 03 --- # Run a test with extensions -As explained in the [Explore extensions](https://grafana.com/docs/k6//extensions/explore) page, there are extensions that can be used directly in your test script, and others that require building a custom k6 binary. +There are two different ways to run your k6 test script depending on the k6 extension you want to use: using the automatic extension resolution, or building a custom k6 binary. -## Using automatic extension resolution +## Before you begin -It is as easy as importing them. Example with [xk6-faker](https://github.com/grafana/xk6-faker): +- [Install k6](https://grafana.com/docs/k6//set-up/install-k6/) v1.2.0 or higher. + +## Use automatic extension resolution + +It's as easy as importing them. Example with [xk6-faker](https://github.com/grafana/xk6-faker): ```javascript import faker from 'k6/x/faker'; @@ -21,7 +25,7 @@ export default function () { } ``` -Then, you can run your script as usual, and k6 will automatically detect the extension and load it: +Then, you can run your script as usual, and k6 automatically detects the extension and loads it: ```sh k6 run script.js @@ -31,7 +35,6 @@ k6 run script.js To use community extensions you must have `K6_ENABLE_COMMUNITY_EXTENSIONS` set to `true`. - ```sh K6_ENABLE_COMMUNITY_EXTENSIONS=true k6 run test.js ``` @@ -41,23 +44,24 @@ K6_ENABLE_COMMUNITY_EXTENSIONS=true k6 run test.js ### Limitations - Only works with Official and Community extensions. -- Output extensions are not supported. -- Running scripts from stdin is not supported. -- Only files with extensions `.js`, `.ts` or `.tar` can be used. +- Output extensions aren't supported. +- Running scripts from stdin isn't supported. +- Only files with extensions `.js`, `.ts` or `.tar` can be used. -### How to disable this feature +### Disable automatic extension resolution You can disable this feature by setting the environment variable `K6_AUTO_EXTENSION_RESOLUTION` to `false`. If provided, the previous example -fails because k6 can't load the extension dynamically. +fails because k6 can't load the extension dynamically. + ```bash K6_AUTO_EXTENSION_RESOLUTION=false k6 run test.js ``` -## Using extensions that require building a custom k6 binary +## Use extensions with a custom k6 binary -To run other extensions (including ones you create), you need to build a custom k6 binary with [xk6](https://github.com/grafana/xk6/). +To run other extensions (including ones you create), you need to build a custom k6 binary with [xk6](https://github.com/grafana/xk6/). -You can do this locally with [Go](https://grafana.com/docs/k6//extensions/run/build-k6-binary-using-go/) or use the [xk6 Docker image](https://grafana.com/docs/k6//extensions/run/build-k6-binary-using-docker/). +You can do this locally with Go or use the xk6 Docker image. {{< code >}} @@ -74,4 +78,7 @@ docker run --rm -u "$(id -u):$(id -g)" -v "${PWD}:/xk6" grafana/xk6 build \ {{< /code >}} -
\ No newline at end of file +For more details, refer to: + +- [Build a k6 binary using Go](https://grafana.com/docs/k6//extensions/run/build-k6-binary-using-go/) +- [Build a k6 binary using Docker](https://grafana.com/docs/k6//extensions/run/build-k6-binary-using-docker/) diff --git a/docs/sources/k6/v1.2.x/extensions/_index.md b/docs/sources/k6/v1.2.x/extensions/_index.md index 9ef78d94f4..618637e1a4 100644 --- a/docs/sources/k6/v1.2.x/extensions/_index.md +++ b/docs/sources/k6/v1.2.x/extensions/_index.md @@ -6,7 +6,10 @@ weight: 700 # Extensions - +With k6 extensions, you can extend the core k6 functionality with new features to support your specific reliability-testing needs. -{{< section >}} +k6 supports three types of extensions: +- **JavaScript extensions** extend the JavaScript APIs available to your test scripts. They can add support for new network protocols, improve performance compared to equivalent JS libraries, or add features. +- **Output extensions** send metrics to a custom file format or service. They can add custom processing and dispatching methods. +- **Secret Source extensions** provide secrets to your tests. diff --git a/docs/sources/k6/v1.2.x/extensions/create/_index.md b/docs/sources/k6/v1.2.x/extensions/create/_index.md index d223c2e476..c608aed65b 100644 --- a/docs/sources/k6/v1.2.x/extensions/create/_index.md +++ b/docs/sources/k6/v1.2.x/extensions/create/_index.md @@ -1,11 +1,11 @@ --- -title: 'Create a new extension' -menuTitle: 'Create a new extension' -description: 'Creating k6 extensions does not have to be a daunting task, but there are some prerequisites to succeed.' +title: 'Create a k6 extension' +menuTitle: 'Create an extension' +description: 'Learn how to create a k6 extension.' weight: 04 --- -# Create a new k6 extension +# Create a k6 extension If you find a gap in your testing process that no k6 extension can fix, consider building your own extension. Use the tutorials below to get started. diff --git a/docs/sources/k6/next/extensions/explanations/extensions-registry.md b/docs/sources/k6/v1.2.x/extensions/create/extensions-registry.md similarity index 98% rename from docs/sources/k6/next/extensions/explanations/extensions-registry.md rename to docs/sources/k6/v1.2.x/extensions/create/extensions-registry.md index dd1b6f93d7..8e851c5aac 100644 --- a/docs/sources/k6/next/extensions/explanations/extensions-registry.md +++ b/docs/sources/k6/v1.2.x/extensions/create/extensions-registry.md @@ -1,7 +1,7 @@ --- title: About the Extensions Registry description: Reasons for the registry and what is required to be included. -weight: 01 +weight: 600 --- # About the Extensions Registry @@ -18,7 +18,7 @@ To ensure quality, we need a well-maintained, curated listing of extensions. Our pledge to the community is to make our best attempt to ensure the listed projects meet certain standards. While we cannot guarantee the quality of community-provided extensions, we _can_ aid the evaluation by requiring certain consistencies. -## Registry Requirements +## Registry requirements At minimum, each source code repository must have the following: @@ -55,7 +55,7 @@ At minimum, each source code repository must have the following: For example, if latest version of k6 is `v0.100`, the extension must build with at least version `v0.98`. Be sure to also match the version of Go as determined by the version of k6. -## Naming Conventions +## Naming conventions Some extensions may be very specific, where others are more general. Multiple extensions may even be created for the same product with different levels of support based upon version. @@ -76,7 +76,7 @@ Our goal is to quickly understand the intent of the extension. {{< /admonition >}} -## Potential for De-listing +## Potential for de-listing Given our desire to provide the best developer experience when using k6, we reserve the right to de-list any extension we deem is no longer maintaining standards. Before any action takes place, the extension maintainers will be contacted to be given a chance to rectify the project and thus avoid de-listing. diff --git a/docs/sources/k6/next/extensions/explanations/go-js-bridge.md b/docs/sources/k6/v1.2.x/extensions/create/go-js-bridge.md similarity index 99% rename from docs/sources/k6/next/extensions/explanations/go-js-bridge.md rename to docs/sources/k6/v1.2.x/extensions/create/go-js-bridge.md index 5fc85940bd..e4cac578f2 100644 --- a/docs/sources/k6/next/extensions/explanations/go-js-bridge.md +++ b/docs/sources/k6/v1.2.x/extensions/create/go-js-bridge.md @@ -1,7 +1,7 @@ --- title: About the Go-to-JS bridge description: Technical details about how JavaScript works in the sobek engine. -weight: 02 +weight: 700 --- # About the Go-to-JS bridge diff --git a/docs/sources/k6/v1.2.x/extensions/create/javascript-extensions.md b/docs/sources/k6/v1.2.x/extensions/create/javascript-extensions.md index 21386283cf..9ae19c2c41 100644 --- a/docs/sources/k6/v1.2.x/extensions/create/javascript-extensions.md +++ b/docs/sources/k6/v1.2.x/extensions/create/javascript-extensions.md @@ -1,10 +1,10 @@ --- -title: 'JavaScript Extensions' +title: 'JavaScript extensions' description: 'Follow these steps to build a JS extension for k6.' weight: 300 --- -# JavaScript Extensions +# JavaScript extensions Take advantage of Go's speed, power, and efficiency while providing the flexibility of using JavaScript APIs within your test scripts. diff --git a/docs/sources/k6/v1.2.x/extensions/create/output-extensions.md b/docs/sources/k6/v1.2.x/extensions/create/output-extensions.md index 2e1ec715f8..aa5a307503 100644 --- a/docs/sources/k6/v1.2.x/extensions/create/output-extensions.md +++ b/docs/sources/k6/v1.2.x/extensions/create/output-extensions.md @@ -1,10 +1,10 @@ --- -title: 'Output Extensions' +title: 'Output extensions' description: 'Follow these steps to build an output extension for k6.' weight: 400 --- -# Output Extensions +# Output extensions k6 provides many [metrics](https://grafana.com/docs/k6//using-k6/metrics) and [output formats](https://grafana.com/docs/k6//results-output/), but it cannot directly support all possibilities. To store or alter metrics captured during an active k6 test, diff --git a/docs/sources/k6/v1.2.x/extensions/create/secret-source_extensions.md b/docs/sources/k6/v1.2.x/extensions/create/secret-source_extensions.md index 4171ed5833..b2a7cb47a0 100644 --- a/docs/sources/k6/v1.2.x/extensions/create/secret-source_extensions.md +++ b/docs/sources/k6/v1.2.x/extensions/create/secret-source_extensions.md @@ -1,10 +1,10 @@ --- -title: 'Secret source Extensions' +title: 'Secret source extensions' description: 'Follow these steps to build an secret source extension for k6.' weight: 500 --- -# Secret Source Extensions +# Secret Source extensions Secret source extension allow users to write or use written by other users extensions in order to get secrets to be used within k6 tests. diff --git a/docs/sources/k6/v1.2.x/extensions/explanations/_index.md b/docs/sources/k6/v1.2.x/extensions/explanations/_index.md deleted file mode 100644 index b8ac554667..0000000000 --- a/docs/sources/k6/v1.2.x/extensions/explanations/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Explanations -weight: 05 ---- - -# Explanations - - - -{{< section >}} diff --git a/docs/sources/k6/v1.2.x/extensions/explore.md b/docs/sources/k6/v1.2.x/extensions/explore.md index 662494021b..6366a6cc1e 100644 --- a/docs/sources/k6/v1.2.x/extensions/explore.md +++ b/docs/sources/k6/v1.2.x/extensions/explore.md @@ -1,67 +1,65 @@ --- title: 'Explore extensions' menuTitle: 'Explore extensions' -description: 'Explore the k6 extension ecosystem to find extensions that meet your requirements.' +description: 'Explore the k6 extension ecosystem to find extensions that fit your use cases.' weight: 01 --- # Explore extensions -## Supported by automatic extension resolution +Extensions can be used to extend the core k6 features to fit your performance-testing use cases. There are two main categories of extensions: -These extensions can be used in your test without any additional configuration. They are automatically resolved and loaded by k6 when you [import them in your test script](https://grafana.com/docs/k6//extensions/run/#using-automatic-extension-loading). - -We have two categories of extensions: - -| Category | Maintainer | Audited | Cloud support | -| ------------- | ----------------------------------- | ------- | ------------- | -| **Official** | Grafana Labs | ✅ Yes | ✅ Yes | -| **Community** | Community | ✅ Yes | ⚠️ Partial\* | +| Category | Maintainer | Audited | Cloud support | +| ------------- | ------------ | ------- | ------------- | +| **Official** | Grafana Labs | ✅ Yes | ✅ Yes | +| **Community** | Community | ✅ Yes | ⚠️ Partial\* | -\* *Partial* means that they can be used in the CLI with the `--local-execution` mode. Also, on Private Load Zones if a custom image is build. They don't work on Grafana Cloud k6 Public Load Zones. +\* _Partial_ cloud support means that the extensions can be used in the CLI with the `--local-execution` mode, and on Private Load Zones with a custom image. They don't work on Grafana Cloud k6 Public Load Zones. -### Official extensions +## Official extensions -| Extension | Description | Versions | -| --------- | ----------- | -------- | -| [xk6-client-prometheus-remote](https://github.com/grafana/xk6-client-prometheus-remote) | Test Prometheus Remote Write-compatible endpoints | 0.3.2 | -| [xk6-faker](https://github.com/grafana/xk6-faker) | Generate fake data in your tests | 0.4.0, 0.4.1, 0.4.2, 0.4.3, 0.4.4 | -| [xk6-loki](https://github.com/grafana/xk6-loki) | Test Grafana Loki log ingestion endpoints | 1.0.0, 1.0.1 | +| Extension | Description | Versions | +| --------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------- | +| [xk6-client-prometheus-remote](https://github.com/grafana/xk6-client-prometheus-remote) | Test Prometheus Remote Write-compatible endpoints | 0.3.2 | +| [xk6-faker](https://github.com/grafana/xk6-faker) | Generate fake data in your tests | 0.4.0, 0.4.1, 0.4.2, 0.4.3, 0.4.4 | +| [xk6-loki](https://github.com/grafana/xk6-loki) | Test Grafana Loki log ingestion endpoints | 1.0.0, 1.0.1 | | [xk6-sql](https://github.com/grafana/xk6-sql) | Test SQL servers | 1.0.0, 1.0.1, 1.0.2, 1.0.3, 1.0.4, 1.0.5 | -| [xk6-sql-driver-mysql](https://github.com/grafana/xk6-sql-driver-mysql) | SQL driver for MySQL | 0.1.0, 0.2.0, 0.2.1 | -| [xk6-sql-driver-postgres](https://github.com/grafana/xk6-sql-driver-postgres) | SQL driver for Postgres | 0.1.0, 0.1.1 | -| [xk6-ssh](https://github.com/grafana/xk6-ssh) | Use SSH connections in your tests | 0.1.0, 0.1.1, 0.1.2, 0.1.3 | +| [xk6-sql-driver-mysql](https://github.com/grafana/xk6-sql-driver-mysql) | SQL driver for MySQL | 0.1.0, 0.2.0, 0.2.1 | +| [xk6-sql-driver-postgres](https://github.com/grafana/xk6-sql-driver-postgres) | SQL driver for Postgres | 0.1.0, 0.1.1 | +| [xk6-ssh](https://github.com/grafana/xk6-ssh) | Use SSH connections in your tests | 0.1.0, 0.1.1, 0.1.2, 0.1.3 | -### Community extensions +## Community extensions {{< admonition type="note" >}} -We are working on process for community folks to submit their extensions to be included here. +We're working on a process for community folks to submit their extensions. {{< /admonition >}} -| Extension | Description | Versions | -| --------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------- | -| [xk6-kafka](https://github.com/mostafa/xk6-kafka) | Load test Apache Kafka | 1.0.0 | -| [xk6-sql-driver-azuresql](https://github.com/grafana/xk6-sql-driver-azuresql) | SQL driver for AzureSQL | 0.1.0, 0.1.1 | -| [xk6-sql-driver-clickhouse](https://github.com/grafana/xk6-sql-driver-clickhouse) | SQL driver for Clickhouse | 0.1.0, 0.1.1 | -| [xk6-sql-driver-sqlserver](https://github.com/grafana/xk6-sql-driver-sqlserver) | SQL driver for SQLite3 | 0.1.0, 0.1.1 | -| [xk6-sse](https://github.com/phymbert/xk6-sse) | Test with Server-Sent Events (SSE) | 0.1.10, 0.1.11 | +| Extension | Description | Versions | +| --------------------------------------------------------------------------------- | ---------------------------------- | -------------- | +| [xk6-kafka](https://github.com/mostafa/xk6-kafka) | Load test Apache Kafka | 1.0.0 | +| [xk6-sql-driver-azuresql](https://github.com/grafana/xk6-sql-driver-azuresql) | SQL driver for AzureSQL | 0.1.0, 0.1.1 | +| [xk6-sql-driver-clickhouse](https://github.com/grafana/xk6-sql-driver-clickhouse) | SQL driver for Clickhouse | 0.1.0, 0.1.1 | +| [xk6-sql-driver-sqlserver](https://github.com/grafana/xk6-sql-driver-sqlserver) | SQL driver for SQLite3 | 0.1.0, 0.1.1 | +| [xk6-sse](https://github.com/phymbert/xk6-sse) | Test with Server-Sent Events (SSE) | 0.1.10, 0.1.11 | + +## Use extensions -## Require building a custom k6 binary +There are two ways to use extensions when running a k6 test script. -### Your own extensions +### Automatic extension resolution -If you have developed your own k6 extension or want to use an extension that's not available through automatic extension resolution, you'll need to build a custom k6 binary. This process involves using the xk6 tool to compile k6 with your desired extensions included. Custom binaries give you the flexibility to incorporate any extension from the k6 ecosystem. +These extensions can be used in your test without any additional configuration. They are automatically resolved and loaded by k6 when you [import them in your test script](https://grafana.com/docs/k6//extensions/run/#using-automatic-extension-loading). -Check out how to [build a custom k6 binary guide](https://grafana.com/docs/k6//extensions/run/#using-extensions-that-require-building-a-custom-k6-binary) to learn how to create your own k6 binary with custom extensions. +### Custom k6 binary -### More ecosystem extensions +If you have developed your own k6 extension or want to use an extension that's not available through automatic extension resolution, you have to build a custom k6 binary. The process involves using the xk6 tool to compile k6 with your desired extensions included. Custom binaries give you the flexibility to incorporate any extension from the k6 ecosystem. + +Refer to [build a custom k6 binary guide](https://grafana.com/docs/k6//extensions/run/#use-extensions-with-a-custom-k6-binary) to learn how to create your own k6 binary with custom extensions. {{< admonition type="caution" >}} -The extensions in this category are not maintained nor audited by Grafana Labs. +Many other extensions maintained by members of the k6 ecosystem are available in [GitHub](https://github.com/topics/xk6). These extensions aren't maintained nor audited by Grafana Labs. {{< /admonition >}} - -Many other extensions, maintained by members of the k6 ecosystem are available in [GitHub](https://github.com/topics/xk6). diff --git a/docs/sources/k6/v1.2.x/extensions/run/_index.md b/docs/sources/k6/v1.2.x/extensions/run/_index.md index dc8de23863..8f4ff7f406 100644 --- a/docs/sources/k6/v1.2.x/extensions/run/_index.md +++ b/docs/sources/k6/v1.2.x/extensions/run/_index.md @@ -1,17 +1,21 @@ --- title: 'Run a test with extensions' menuTitle: 'Run a test with extensions' -description: 'Run k6 with extensions to cover use cases not supported natively in the core.' +description: 'Learn how to run a k6 test with extensions.' weight: 03 --- # Run a test with extensions -As explained in the [Explore extensions](https://grafana.com/docs/k6//extensions/explore) page, there are extensions that can be used directly in your test script, and others that require building a custom k6 binary. +There are two different ways to run your k6 test script depending on the k6 extension you want to use: using the automatic extension resolution, or building a custom k6 binary. -## Using automatic extension resolution +## Before you begin -It is as easy as importing them. Example with [xk6-faker](https://github.com/grafana/xk6-faker): +- [Install k6](https://grafana.com/docs/k6//set-up/install-k6/) v1.2.0 or higher. + +## Use automatic extension resolution + +It's as easy as importing them. Example with [xk6-faker](https://github.com/grafana/xk6-faker): ```javascript import faker from 'k6/x/faker'; @@ -21,7 +25,7 @@ export default function () { } ``` -Then, you can run your script as usual, and k6 will automatically detect the extension and load it: +Then, you can run your script as usual, and k6 automatically detects the extension and loads it: ```sh k6 run script.js @@ -31,7 +35,6 @@ k6 run script.js To use community extensions you must have `K6_ENABLE_COMMUNITY_EXTENSIONS` set to `true`. - ```sh K6_ENABLE_COMMUNITY_EXTENSIONS=true k6 run test.js ``` @@ -41,23 +44,24 @@ K6_ENABLE_COMMUNITY_EXTENSIONS=true k6 run test.js ### Limitations - Only works with Official and Community extensions. -- Output extensions are not supported. -- Running scripts from stdin is not supported. -- Only files with extensions `.js`, `.ts` or `.tar` can be used. +- Output extensions aren't supported. +- Running scripts from stdin isn't supported. +- Only files with extensions `.js`, `.ts` or `.tar` can be used. -### How to disable this feature +### Disable automatic extension resolution You can disable this feature by setting the environment variable `K6_AUTO_EXTENSION_RESOLUTION` to `false`. If provided, the previous example -fails because k6 can't load the extension dynamically. +fails because k6 can't load the extension dynamically. + ```bash K6_AUTO_EXTENSION_RESOLUTION=false k6 run test.js ``` -## Using extensions that require building a custom k6 binary +## Use extensions with a custom k6 binary -To run other extensions (including ones you create), you need to build a custom k6 binary with [xk6](https://github.com/grafana/xk6/). +To run other extensions (including ones you create), you need to build a custom k6 binary with [xk6](https://github.com/grafana/xk6/). -You can do this locally with [Go](https://grafana.com/docs/k6//extensions/run/build-k6-binary-using-go/) or use the [xk6 Docker image](https://grafana.com/docs/k6//extensions/run/build-k6-binary-using-docker/). +You can do this locally with Go or use the xk6 Docker image. {{< code >}} @@ -74,4 +78,7 @@ docker run --rm -u "$(id -u):$(id -g)" -v "${PWD}:/xk6" grafana/xk6 build \ {{< /code >}} -
\ No newline at end of file +For more details, refer to: + +- [Build a k6 binary using Go](https://grafana.com/docs/k6//extensions/run/build-k6-binary-using-go/) +- [Build a k6 binary using Docker](https://grafana.com/docs/k6//extensions/run/build-k6-binary-using-docker/)