Skip to content

Commit c3595af

Browse files
heitortsergentheitortsergent
authored
Updates to Extensions section (#2034)
* Move Explanation pages into Create a new extension * Update Extensions index shortcode to show descriptions * Remove "new" from page title * Update titles * Edits to Run a test with extensions * Edits to explore and extensions index pages * Remove use cases section * Apply to v1.2.x
1 parent 7e4eb5a commit c3595af

20 files changed

+154
-158
lines changed

‎docs/sources/k6/next/extensions/_index.md

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,10 @@ weight: 700
66

77
# Extensions
88

9-
<!-- TODO: Add content -->
9+
With k6 extensions, you can extend the core k6 functionality with new features to support your specific reliability-testing needs.
1010

11-
{{< section >}}
11+
k6 supports three types of extensions:
1212

13+
- **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.
14+
- **Output extensions** send metrics to a custom file format or service. They can add custom processing and dispatching methods.
15+
- **Secret Source extensions** provide secrets to your tests.

‎docs/sources/k6/next/extensions/create/_index.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
---
2-
title: 'Create a new extension'
3-
menuTitle: 'Create a new extension'
4-
description: 'Creating k6 extensions does not have to be a daunting task, but there are some prerequisites to succeed.'
2+
title: 'Create a k6 extension'
3+
menuTitle: 'Create an extension'
4+
description: 'Learn how to create a k6 extension.'
55
weight: 04
66
---
77

8-
# Create a new k6 extension
8+
# Create a k6 extension
99

1010
If you find a gap in your testing process that no k6 extension can fix,
1111
consider building your own extension. Use the tutorials below to get started.

‎docs/sources/k6/v1.2.x/extensions/explanations/extensions-registry.md renamed to ‎docs/sources/k6/next/extensions/create/extensions-registry.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: About the Extensions Registry
33
description: Reasons for the registry and what is required to be included.
4-
weight: 01
4+
weight: 600
55
---
66

77
# About the Extensions Registry
@@ -18,7 +18,7 @@ To ensure quality, we need a well-maintained, curated listing of extensions.
1818
Our pledge to the community is to make our best attempt to ensure the listed projects meet certain standards.
1919
While we cannot guarantee the quality of community-provided extensions, we _can_ aid the evaluation by requiring certain consistencies.
2020

21-
## Registry Requirements
21+
## Registry requirements
2222

2323
At minimum, each source code repository must have the following:
2424

@@ -55,7 +55,7 @@ At minimum, each source code repository must have the following:
5555
For example, if latest version of k6 is `v0.100`, the extension must build with at least version `v0.98`.
5656
Be sure to also match the version of Go as determined by the version of k6.
5757

58-
## Naming Conventions
58+
## Naming conventions
5959

6060
Some extensions may be very specific, where others are more general.
6161
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.
7676

7777
{{< /admonition >}}
7878

79-
## Potential for De-listing
79+
## Potential for de-listing
8080

8181
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.
8282
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.

‎docs/sources/k6/v1.2.x/extensions/explanations/go-js-bridge.md renamed to ‎docs/sources/k6/next/extensions/create/go-js-bridge.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: About the Go-to-JS bridge
33
description: Technical details about how JavaScript works in the sobek engine.
4-
weight: 02
4+
weight: 700
55
---
66

77
# About the Go-to-JS bridge

‎docs/sources/k6/next/extensions/create/javascript-extensions.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
---
2-
title: 'JavaScript Extensions'
2+
title: 'JavaScript extensions'
33
description: 'Follow these steps to build a JS extension for k6.'
44
weight: 300
55
---
66

7-
# JavaScript Extensions
7+
# JavaScript extensions
88

99
Take advantage of Go's speed, power, and efficiency while providing the flexibility of using JavaScript APIs
1010
within your test scripts.

‎docs/sources/k6/next/extensions/create/output-extensions.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
---
2-
title: 'Output Extensions'
2+
title: 'Output extensions'
33
description: 'Follow these steps to build an output extension for k6.'
44
weight: 400
55
---
66

7-
# Output Extensions
7+
# Output extensions
88

99
k6 provides many [metrics](https://grafana.com/docs/k6/<K6_VERSION>/using-k6/metrics) and [output formats](https://grafana.com/docs/k6/<K6_VERSION>/results-output/), but it cannot directly support all possibilities.
1010
To store or alter metrics captured during an active k6 test,

‎docs/sources/k6/next/extensions/create/secret-source_extensions.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
---
2-
title: 'Secret source Extensions'
2+
title: 'Secret source extensions'
33
description: 'Follow these steps to build an secret source extension for k6.'
44
weight: 500
55
---
66

7-
# Secret Source Extensions
7+
# Secret Source extensions
88

99
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.
1010

‎docs/sources/k6/next/extensions/explanations/_index.md

Lines changed: 0 additions & 10 deletions
This file was deleted.

‎docs/sources/k6/next/extensions/explore.md

Lines changed: 35 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,65 @@
11
---
22
title: 'Explore extensions'
33
menuTitle: 'Explore extensions'
4-
description: 'Explore the k6 extension ecosystem to find extensions that meet your requirements.'
4+
description: 'Explore the k6 extension ecosystem to find extensions that fit your use cases.'
55
weight: 01
66
---
77

88
# Explore extensions
99

10-
## Supported by automatic extension resolution
10+
Extensions can be used to extend the core k6 features to fit your performance-testing use cases. There are two main categories of extensions:
1111

12-
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/<K6_VERSION>/extensions/run/#using-automatic-extension-loading).
13-
14-
We have two categories of extensions:
15-
16-
| Category | Maintainer | Audited | Cloud support |
17-
| ------------- | ----------------------------------- | ------- | ------------- |
18-
| **Official** | Grafana Labs | ✅ Yes | ✅ Yes |
19-
| **Community** | Community | ✅ Yes | ⚠️ Partial\* |
12+
| Category | Maintainer | Audited | Cloud support |
13+
| ------------- | ------------ | ------- | ------------- |
14+
| **Official** | Grafana Labs | ✅ Yes | ✅ Yes |
15+
| **Community** | Community | ✅ Yes | ⚠️ Partial\* |
2016

21-
\* *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.
17+
\* _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.
2218

23-
### Official extensions
19+
## Official extensions
2420

25-
| Extension | Description | Versions |
26-
| --------- | ----------- | -------- |
27-
| [xk6-client-prometheus-remote](https://github.com/grafana/xk6-client-prometheus-remote) | Test Prometheus Remote Write-compatible endpoints | 0.3.2 |
28-
| [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 |
29-
| [xk6-loki](https://github.com/grafana/xk6-loki) | Test Grafana Loki log ingestion endpoints | 1.0.0, 1.0.1 |
21+
| Extension | Description | Versions |
22+
| --------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------- |
23+
| [xk6-client-prometheus-remote](https://github.com/grafana/xk6-client-prometheus-remote) | Test Prometheus Remote Write-compatible endpoints | 0.3.2 |
24+
| [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 |
25+
| [xk6-loki](https://github.com/grafana/xk6-loki) | Test Grafana Loki log ingestion endpoints | 1.0.0, 1.0.1 |
3026
| [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 |
31-
| [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 |
32-
| [xk6-sql-driver-postgres](https://github.com/grafana/xk6-sql-driver-postgres) | SQL driver for Postgres | 0.1.0, 0.1.1 |
33-
| [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 |
27+
| [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 |
28+
| [xk6-sql-driver-postgres](https://github.com/grafana/xk6-sql-driver-postgres) | SQL driver for Postgres | 0.1.0, 0.1.1 |
29+
| [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 |
3430

35-
### Community extensions
31+
## Community extensions
3632

3733
{{< admonition type="note" >}}
3834

39-
We are working on process for community folks to submit their extensions to be included here.
35+
We're working on a process for community folks to submit their extensions.
4036

4137
{{< /admonition >}}
4238

43-
| Extension | Description | Versions |
44-
| --------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------- |
45-
| [xk6-kafka](https://github.com/mostafa/xk6-kafka) | Load test Apache Kafka | 1.0.0 |
46-
| [xk6-sql-driver-azuresql](https://github.com/grafana/xk6-sql-driver-azuresql) | SQL driver for AzureSQL | 0.1.0, 0.1.1 |
47-
| [xk6-sql-driver-clickhouse](https://github.com/grafana/xk6-sql-driver-clickhouse) | SQL driver for Clickhouse | 0.1.0, 0.1.1 |
48-
| [xk6-sql-driver-sqlserver](https://github.com/grafana/xk6-sql-driver-sqlserver) | SQL driver for SQLite3 | 0.1.0, 0.1.1 |
49-
| [xk6-sse](https://github.com/phymbert/xk6-sse) | Test with Server-Sent Events (SSE) | 0.1.10, 0.1.11 |
39+
| Extension | Description | Versions |
40+
| --------------------------------------------------------------------------------- | ---------------------------------- | -------------- |
41+
| [xk6-kafka](https://github.com/mostafa/xk6-kafka) | Load test Apache Kafka | 1.0.0 |
42+
| [xk6-sql-driver-azuresql](https://github.com/grafana/xk6-sql-driver-azuresql) | SQL driver for AzureSQL | 0.1.0, 0.1.1 |
43+
| [xk6-sql-driver-clickhouse](https://github.com/grafana/xk6-sql-driver-clickhouse) | SQL driver for Clickhouse | 0.1.0, 0.1.1 |
44+
| [xk6-sql-driver-sqlserver](https://github.com/grafana/xk6-sql-driver-sqlserver) | SQL driver for SQLite3 | 0.1.0, 0.1.1 |
45+
| [xk6-sse](https://github.com/phymbert/xk6-sse) | Test with Server-Sent Events (SSE) | 0.1.10, 0.1.11 |
46+
47+
## Use extensions
5048

51-
## Require building a custom k6 binary
49+
There are two ways to use extensions when running a k6 test script.
5250

53-
### Your own extensions
51+
### Automatic extension resolution
5452

55-
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.
53+
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/<K6_VERSION>/extensions/run/#using-automatic-extension-loading).
5654

57-
Check out how to [build a custom k6 binary guide](https://grafana.com/docs/k6/<K6_VERSION>/extensions/run/#using-extensions-that-require-building-a-custom-k6-binary) to learn how to create your own k6 binary with custom extensions.
55+
### Custom k6 binary
5856

59-
### More ecosystem extensions
57+
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.
58+
59+
Refer to [build a custom k6 binary guide](https://grafana.com/docs/k6/<K6_VERSION>/extensions/run/#use-extensions-with-a-custom-k6-binary) to learn how to create your own k6 binary with custom extensions.
6060

6161
{{< admonition type="caution" >}}
6262

63-
The extensions in this category are not maintained nor audited by Grafana Labs.
63+
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.
6464

6565
{{< /admonition >}}
66-
67-
Many other extensions, maintained by members of the k6 ecosystem are available in [GitHub](https://github.com/topics/xk6).

‎docs/sources/k6/next/extensions/run/_index.md

Lines changed: 22 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,21 @@
11
---
22
title: 'Run a test with extensions'
33
menuTitle: 'Run a test with extensions'
4-
description: 'Run k6 with extensions to cover use cases not supported natively in the core.'
4+
description: 'Learn how to run a k6 test with extensions.'
55
weight: 03
66
---
77

88
# Run a test with extensions
99

10-
As explained in the [Explore extensions](https://grafana.com/docs/k6/<K6_VERSION>/extensions/explore) page, there are extensions that can be used directly in your test script, and others that require building a custom k6 binary.
10+
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.
1111

12-
## Using automatic extension resolution
12+
## Before you begin
1313

14-
It is as easy as importing them. Example with [xk6-faker](https://github.com/grafana/xk6-faker):
14+
- [Install k6](https://grafana.com/docs/k6/<K6_VERSION>/set-up/install-k6/) v1.2.0 or higher.
15+
16+
## Use automatic extension resolution
17+
18+
It's as easy as importing them. Example with [xk6-faker](https://github.com/grafana/xk6-faker):
1519

1620
```javascript
1721
import faker from 'k6/x/faker';
@@ -21,7 +25,7 @@ export default function () {
2125
}
2226
```
2327

24-
Then, you can run your script as usual, and k6 will automatically detect the extension and load it:
28+
Then, you can run your script as usual, and k6 automatically detects the extension and loads it:
2529

2630
```sh
2731
k6 run script.js
@@ -31,7 +35,6 @@ k6 run script.js
3135

3236
To use community extensions you must have `K6_ENABLE_COMMUNITY_EXTENSIONS` set to `true`.
3337

34-
3538
```sh
3639
K6_ENABLE_COMMUNITY_EXTENSIONS=true k6 run test.js
3740
```
@@ -41,23 +44,24 @@ K6_ENABLE_COMMUNITY_EXTENSIONS=true k6 run test.js
4144
### Limitations
4245

4346
- Only works with Official and Community extensions.
44-
- Output extensions are not supported.
45-
- Running scripts from stdin is not supported.
46-
- Only files with extensions `.js`, `.ts` or `.tar` can be used.
47+
- Output extensions aren't supported.
48+
- Running scripts from stdin isn't supported.
49+
- Only files with extensions `.js`, `.ts` or `.tar` can be used.
4750

48-
### How to disable this feature
51+
### Disable automatic extension resolution
4952

5053
You can disable this feature by setting the environment variable `K6_AUTO_EXTENSION_RESOLUTION` to `false`. If provided, the previous example
51-
fails because k6 can't load the extension dynamically.
54+
fails because k6 can't load the extension dynamically.
55+
5256
```bash
5357
K6_AUTO_EXTENSION_RESOLUTION=false k6 run test.js
5458
```
5559

56-
## Using extensions that require building a custom k6 binary
60+
## Use extensions with a custom k6 binary
5761

58-
To run other extensions (including ones you create), you need to build a custom k6 binary with [xk6](https://github.com/grafana/xk6/).
62+
To run other extensions (including ones you create), you need to build a custom k6 binary with [xk6](https://github.com/grafana/xk6/).
5963

60-
You can do this locally with [Go](https://grafana.com/docs/k6/<K6_VERSION>/extensions/run/build-k6-binary-using-go/) or use the [xk6 Docker image](https://grafana.com/docs/k6/<K6_VERSION>/extensions/run/build-k6-binary-using-docker/).
64+
You can do this locally with Go or use the xk6 Docker image.
6165

6266
{{< code >}}
6367

@@ -74,4 +78,7 @@ docker run --rm -u "$(id -u):$(id -g)" -v "${PWD}:/xk6" grafana/xk6 build \
7478

7579
{{< /code >}}
7680

77-
<br/>
81+
For more details, refer to:
82+
83+
- [Build a k6 binary using Go](https://grafana.com/docs/k6/<K6_VERSION>/extensions/run/build-k6-binary-using-go/)
84+
- [Build a k6 binary using Docker](https://grafana.com/docs/k6/<K6_VERSION>/extensions/run/build-k6-binary-using-docker/)

0 commit comments

Comments
 (0)