k6 browser: Display Metrics and new Options page (#1667)

* v0.52.x: New `Browser options` page * Display the browser metric table on the `Browser metrics` docs * Update `Browser options` * Port changes to `next` * Update the latest `K6_BROWSER_TIMEOUT` description * Apply suggestions from code review * Apply to v0.52.x * Update code sample for browser options --------- Co-authored-by: Heitor Tashiro Sergent <[email protected]>
grafana · Jul 25, 2024 · c4de131 · c4de131
1 parent a6b91e0
commit c4de131
Show file tree

Hide file tree

Showing 22 changed files with 396 additions and 274 deletions.
diff --git a/docs/sources/next/javascript-api/k6-browser/_index.md b/docs/sources/next/javascript-api/k6-browser/_index.md
diff --git a/docs/sources/next/shared/browser/env-var-options.md b/docs/sources/next/shared/browser/env-var-options.md
@@ -0,0 +1,45 @@
+---
+title: browser/options
+---
+
+| Environment Variable           | Description                                                                                                                                                                                                                                                                                                                                                              |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| K6_BROWSER_ARGS                | Extra command line arguments to include when launching browser process. See [this link](https://peter.sh/experiments/chromium-command-line-switches/) for a list of Chromium arguments. Note that arguments should not start with `--` (see the command example below).                                                                                                  |
+| K6_BROWSER_DEBUG               | All CDP messages and internal fine grained logs will be logged if set to `true`.                                                                                                                                                                                                                                                                                         |
+| K6_BROWSER_EXECUTABLE_PATH     | Override search for browser executable in favor of specified absolute path.                                                                                                                                                                                                                                                                                              |
+| K6_BROWSER_HEADLESS            | Show browser GUI or not. `true` by default.                                                                                                                                                                                                                                                                                                                              |
+| K6_BROWSER_IGNORE_DEFAULT_ARGS | Ignore any of the [default arguments](https://grafana.com/docs/k6/<K6_VERSION>/using-k6-browser/options/#default-arguments) included when launching a browser process.                                                                                                                                                                                                   |
+| K6_BROWSER_TIMEOUT             | Default timeout for initializing the connection to the browser instance. `'30s'` if not set.                                                                                                                                                                                                                                                                             |
+| K6_BROWSER_TRACES_METADATA     | Sets additional _key-value_ metadata that is included as attributes in every span generated from browser module traces. Example: `K6_BROWSER_TRACES_METADATA=attr1=val1,attr2=val2`. This only applies if traces generation is enabled, refer to [Traces output](https://grafana.com/docs/k6/<K6_VERSION>/using-k6/k6-options/reference#traces-output) for more details. |
+
+The following command passes the browser options as environment variables to launch a headful browser with custom arguments.
+
+{{< code >}}
+
+```bash
+$ K6_BROWSER_HEADLESS=false K6_BROWSER_ARGS='show-property-changed-rects' k6 run script.js
+```
+
+```docker
+# WARNING!
+# The grafana/k6:master-with-browser image launches a Chrome browser by setting the
+# 'no-sandbox' argument. Only use it with trustworthy websites.
+#
+# As an alternative, you can use a Docker SECCOMP profile instead, and overwrite the
+# Chrome arguments to not use 'no-sandbox' such as:
+# docker container run --rm -i -e K6_BROWSER_ARGS='' --security-opt seccomp=$(pwd)/chrome.json grafana/k6:master-with-browser run - <script.js
+#
+# You can find an example of a hardened SECCOMP profile in:
+# https://raw.githubusercontent.com/jfrazelle/dotfiles/master/etc/docker/seccomp/chrome.json.
+docker run --rm -i -e K6_BROWSER_HEADLESS=false -e K6_BROWSER_ARGS='show-property-changed-rects' grafana/k6:master-with-browser run - <script.js
+```
+
+```windows
+C:\k6> set "K6_BROWSER_HEADLESS=false" && set "K6_BROWSER_ARGS='show-property-changed-rects' " && k6 run script.js
+```
+
+```windows-powershell
+PS C:\k6> $env:K6_BROWSER_HEADLESS="false" ; $env:K6_BROWSER_ARGS='show-property-changed-rects' ; k6 run script.js
+```
+
+{{< /code >}}
diff --git a/docs/sources/next/shared/browser/web-vital-core-metrics.md b/docs/sources/next/shared/browser/web-vital-core-metrics.md
@@ -0,0 +1,13 @@
+---
+title: browser/webvital-core-metrics
+---
+
+<!-- vale off -->
+
+| Metric name           | Description                                                                                                                                                                                                                            |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| browser_web_vital_cls | Measures the visual stability on a webpage by quantifying the amount of unexpected layout shift of visible page content. Refer to [Cumulative Layout Shift](https://web.dev/cls/) for more information.                                |
+| browser_web_vital_fid | Measures the responsiveness of a web page by quantifying the delay between a user’s first interaction, such as clicking a button, and the browser’s response. Refer to [First Input Delay](https://web.dev/fid/) for more information. |
+| browser_web_vital_lcp | Measures the time it takes for the largest content element on a page to become visible. Refer to [Largest Contentful Paint](https://web.dev/lcp/) for more information.                                                                |
+
+<!-- vale on -->
diff --git a/docs/sources/next/shared/browser/web-vital-other-metrics.md b/docs/sources/next/shared/browser/web-vital-other-metrics.md
@@ -0,0 +1,13 @@
+---
+title: browser/webvital-other-metrics
+---
+
+<!-- vale off -->
+
+| Metric name            | Description                                                                                                                                                                                                   |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| browser_web_vital_fcp  | Measures the time it takes for the browser to render the first DOM element on the page, whether that's a text, image or header. Refer to [First Contentful Paint](https://web.dev/fcp/) for more information. |
+| browser_web_vital_inp  | An experimental metric that measures a page's responsiveness. Refer to [Interaction to Next Paint](https://web.dev/inp/) for more information.                                                                |
+| browser_web_vital_ttfb | Measures the time it takes between the browser request and the start of the response from a server. Refer to [Time to First Byte](https://web.dev/ttfb/) for more information.                                |
+
+<!-- vale on -->
diff --git a/docs/sources/next/using-k6-browser/metrics.md b/docs/sources/next/using-k6-browser/metrics.md
@@ -11,12 +11,11 @@ Follow along to learn about:
 - Google's Core Web Vitals and why they are important
 - How to analyze the browser metrics output
 - How to set thresholds for your browser metrics
+- How to use the Performance API to measure web performance.
 
 ## Google's Core Web Vitals
 
 The k6 browser module emits metrics based on the [Core Web Vitals](https://web.dev/vitals/#core-web-vitals).
-This section provides some conceptual background about the core vitals.
-To review the complete list of browser metrics, refer to the section in the [Metrics reference](https://grafana.com/docs/k6/<K6_VERSION>/using-k6/metrics/reference#browser).
 
 Google introduced these metrics to provided unified signals to assess user experience on the web.
 The vitals are composed of three important metrics to help user experience when using your web application.
@@ -32,6 +31,18 @@ The Core Web Vitals are one of [Google's Page Experience Signals](https://develo
 Existing browser measures, such as `Load` and `DOMContentLoaded` times, no longer accurately reflect user experience very well.
 Relying on these load events does not give the correct metric to analyze critical performance bottlenecks that your page might have. Google's Web Vitals is a better measure of your page performance and its user experience.
 
+## Browser metrics
+
+The following Core Web Vital metrics are collected when using the k6 browser module.
+
+{{< docs/shared source="k6" lookup="browser/web-vital-core-metrics.md" version="<K6_VERSION>" >}}
+
+Additionally, k6 also collects other Web Vital metrics.
+
+{{< docs/shared source="k6" lookup="browser/web-vital-other-metrics.md" version="<K6_VERSION>" >}}
+
+To review the complete list of k6 metrics, refer to the [Metrics reference](https://grafana.com/docs/k6/<K6_VERSION>/using-k6/metrics/reference).
+
 ## Understanding the browser metrics output
 
 When a browser test finishes, k6 reports a top-level overview of the aggregated browser metrics output.
@@ -129,31 +140,24 @@ export default async function () {
   const page = await browser.newPage();
 
   try {
-    await page.goto("https://test.k6.io/browser.php");
-    await page.evaluate(() => window.performance.mark("page-visit"));
+    await page.goto('https://test.k6.io/browser.php');
+    await page.evaluate(() => window.performance.mark('page-visit'));
 
-    await page.locator("#checkbox1").check();
+    await page.locator('#checkbox1').check();
     await page.locator('#counter-button').click();
-    await page.locator("#text1").fill("This is a test");
+    await page.locator('#text1').fill('This is a test');
 
-    await page.evaluate(() => window.performance.mark("action-completed"));
+    await page.evaluate(() => window.performance.mark('action-completed'));
 
     // Get time difference between visiting the page and completing the actions
     await page.evaluate(() =>
-      window.performance.measure(
-        "total-action-time",
-        "page-visit",
-        "action-completed"
-      )
+      window.performance.measure('total-action-time', 'page-visit', 'action-completed')
     );
 
     const totalActionTime = await page.evaluate(
       () =>
-        JSON.parse(
-          JSON.stringify(
-            window.performance.getEntriesByName("total-action-time")
-          )
-        )[0].duration
+        JSON.parse(JSON.stringify(window.performance.getEntriesByName('total-action-time')))[0]
+          .duration
     );
 
     myTrend.add(totalActionTime);

diff --git a/docs/sources/next/using-k6-browser/migrating-to-k6-v0-52.md b/docs/sources/next/using-k6-browser/migrating-to-k6-v0-52.md
@@ -3,7 +3,7 @@ aliases:
   - ./migrating-to-k6-v0-46/ # docs/k6/<K6_VERSION>/using-k6-browser/migrating-to-k6-v0-46
 title: 'Migrating browser scripts to k6 v0.52'
 description: 'A migration guide to ease the process of transitioning to the new k6 browser module version bundled with k6 v0.52'
-weight: 04
+weight: 05
 ---
 
 # Migrating browser scripts to k6 v0.52