Update browser module isVisible and isHidden docs

[ankur22]

What?

This updates the docs for the isVisible and isHidden APIs in all associated classes.

Checklist

Please fill in this template:

• 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 make docs command locally and verified that the changes look good.

If updating the documentation for the next release of k6:

• I have made my changes in the docs/sources/next folder of the documentation.

Related PR(s)/Issue(s)

Related issue: grafana/xk6-browser#981

[ka3de]

Overall LGTM, just some small suggestions, but feel free to discard them if you think the current version is OK, these are no blockers by any means.

Also, I have a comment, maybe more for @heitortsergent:
Now we have a mix of methods for elementHandle and frame, some we do have our own specific documentation page, and some are just links to Playwright's method, as they are equivalent. This makes it look a little bit weird in the navigation sidebar. See:

The elementHandle has many methods listed in the table, on the right side doc, but on the left navigation sidebar it only lists the ones that we have documentation for. The same happens for frame. I guess this is OK and expected until we progressively add our own specific docs for each method, but it seemed a little bit weird, as it might look like it only has these two methods which are documented.

[inancgumus]

LGTM after @ka3de's suggestions.

[heitortsergent]

Just left one comment with a question, LGTM!

@ka3de that's a good point about the left-hand navigation only including a few methods, that can be confusing... One thing we could do is to fill out the section with pages for all the methods, even if the content in those pages is just linking to the playwright docs. But I'd also be curious if any users find it confusing, or think we don't might not support more methods if they only look at the left-hand navigation.

[heitortsergent]

Just out of curiosity, is there a specific reason why we recommend using the locator-based method?

[ankur22]

Locators are seen to be better since they will auto wait and retry the search for the element with the given selector. This means that we can set a locator, navigate to a page, and then still work with the locator after the navigation occurs (as long as the element is actually on the new page). Whereas with the frame APIs, once a navigation occurs, we cannot use the old reference to the element that was setup before the navigation. In a nutshell, locators are safer.

[heitortsergent]

Ah, that does seem better, thanks for the explanation! 🙇

[ankur22]

Probably needs to be explained somewhere in our docs though 👍

[inancgumus]

We explain locators with a Page Object Model example here. We might expand on it.