Merge branch 'main' into chore/http-requests-redirect

grafana · Jul 22, 2024 · 656e0ef · 656e0ef
2 parents ebd8cc9 + 5136b3d
commit 656e0ef
Show file tree

Hide file tree

Showing 1,001 changed files with 60,422 additions and 722 deletions.
diff --git a/.eslintignore b/.eslintignore
@@ -1,6 +1,7 @@
 .cache/
 public/
 node_modules/
+docs/sources/*/release-notes
 docs/sources/get-started/run-cloud-tests-from-the-CLI.md
 docs/sources/get-started/run-your-first-tests.md
 docs/sources/*/using-k6/metrics/create-custom-metrics.md

diff --git a/docs/sources/.eslintrc.js b/docs/sources/.eslintrc.js
@@ -41,5 +41,9 @@ module.exports = {
     __ITER: 'readonly',
     open: 'readonly',
     window: 'readonly',
+    setInterval: 'readonly',
+    clearInterval: 'readonly',
+    setTimeout: 'readonly',
+    clearTimeout: 'readonly',
   },
 };
diff --git a/docs/sources/_index.md b/docs/sources/_index.md
@@ -19,6 +19,7 @@ cascade:
   github_branch: main
   github_dir: /docs/sources
   replace_dir: docs/k6/
+  JSLIB_AWS_VERSION: 0.12.3
 versioned: true
 versioned_next: true
 ---
diff --git a/docs/sources/next/_index.md b/docs/sources/next/_index.md
@@ -3,103 +3,85 @@ aliases:
   - /docs/k6/
 description: 'The k6 documentation covers everything you need to know about k6 OSS, load testing, and performance testing.'
 menuTitle: Grafana k6
-title: Grafana k6 documentation
+title: Grafana k6
 weight: -10
+hero:
+  title: Grafana k6
+  level: 1
+  image: /media/docs/k6/GrafanaLogo_k6_icon.svg
+  width: 100
+  height: 100
+  description: Grafana k6 is an open-source, developer-friendly, and extensible load testing tool. k6 allows you to prevent performance issues and proactively improve reliability.
+cards:
+  title_class: pt-0 lh-1
+  items:
+    - title: Run your first k6 test
+      href: ./get-started/
+      description: Learn how to install the k6 CLI, run your first k6 test, and view metric results in the terminal.
+      height: 24
+    - title: Using k6
+      href: ./using-k6/
+      description: Learn about k6 options and concepts such as thresholds, metrics, lifecycle hooks, and more.
+      height: 24
+    - title: Testing guides
+      href: ./testing-guides/
+      description: Discover how to plan and define your performance testing strategy with these guides.
+      height: 24
+    - title: k6 JavaScript API
+      href: ./javascript-api/
+      description: Explore the k6 APIs through their documentation and examples.
+      height: 24
+    - title: Explore k6 extensions
+      href: ./extensions/
+      description: Have a particular testing need? Find k6 extensions that extend the native k6 functionality.
+      height: 24
+    - title: k6 script examples
+      href: ./extensions/
+      description: Learn how to script your tests with this list of common k6 examples.
+      height: 24
 ---
 
-# Grafana k6 documentation
+{{< docs/hero-simple key="hero" >}}
 
-This documentation will help you go from a total beginner to a seasoned k6 expert!
-
-## Get started
-
-<div class="nav-cards">
-    <a href={{< relref "./set-up/install-k6" >}} class="nav-cards__item nav-cards__item--guide">
-        <h4>🚀 Installation</h4>
-        <p>Get up and running in no-time, using either a package manager, standalone installer or the official Docker image.</p>
-    </a>
-    <a href={{< relref "./get-started/running-k6" >}} class="nav-cards__item nav-cards__item--guide">
-        <h4>🏎️💨 Running k6</h4>
-        <p>Write and execute your first load test locally using JavaScript and the k6 API, adding multiple virtual users, checks and ramping stages.</p>
-    </a>
-    <a href={{< relref "./get-started/results-output" >}} class="nav-cards__item nav-cards__item--guide">
-        <h4>⏱ Results output</h4>
-        <p>Learn how to leverage the results output to gain actionable insight about your application's performance.</p>
-    </a>
-</div>
-
-## What is k6?
-
-Grafana k6 is an open-source load testing tool that makes performance testing easy and productive for engineering teams.
-k6 is free, developer-centric, and extensible.
-
-Using k6, you can test the reliability and performance of your systems and catch performance regressions and problems earlier.
-k6 will help you to build resilient and performant applications that scale.
+---
 
