browser: add locator.evaluate and evaluateHandle

Author: AgnesToulet

docs/sources/k6/next/javascript-api/k6-browser/locator/_index.md

@@ -26,6 +26,8 @@ Locator can be created with the [page.locator(selector[, options])](https://graf
 | [count()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/locator/count)                                                            | Returns the number of elements matching the selector.                                                                   |
 | [dblclick([options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/locator/dblclick) {{< docs/bwipt id="471" >}}                 | Mouse double click on the chosen element.                                                                               |
 | [dispatchEvent(type, eventInit, [options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/locator/dispatchevent)                  | Dispatches HTML DOM event types e.g. `'click'`.                                                                         |
+| [evaluate(pageFunction[, arg])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/locator/evaluate)                                              | Returns the value of the `pageFunction` invocation, called with the matching element as first argument.                                       |
+| [evaluateHandle(pageFunction[, arg])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/locator/evaluatehandle)                                              | Returns the value of the `pageFunction` invocation as a [JSHandle](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/jshandle).                                       |
 | [fill(value, [options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/locator/fill)                                              | Fill an `input`, `textarea` or `contenteditable` element with the provided value.                                       |
 | [filter(options)](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/locator/filter)                                                   | Returns a new `locator` that matches only elements containing or excluding specified text.                               |
 | [first()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/locator/first)                                                            | Returns a `locator` to the first matching element.                                                                        |

docs/sources/k6/next/javascript-api/k6-browser/locator/evaluate.md

@@ -0,0 +1,68 @@
+---
+title: 'evaluate(pageFunction[, arg])'
+description: 'Browser module: locator.evaluate(pageFunction[, arg]) method'
+---
+
+# evaluate(pageFunction[, arg])
+
+Returns the value of the `pageFunction` invocation. It passes the matching element of the locator as the first argument to the `pageFunction` and arg as a second argument.
+
+<TableWithNestedRows>
+
+| Parameter    | Type               | Defaults | Description                                  |
+| ------------ | ------------------ | -------- | -------------------------------------------- |
+| pageFunction | function or string |          | Function to be evaluated.                    |
+| arg          | string             | `''`     | Optional argument to pass to `pageFunction`. |
+
+</TableWithNestedRows>
+
+### Returns
+
+| Type         | Description                         |
+| ------------ | ----------------------------------- |
+| Promise<any> | The return value of `pageFunction`. |
+
+### Example
+
+{{< code >}}
+
+<!-- eslint-skip -->
+
+```javascript
+import { browser } from 'k6/browser';
+import { check } from 'https://jslib.k6.io/k6-utils/1.5.0/index.js';
+
+export const options = {
+  scenarios: {
+    browser: {
+      executor: 'shared-iterations',
+      options: {
+        browser: {
+          type: 'chromium',
+        },
+      },
+    },
+  },
+};
+
+export default async function () {
+  const page = await browser.newPage();
+
+  try {
+    await page.goto("https://quickpizza.grafana.com", { waitUntil: "load" });
+
+    await page.getByText('Pizza, Please!').click();
+
+    await check(page, {
+      'pizza name': async p => {
+        const n = await p.locator('#pizza-name').evaluate((pizzaName, extra) => pizzaName.textContent + extra, ' Super pizza!');
+        return n == 'Our recommendation: Super pizza!';
+      }
+    });
+  } finally {
+    await page.close();
+  }
+}
+```
+
+{{< /code >}}

docs/sources/k6/next/javascript-api/k6-browser/locator/evaluatehandle.md

@@ -0,0 +1,69 @@
+---
+title: 'evaluateHandle(pageFunction[, arg])'
+description: 'Browser module: locator.evaluateHandle(pageFunction[, arg]) method'
+---
+
+# evaluateHandle(pageFunction[, arg])
+
+Returns the value of the `pageFunction` invocation as a `JSHandle`. It passes the matching element of the locator as the first argument to the `pageFunction` and arg as a second argument.
+
+The only difference between [evaluate](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/locator/evaluate/) and `evaluateHandle` is that `evaluateHandle` returns [JSHandle](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/jshandle/).
+
+<TableWithNestedRows>
+
+| Parameter    | Type               | Defaults | Description                                  |
+| ------------ | ------------------ | -------- | -------------------------------------------- |
+| pageFunction | function or string |          | Function to be evaluated.                    |
+| arg          | string             | `''`     | Optional argument to pass to `pageFunction`. |
+
+</TableWithNestedRows>
+
+### Returns
+
+| Type              | Description                                         |
+| ----------------- | --------------------------------------------------- |
+| Promise<JSHandle> | A `JSHandle` of the return value of `pageFunction`. |
+
+### Example
+
+{{< code >}}
+
+<!-- eslint-skip -->
+
+```javascript
+import { browser } from 'k6/browser';
+
+export const options = {
+  scenarios: {
+    browser: {
+      executor: 'shared-iterations',
+      options: {
+        browser: {
+          type: 'chromium',
+        },
+      },
+    },
+  },
+};
+
+export default async function () {
+  const page = await browser.newPage();
+
+  try {
+    await page.goto("https://quickpizza.grafana.com", { waitUntil: "load" });
+
+    await page.getByText('Pizza, Please!').click();
+
+    const jsHandle = await page.locator('#pizza-name').evaluateHandle((pizzaName) => pizzaName);
+
+    const obj = await jsHandle.evaluateHandle((handle) => {
+      return { innerText: handle.innerText };
+    });
+    console.log(await obj.jsonValue()); // {"innerText":"Our recommendation:"}
+  } finally {
+    await page.close();
+  }
+}
+```
+
+{{< /code >}}