Merge pull request #1345 from grafana/update-k6-browser-docs

docs: update k6 browser documentation

Author: mdcruz

src/data/markdown/translated-guides/en/03 Using k6 browser/01 Overview.md

@@ -13,7 +13,7 @@ This module aims to provide rough compatibility with the Playwright API, so you
 
 <Blockquote mod="note" title="">
 
-To work with the browser module, make sure you are using the latest [k6 version](https://github.com/grafana/k6/releases).
+To work with the browser module, make sure you are using the latest [k6 version](https://github.com/grafana/k6/releases), and install a Chromium-based browser on your machine (such as [Google Chrome](https://www.google.com/chrome/)).
 
 </Blockquote>
 

src/data/markdown/translated-guides/en/03 Using k6 browser/02 Running browser tests.md

@@ -50,7 +50,7 @@ Note that providing an `executor` and setting the `browser` scenario option's `t
 
     try {
       await page.goto('https://test.k6.io/');
-      page.screenshot({ path: 'screenshot.png' });
+      page.screenshot({ path: 'screenshots/screenshot.png' });
     } finally {
       page.close();
     }
@@ -90,7 +90,7 @@ $ k6 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 grafana/k6:master-with-browser run - <script.js
+docker run --rm -i -v $(pwd):/home/k6/screenshots grafana/k6:master-with-browser run - <script.js
 ```
 
 ```bash
@@ -122,7 +122,7 @@ $ K6_BROWSER_HEADLESS=false k6 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 grafana/k6:master-with-browser run - <script.js
+docker run --rm -i -v $(pwd):/home/k6/screenshots -e K6_BROWSER_HEADLESS=false grafana/k6:master-with-browser run - <script.js
 ```
 
 ```bash
@@ -184,7 +184,7 @@ export default async function () {
     page.locator('input[name="login"]').type('admin');
     page.locator('input[name="password"]').type('123');
 
-    page.screenshot({ path: 'screenshot.png' });
+    page.screenshot({ path: 'screenshots/screenshot.png' });
   } finally {
     page.close();
   }

src/data/markdown/translated-guides/en/03 Using k6 browser/04 Migrating to k6 v0-46.md

@@ -112,6 +112,8 @@ Now, all that is needed is to specify the `browser.type` within the [scenario op
 
 With the removal of the `chromium.launch()` and `chromium.connect()` methods, setting browsers options is now done by using environment variables. For more information, refer to [Browser Module Options](/javascript-api/k6-experimental/browser/#browser-module-options).
 
+### Launching a browser
+
 Before:
 
 <CodeGroup lineNumbers={[true]}>
@@ -161,6 +163,56 @@ PS C:\k6> $env:K6_BROWSER_HEADLESS="false" ; $env:K6_BROWSER_TIMEOUT='60s' ; k6
 
 </CodeGroup>
 
+### Connecting to a remote browser
+
+Before:
+
+<CodeGroup lineNumbers={[true]}>
+
+<!-- eslint-skip -->
+
+```javascript
+export default async function () {
+    const remoteURL = 'REMOTE_URL'
+    const browser = chromium.connect(remoteURL);
+    const page = browser.newPage();
+}
+```
+
+</CodeGroup>
+
+After:
+
+<CodeGroup labels={["Bash", "Docker", "Windows: CMD", "Windows: PowerShell"]} lineNumbers={[false]}>
+
+```bash
+$ K6_BROWSER_WS_URL='REMOTE_URL' k6 run script.js
+```
+
+```bash
+# 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_WS_URL='REMOTE_URL' grafana/k6:master-with-browser run - <script.js
+```
+
+```bash
+C:\k6> set "K6_BROWSER_WS_URL='REMOTE_URL'" && set "K6_BROWSER_TIMEOUT='60s' && k6 run script.js
+```
+
+```bash
+PS C:\k6> $env:K6_BROWSER_WS_URL='REMOTE_URL' ; k6 run script.js
+```
+
+</CodeGroup>
+
 <Blockquote mod="note" title="">
 
 The following browser options are no longer supported: `devtools`, `env`, and `proxy` since they weren't providing much value. `slowMo` has been temporarily removed, and we're working on reintroducing it.