-k6 is developed by [Grafana Labs](https://grafana.com/) and the community.
+## Overview
 
-Watch the video below to learn more about k6 and why it could be the missing puzzle in your Grafana stack.
+Using k6, you can test the reliability and performance of your application and infrastructure.
 
-{{< youtube id="1mtYVDA2_iQ" >}}
+k6 helps engineering teams prevent errors and SLO breaches, enabling them to build resilient and high-performing applications that scale.
 
-## Key features
+Engineering teams, including Developers, QA Engineers, SDETs, and SREs, commonly use k6 for:
 
-k6 is packed with features, which you can learn all about in the documentation.
-Key features include:
+- **Load and performance testing**
 
-- [CLI tool](https://grafana.com/docs/k6/<K6_VERSION>/using-k6/k6-options/how-to) with developer-friendly APIs.
-- Scripting in JavaScript ES2015/ES6 - with support for [local and remote modules](https://grafana.com/docs/k6/<K6_VERSION>/using-k6/modules)
-- [Checks](https://grafana.com/docs/k6/<K6_VERSION>/using-k6/checks) and [Thresholds](https://grafana.com/docs/k6/<K6_VERSION>/using-k6/thresholds) - for goal-oriented, automation-friendly load testing
+  k6 is optimized for minimal resource consumption and designed for running high-load performance tests such as
+  [spike](https://grafana.com/docs/k6/<K6_VERSION>/testing-guides/test-types/spike-testing), [stress](https://grafana.com/docs/k6/<K6_VERSION>/testing-guides/test-types/stress-testing), or [soak tests](https://grafana.com/docs/k6/<K6_VERSION>/testing-guides/test-types/soak-testing).
 
-## Use cases
+- **Browser performance testing**
 
-k6 users are typically Developers, QA Engineers, SDETs, and SREs.
-They use k6 for testing the performance and reliability of APIs, microservices, and websites.
-Common k6 use cases are:
+  Through the [k6 browser API](https://grafana.com/docs/k6/<K6_VERSION>/using-k6-browser), you can run browser-based performance tests and collect browser metrics to identify performance issues related to browsers. Additionally, you can mix browser tests with other performance tests to get a comprehensive view of your website's performance.
 
-- **Load testing**
+- **Performance and synthetic monitoring**
 
-  k6 is optimized for minimal resource consumption and designed for running high load tests
-  ([spike](https://grafana.com/docs/k6/<K6_VERSION>/testing-guides/test-types/spike-testing), [stress](https://grafana.com/docs/k6/<K6_VERSION>/testing-guides/test-types/stress-testing), [soak tests](https://grafana.com/docs/k6/<K6_VERSION>/testing-guides/test-types/soak-testing)).
+  You can schedule tests to run with minimal load very frequently, continuously validating the performance and availability of your production environment. For this, you can also use [Grafana Cloud Synthetic Monitoring](https://grafana.com/docs/grafana-cloud/testing/synthetic-monitoring/create-checks/checks/k6/), which supports running k6 scripts.
 
-- **Browser testing**
+- **Automation of performance tests**
 
-  Through [k6 browser](https://grafana.com/docs/k6/<K6_VERSION>/using-k6-browser), you can run browser-based performance testing and catch issues related to browsers only which can be skipped entirely from the protocol level.
+  k6 integrates seamlessly with CI/CD and automation tools, enabling engineering teams to [automate performance testing](https://grafana.com/docs/k6/<K6_VERSION>/testing-guides/automated-performance-testing/) as part of their development and release cycle.
 
 - **Chaos and resilience testing**
 
   You can use k6 to simulate traffic as part of your chaos experiments, trigger them from your k6 tests or inject different types of faults in Kubernetes with [xk6-disruptor](https://grafana.com/docs/k6/<K6_VERSION>/testing-guides/injecting-faults-with-xk6-disruptor/xk6-disruptor).
 
-- **Performance and synthetic monitoring**
+- **Infrastructure testing**
 
-  With k6, you can automate and schedule to trigger tests very frequently with a small load to continuously validate the performance and availability of your production environment. You can also use [Grafana Cloud Synthetic Monitoring](https://grafana.com/docs/grafana-cloud/testing/synthetic-monitoring/create-checks/checks/k6/) for a managed solution built specifically for synthetic monitoring that supports k6 test scripts.
+  With [k6 extensions](https://grafana.com/docs/k6/<K6_VERSION>/extensions/), you can add support to k6 for new protocols or use a particular client to directly test individual systems within your infrastructure.
 
-## Load Testing Manifesto
-
-Our load testing manifesto is the result of having spent years hip deep in the trenches, doing performance- and load testing.
-We’ve created it to be used as guidance, helping you in getting your performance testing on the right track!
-
-- [Simple testing is better than no testing](https://k6.io/our-beliefs/#simple-testing-is-better-than-no-testing)
-- [Load testing should be goal oriented](https://k6.io/our-beliefs/#load-testing-should-be-goal-oriented)
-- [Load testing by developers](https://k6.io/our-beliefs/#load-testing-by-developers)
-- [Developer experience is super important](https://k6.io/our-beliefs/#developer-experience-is-super-important)
-- [Load test in a pre-production environment](https://k6.io/our-beliefs/#load-test-in-a-pre-production-environment)
-
-## What k6 does not
-
-k6 is a high-performing load testing tool, scriptable in JavaScript. The architectural design to have these capabilities brings some trade-offs:
-
-- **Does not run natively in a browser**
-
-  By default, k6 does not render web pages the same way a browser does.
-  Browsers can consume significant system resources.
-  Skipping the browser allows running more load within a single machine.
-
-  However, with [k6 browser](https://grafana.com/docs/k6/<K6_VERSION>/using-k6-browser), you can interact with real browsers and collect frontend metrics as part of your k6 tests.
+Watch the video below to learn more about k6 and why it could be the missing puzzle in your Grafana stack.
 
-- **Does not run in NodeJS**
+{{< youtube id="1mtYVDA2_iQ" >}}
 
-  JavaScript is not generally well suited for high performance.
-  To achieve maximum performance, the tool itself is written in Go, embedding a JavaScript runtime allowing for easy test scripting.
+## Explore
 
-  If you want to import npm modules or libraries using NodeJS APIs, you can [bundle npm modules with webpack](https://grafana.com/docs/k6/<K6_VERSION>/using-k6/modules#bundling-node-modules) and import them in your tests.
+{{< card-grid key="cards" type="simple" >}}
diff --git a/docs/sources/next/examples/http-authentication.md b/docs/sources/next/examples/http-authentication.md
@@ -123,7 +123,10 @@ Here's an example script to demonstrate how to sign a request to fetch an object
 
 ```javascript
 import http from 'k6/http';
-import { AWSConfig, SignatureV4 } from 'https://jslib.k6.io/aws/0.12.3/signature.js';
+import {
+  AWSConfig,
+  SignatureV4,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/signature.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,

diff --git a/docs/sources/next/examples/tutorials/_index.md b/docs/sources/next/examples/tutorials/_index.md
@@ -12,7 +12,7 @@ weight: 26
 - [Swagger/OpenAPI integration](https://k6.io/blog/load-testing-your-api-with-swagger-openapi-and-k6)
 - [Schedule k6 tests with cron](https://k6.io/blog/performance-monitoring-with-cron-and-k6)
 - [Load test a GraphQL service](https://k6.io/blog/load-testing-graphql-with-k6)
-- [Use TypeScript in k6 scripts](https://github.com/k6io/template-typescript)
+- [Use TypeScript in k6 scripts](https://grafana.com/docs/k6/<K6_VERSION>/using-k6/javascript-typescript-compatibility-mode/)
 - [Debug using a Web Proxy](https://k6.io/blog/k6-load-testing-debugging-using-a-web-proxy/)
 - [Distributed k6 tests on K8s](https://k6.io/blog/running-distributed-tests-on-k8s/)
 - [Create a k6 extension](https://k6.io/blog/extending-k6-with-xk6)
diff --git a/docs/sources/next/get-started/_index.md b/docs/sources/next/get-started/_index.md
@@ -1,5 +1,5 @@
 ---
-weight: 01
+weight: 150
 title: Get started
 ---
 

diff --git a/docs/sources/next/get-started/resources.md b/docs/sources/next/get-started/resources.md
@@ -14,8 +14,7 @@ These resources help you write and run k6 tests in a safe environment and explor
 
 ## Learning
 
-- [Get started with k6 tutorial](https://grafana.com/docs/k6/<K6_VERSION>/examples/get-started-with-k6). The getting started tutorial provides some procedures for common real-life uses of k6 and does not require prior knowledge of k6 or JavaScript
-
+- [Get started with k6 tutorial](https://grafana.com/docs/k6/<K6_VERSION>/examples/get-started-with-k6). The getting started tutorial provides some procedures for common real-life uses of k6 and does not require prior knowledge of k6 or JavaScript.
 - [k6 Learn](https://github.com/grafana/k6-learn). A repository with a course and a ton of learning resources.
 - [k6 OSS workshop](https://github.com/grafana/k6-oss-workshop). A 2-3 hour k6 workshop with practical k6 examples using the QuickPizza demo app.
 - [k6 YouTube channel](https://www.youtube.com/playlist?list=PLDGkOdUX1UjrZM3lIHvFcKJxVgl2n4J65). Office hours, specific playlists, and other interesting videos from the community.
@@ -43,5 +42,5 @@ Note that these are shared testing environments - please avoid high-load tests.
 - [Kubernetes Operator](https://k6.io/blog/running-distributed-tests-on-k8s/). Distribute test execution across a Kubernetes cluster.
 - [xk6 extensions](https://grafana.com/docs/k6/<K6_VERSION>/extensions). Custom k6 binaries to support the tool you need.
 - [The browser recorder](https://grafana.com/docs/k6/<K6_VERSION>/using-k6/test-authoring/create-tests-from-recordings/using-the-browser-recorder). Make test scripts from browser sessions.
-- [k6 TypeScript template](https://github.com/grafana/k6-template-typescript)
+- [Use TypeScript in k6 scripts](https://grafana.com/docs/k6/<K6_VERSION>/using-k6/javascript-typescript-compatibility-mode/)
 - [Integrations](https://grafana.com/docs/k6/<K6_VERSION>/misc/integrations)
diff --git a/docs/sources/next/grafana-cloud-k6/_index.md b/docs/sources/next/grafana-cloud-k6/_index.md
@@ -0,0 +1,10 @@
+---
+weight: 1000
+title: Grafana Cloud k6
+---
+
+# Grafana Cloud k6
+
+Grafana Cloud k6 is a performance-testing application that's part of Grafana Cloud. It lets you leverage all of the k6 capabilities, while Grafana handles the infrastructure work of scaling servers, handling distributed load zones, and storing and aggregating metrics from your tests.
+
+Visit the [Grafana Cloud k6 documentation](https://grafana.com/docs/grafana-cloud/testing/k6/) for more information.
diff --git a/docs/sources/next/javascript-api/jslib/aws/EventBridgeClient/_index.md b/docs/sources/next/javascript-api/jslib/aws/EventBridgeClient/_index.md
@@ -34,7 +34,10 @@ EventBridgeClient methods will throw errors in case of failure.
 {{< code >}}
 
 ```javascript
-import { AWSConfig, EventBridgeClient } from 'https://jslib.k6.io/aws/0.12.3/event-bridge.js';
+import {
+  AWSConfig,
+  EventBridgeClient,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/event-bridge.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,

diff --git a/docs/sources/next/javascript-api/jslib/aws/EventBridgeClient/putEvents.md b/docs/sources/next/javascript-api/jslib/aws/EventBridgeClient/putEvents.md
@@ -44,7 +44,10 @@ weight: 10
 {{< code >}}
 
 ```javascript
-import { AWSConfig, EventBridgeClient } from 'https://jslib.k6.io/aws/0.12.3/event-bridge.js';
+import {
+  AWSConfig,
+  EventBridgeClient,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/event-bridge.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,

diff --git a/docs/sources/next/javascript-api/jslib/aws/KMSClient/KMSDataKey.md b/docs/sources/next/javascript-api/jslib/aws/KMSClient/KMSDataKey.md
@@ -25,7 +25,10 @@ For instance, the [`generateDataKey`](https://grafana.com/docs/k6/<K6_VERSION>/j
 ```javascript
 import exec from 'k6/execution';
 
-import { AWSConfig, KMSClient } from 'https://jslib.k6.io/aws/0.12.3/kms.js';
+import {
+  AWSConfig,
+  KMSClient,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/kms.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,

diff --git a/docs/sources/next/javascript-api/jslib/aws/KMSClient/KMSKey.md b/docs/sources/next/javascript-api/jslib/aws/KMSClient/KMSKey.md
@@ -22,7 +22,10 @@ weight: 20
 ```javascript
 import exec from 'k6/execution';
 
-import { AWSConfig, KMSClient } from 'https://jslib.k6.io/aws/0.12.3/kms.js';
+import {
+  AWSConfig,
+  KMSClient,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/kms.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,

diff --git a/docs/sources/next/javascript-api/jslib/aws/KMSClient/_index.md b/docs/sources/next/javascript-api/jslib/aws/KMSClient/_index.md
@@ -39,7 +39,10 @@ Both the dedicated `kms.js` jslib bundle and the all-encompassing `aws.js` bundl
 ```javascript
 import { textSummary } from 'https://jslib.k6.io/k6-summary/0.0.2/index.js';
 
-import { AWSConfig, KMSClient } from 'https://jslib.k6.io/aws/0.12.3/kms.js';
+import {
+  AWSConfig,
+  KMSClient,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/kms.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,

diff --git a/docs/sources/next/javascript-api/jslib/aws/KMSClient/generateDataKey.md b/docs/sources/next/javascript-api/jslib/aws/KMSClient/generateDataKey.md
@@ -30,7 +30,10 @@ weight: 10
 ```javascript
 import exec from 'k6/execution';
 
-import { AWSConfig, KMSClient } from 'https://jslib.k6.io/aws/0.12.3/kms.js';
+import {
+  AWSConfig,
+  KMSClient,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/kms.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,

diff --git a/docs/sources/next/javascript-api/jslib/aws/LambdaClient/_index.md b/docs/sources/next/javascript-api/jslib/aws/LambdaClient/_index.md
@@ -33,7 +33,10 @@ Both the dedicated `lambda.js` jslib bundle and the all-encompassing `aws.js` bu
 {{< code >}}
 
 ```javascript
-import { AWSConfig, LambdaClient } from 'https://jslib.k6.io/aws/0.12.3/lambda.js';
+import {
+  AWSConfig,
+  LambdaClient,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/lambda.js';
 import { check } from 'k6';
 
 const awsConfig = new AWSConfig({

diff --git a/docs/sources/next/javascript-api/jslib/aws/LambdaClient/invoke.md b/docs/sources/next/javascript-api/jslib/aws/LambdaClient/invoke.md
@@ -51,7 +51,10 @@ InvocationResponse is an object that represents the response of an invocation. I
 {{< code >}}
 
 ```javascript
-import { AWSConfig, LambdaClient } from 'https://jslib.k6.io/aws/0.12.3/lambda.js';
+import {
+  AWSConfig,
+  LambdaClient,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/lambda.js';
 import { check } from 'k6';
 
 const awsConfig = new AWSConfig({

diff --git a/docs/sources/next/javascript-api/jslib/aws/S3Client/Object.md b/docs/sources/next/javascript-api/jslib/aws/S3Client/Object.md
@@ -30,7 +30,7 @@ import {
   // listBuckets,
   AWSConfig,
   S3Client,
-} from 'https://jslib.k6.io/aws/0.12.3/s3.js';
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/s3.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,

diff --git a/docs/sources/next/javascript-api/jslib/aws/S3Client/S3MultipartUpload.md b/docs/sources/next/javascript-api/jslib/aws/S3Client/S3MultipartUpload.md
@@ -18,7 +18,10 @@ S3MultipartUpload is returned by the [`createMultipartUpload(bucketName, objectK
 {{< code >}}
 
 ```javascript
-import { AWSConfig, S3Client } from 'https://jslib.k6.io/aws/0.12.3/s3.js';
+import {
+  AWSConfig,
+  S3Client,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/s3.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,

diff --git a/docs/sources/next/javascript-api/jslib/aws/S3Client/S3Part.md b/docs/sources/next/javascript-api/jslib/aws/S3Client/S3Part.md
@@ -23,7 +23,10 @@ S3Part is returned by the [`uploadPart(bucketName, objectKey, uploadId, partNumb
 import crypto from 'k6/crypto';
 import exec from 'k6/execution';
 
-import { AWSConfig, S3Client } from 'https://jslib.k6.io/aws/0.12.3/s3.js';
+import {
+  AWSConfig,
+  S3Client,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/s3.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,

diff --git a/docs/sources/next/javascript-api/jslib/aws/S3Client/_index.md b/docs/sources/next/javascript-api/jslib/aws/S3Client/_index.md
@@ -49,7 +49,10 @@ import { check } from 'k6';
 import exec from 'k6/execution';
 import http from 'k6/http';
 
-import { AWSConfig, S3Client } from 'https://jslib.k6.io/aws/0.12.3/s3.js';
+import {
+  AWSConfig,
+  S3Client,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/s3.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,
@@ -111,7 +114,10 @@ export async function handleSummary(data) {
 import crypto from 'k6/crypto';
 import exec from 'k6/execution';
 
-import { AWSConfig, S3Client } from 'https://jslib.k6.io/aws/0.12.3/s3.js';
+import {
+  AWSConfig,
+  S3Client,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/s3.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,