browser: add locator.evaluate and evaluateHandle

[AgnesToulet]

What?

This PR adds the following functions in the locator API documentation:

• evaluate(pageFunction, arg)
• evaluateHandle(pageFunction, arg)

Checklist

• I have used a meaningful title for the PR.
• I have described the changes I've made in the "What?" section above.
• I have performed a self-review of my changes.
• I have run the npm start command locally and verified that the changes look good.

Related PR(s)/Issue(s)

Implementation PR: grafana/k6#5306

[github-actions]

💻 Deploy preview available:

• https://deploy-preview-k6-docs-2098-zb444pucvq-vp.a.run.app/docs/k6/
• https://deploy-preview-k6-docs-2098-zb444pucvq-vp.a.run.app/docs/k6/latest

[oleiade]

Left a couple of non-blocking comment. Feel free to dismiss them if I missed an important context piece 🙇🏻

[oleiade]

This information is super valuable, but felt really dry as I read it first. I suggest starting it with a high level overview of what this API will do for the user.

I see Playwright describes their evaluate method as "Execute JavaScript code in the page, taking the matching element as an argument.", which, from a user perspective answers the first question I had immediately: what is this API gonna do for me.

They only mention the pageFunction, what it does and how to use it later in a "details" section.

What do you think of:

Suggested change

	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.
	Execute JavaScript code in the page, taking the matching element as an argument.
	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.

[AgnesToulet]

I must admit I mostly copy/pasted the existing doc from other classes (as this function was already implemented in several places).
But it makes sense, I would rather suggest something like:

Suggested change

	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.
	Executes JavaScript code in the page, passing the matching element of the locator as the first argument to the `pageFunction` and arg as a second argument. It returns the value of the `pageFunction` invocation.

WDYT @ankur22? If we agree on a function description, I'll update it in all pages and not only here.

[ankur22]

Yep, thanks for this! the updated wording LGTM 🚀

[AgnesToulet]

I made the update to all pages 👍

[github-actions]

💻 Deploy preview available (browser: add locator.evaluate and evaluateHandle):

• https://deploy-preview-k6-docs-2098-zb444pucvq-vp.a.run.app/docs/k6/
• https://deploy-preview-k6-docs-2098-zb444pucvq-vp.a.run.app/docs/k6/latest

[ankur22]

LGTM 🚀

[heitortsergent]

Left some minor nit suggestions, overall it looks great! 🙇

[heitortsergent]

This is unrelated to the changes in the PR, but seems like the Run code blocks workflow is failing on page/evaluate.md due to a wrong import.

Looks like we need to change the line 2:

import { check } from 'k6/http';

To:

import { check } from 'k6';