Docs: Browser documentation updates for v1.0.0

.vale/Vocab/docs/accept.txt

@@ -210,4 +210,5 @@ shm
 srgb
 kwallet
 referer
-scrollable
+scrollable
+headful

gatsby-node.js

@@ -1670,6 +1670,17 @@ const createRedirects = ({ actions }) => {
     isPermanent: true,
   });
 
+  createRedirect({
+    fromPath: '/using-k6-browser/selecting-elements/',
+    toPath: '/using-k6-browser/recommended-practices/selecting-elements/',
+    isPermanent: true,
+  });
+  createRedirect({
+    fromPath: '/using-k6-browser/examples/page-object-model/',
+    toPath: '/using-k6-browser/recommended-practices/page-object-model/',
+    isPermanent: true,
+  });
+
   const redirects = {
     '/javascript-api/k6-http/cookiejar-k6-http/':
       '/javascript-api/k6-http/cookiejar/',

src/data/markdown/docs/02 javascript api/07 k6-experimental/01 browser/01 Browser module.md

@@ -0,0 +1,53 @@
+****---
+title: "Browser module"
+excerpt: "Browser module"
+---
+
+The `Browser` module is the entry point for all your tests, and it is what interacts with the actual web browser via [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) (CDP). It manages:
+- [BrowserContext](/javascript-api/k6-experimental/browser/browsercontext/) which is where you can set a variety of attributes to control the behavior of pages;
+- and [Page](/javascript-api/k6-experimental/browser/page/) which is where your rendered site is displayed.
+
+A new browser process is automatically created when you use the `newContext` method of the `browser` module (`'k6/experimental/browser'`).
+
+| Method                                                                                    | Description                                                                                                                                           |
+|-------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [browser.contexts()](/javascript-api/k6-experimental/browser/browser-module/contexts)                        | Lets you access all open [BrowserContext](/javascript-api/k6-experimental/browser/browsercontext/)s.                                                        |
+| [browser.isConnected](/javascript-api/k6-experimental/browser/browser-module/isconnected) <BWIPT id="453"/>  | Indicates whether the [CDP](https://chromedevtools.github.io/devtools-protocol/) connection to the browser process is active or not.                  |
+| [browser.newContext([options])](/javascript-api/k6-experimental/browser/browser-module/newcontext/) <BWIPT id="455"/> | Creates and returns a new [BrowserContext](/javascript-api/k6-experimental/browser/browsercontext/).                                                             |
+| [browser.newPage([options])](/javascript-api/k6-experimental/browser/browser-module/newpage)  <BWIPT id="455"/>       | Creates a new [Page](/javascript-api/k6-experimental/browser/page/) in a new [BrowserContext](/javascript-api/k6-experimental/browser/browsercontext/) and returns the page. |
+| [browser.version()](/javascript-api/k6-experimental/browser/browser-module/version/)                          | Returns the browser application's version.                                                                                                            |
+
+### Example
+
+<CodeGroup labels={[]}>
+
+```javascript
+import { browser } from 'k6/experimental/browser';
+
+export const options = {
+  scenarios: {
+    browser: {
+      executor: 'shared-iterations',
+      options: {
+        browser: {
+            type: 'chromium',
+        },
+      },
+    },
+  },
+  thresholds: {
+    checks: ["rate==1.0"]
+  }
+}
+
+export default async function () {
+  const page = browser.newPage();
+  try {
+    await page.goto('https://test.k6.io/');
+  } finally {
+    page.close();
+  }
+}
+```
+
+</CodeGroup>

src/data/markdown/docs/02 javascript api/07 k6-experimental/01 browser/02 BrowserContext.md

@@ -3,16 +3,15 @@ title: "BrowserContext"
 excerpt: "Browser module: BrowserContext Class"
 ---
 
-`BrowserContext`s provide a way to operate multiple independent sessions, with separate pages, cache, and cookies. A default `BrowserContext` is created when a [Browser](/javascript-api/k6-experimental/browser/browser-class/) is launched.
+`BrowserContext`s provide a way to operate multiple independent sessions, with separate pages, cache, and cookies. A default `BrowserContext` is created when a browser is launched.
 
-The [Browser](/javascript-api/k6-experimental/browser/browser-class/) type is used to create a new `BrowserContext`.
+The [browser module API](/javascript-api/k6-experimental/browser#browser-module-api) is used to create a new `BrowserContext`.
 
 If a [page](/javascript-api/k6-experimental/browser/page/) opens another page, e.g. with a `window.open` call, the popup will belong to the parent page's `BrowserContext`.
 
 
 | Method                                                                                                                                          | Description                                                                                                |
 |-------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------|
-| [BrowserContext.browser()](/javascript-api/k6-experimental/browser/browsercontext/browser-instance/)                                                                 | Returns the [Browser](/javascript-api/k6-experimental/browser/browser-class/) instance that this `BrowserContext` belongs to. |
 | [BrowserContext.addCookies()](/javascript-api/k6-experimental/browser/browsercontext/addcookies/)                                                                    | Adds cookies into the `BrowserContext`. |
 | [BrowserContext.clearCookies()](/javascript-api/k6-experimental/browser/browsercontext/clearcookies/) <BWIPT id="442"/>                                     | Clear the `BrowserContext`'s cookies.                                                                      |
 | [BrowserContext.clearPermissions()](/javascript-api/k6-experimental/browser/browsercontext/clearpermissions) <BWIPT id="443"/>                              | Clears all permission overrides for the `BrowserContext`.                                                  |

src/data/markdown/docs/02 javascript api/07 k6-experimental/01 browser/02 BrowserContext/addCookies.md

@@ -10,10 +10,22 @@ Adds cookies into the `BrowserContext`. All pages within this context will have
 <CodeGroup labels={[]}>
 
 ```javascript
-import { chromium } from 'k6/experimental/browser';
+import { browser } from 'k6/experimental/browser';
+
+export const options = {
+  scenarios: {
+    browser: {
+      executor: 'shared-iterations',
+      options: {
+        browser: {
+            type: 'chromium',
+        },
+      },
+    },
+  },
+}
 
 export default async function () {
-  const browser = chromium.launch();
   const context = browser.newContext();
 
   context.addCookies([
@@ -26,6 +38,7 @@ export default async function () {
 
   const page = context.newPage();
   await page.goto('https://test.k6.io/');
+  page.close();
 }
 ```
 

src/data/markdown/docs/02 javascript api/07 k6-experimental/01 browser/02 BrowserContext/clearCookies.md

@@ -17,10 +17,22 @@ Clears the `BrowserContext`'s cookies.
 <CodeGroup labels={[]}>
 
 ```javascript
-import { chromium } from 'k6/experimental/browser';
+import { browser } from 'k6/experimental/browser';
+
+export const options = {
+  scenarios: {
+    browser: {
+      executor: 'shared-iterations',
+      options: {
+        browser: {
+            type: 'chromium',
+        },
+      },
+    },
+  },
+}
 
 export default async function () {
-  const browser = chromium.launch();
   const context = browser.newContext();
   const page = context.newPage();
 

src/data/markdown/docs/02 javascript api/07 k6-experimental/01 browser/02 BrowserContext/clearPermissions.md

@@ -18,10 +18,22 @@ Clears all permission overrides for the `BrowserContext`.
 <CodeGroup labels={[]}>
 
 ```javascript
-import { chromium } from 'k6/experimental/browser';
+import { browser } from 'k6/experimental/browser';
+
+export const options = {
+  scenarios: {
+    browser: {
+      executor: 'shared-iterations',
+      options: {
+        browser: {
+            type: 'chromium',
+        },
+      },
+    },
+  },
+}
 
 export default function () {
-  const browser = chromium.launch();
   const context = browser.newContext();
   context.grantPermissions(['clipboard-read']);
   // do stuff ...