What?

This adds a few new APIs. It would have been difficult to implement frameLocator on its own without the other two APIs:

1. It implements frameLocator which allows the user to interact with elements within iframes with locator like APIs.
2. On top of that it implements locator.contentFrame which returns a frameLocator, allowing the user to actually retrieve a frameLocator to start working with elements from with an iframe.
3. It implements frameLocator.locator allowing users to actually select elements in an iframe.

Why?

Working with locator like APIs is important for maintainable, less flakey tests. It's also a preferred way of working when interacting with iframes in Playwright. We're currently on a drive to improve k6 browser's parity to make migrating from Playwright to k6 easier.

Essentially, locator and frameLocator APIs will retrieve the latest version of an element or perform an action on the latest version of an element when such APIs are called. Currently websites are very dynamic and we always want to try to work with the latest version of the DOM when trying to retrieve data or perform actions. Working with page$ and frame.contentFrame are currently the only way to interact with elements in an iframe, but these are flakey since they work with old versions of the DOM.

The end result of this implementation also allows us to easily chain selectors. Before we used to have to do (imagine having to navigate to multiple nested iframes):

const frameB = await page.$('#frameB');
const frameBContent = await frameB.contentFrame(); // Takes a snapshot of the DOM

const frameC = await frameBContent.$('#frameB');
const frameCContent = await frameC.contentFrame(); // Takes a snapshot of the DOM

await frameCContent.locator("#increment", nil).click();

const count = await frameCContent.locator("#count").textContent();

and now we can do:

const frameCContent = page.locator('#frameB').contentFrame().locator('#frameC').contentFrame();

await frameCContent.locator("#increment", nil).click(); // Works with the latest DOM and performs actionability checks.

const count = await frameCContent.locator("#count").textContent(); // Works with the latest DOM and performs actionability checks.

Checklist

• I have performed a self-review of my code.
• I have commented on my code, particularly in hard-to-understand areas.
• I have added tests for my changes.
• I have run linter and tests locally (make check) and all pass.

Checklist: Documentation (only for k6 maintainers and if relevant)

Please do not merge this PR until the following items are filled out.

• I have added the correct milestone and labels to the PR.
• I have updated the release notes: link
• I have updated or added an issue to the k6-documentation: grafana/k6-docs#NUMBER if applicable
• I have updated or added an issue to the TypeScript definitions: grafana/k6-DefinitelyTyped@73db0e0 and grafana/k6-DefinitelyTyped@2fcfc47

Related PR(s)/Issue(s)

#5032