[Question] Documentation for page.waitForSelector() and visibility

[thernstig]

Hi!

Been using Playwright (and previously Puppeteer) for some time now, and wanted to ask a question that might turn out to be some documentation updates.

One of the concepts I've seen new users get stuck on is https://github.com/microsoft/playwright/blob/master/docs/api.md#pagewaitforselectorselector-options and the wording of the waitFor:

waitFor <"attached"|"detached"|"visible"|"hidden"> Wait for element to become visible (visible), hidden (hidden), present in dom (attached) or not present in dom (detached). Defaults to attached.

The term visible is what confuses people.

https://github.com/microsoft/playwright/blob/master/docs/core-concepts.md#auto-waiting now explains this pretty good, but also that text mentions nothing about the actual CSS property called visibility that has a value of visible (https://developer.mozilla.org/en-US/docs/Web/CSS/visibility).

Now, is there any way to make this less confusing for users? What they struggle on is to think that visible actual means the CSS property visibility: visible.

[dgozman]

I have updated the docs, any feedback is welcome!

[thernstig]

@dgozman I apologize for the abundance of questions here, but I do want the docs to be good, so it is with good intentions.

1. Does this sentence, it has non-empty bounding box (for example, it has some content and no display:none), mean that an element with nothing in it (i.e. just empty) will be considered hidden? I.e. it exists in the DOM, is visible, but no content inside the bounding box?

2. Should you add the word attached to the DOM in this text - displayed (for example, not empty, no display:none, no visibility:hidden),? It might become too verbose though.

3. In the docs at https://github.com/microsoft/playwright/blob/master/docs/core-concepts.md#auto-waiting it says ... or to become hidden or detached but the example only show 'detached' - not sure if that can be confusing for user or not.

4. Is there a reason waitForSelector behaves differently than the Auto-waiting functionality such as on page.click()? waitForSelector does not wait for e.g. wait for it to stop moving, for example, until css transition finishes (and some of the other auto-waiting functionalities).

5. https://github.com/microsoft/playwright/blob/master/docs/core-concepts.md#auto-waiting says nothing about bounding-box, whilst the API docs for waitForSelector() does. I assume the Auto-wait also behaves the same in regards to the bounding box?

[dgozman]

@dgozman I apologize for the abundance of questions here, but I do want the docs to be good, so it is with good intentions.

Thank you for the thorough details, very appreciated!

1. Does this sentence, it has non-empty bounding box (for example, it has some content and no display:none), mean that an element with nothing in it (i.e. just empty) will be considered hidden? I.e. it exists in the DOM, is visible, but no content inside the bounding box?

That is correct. The alternative is to use attached, which is default.

2. Should you add the word attached to the DOM in this text - displayed (for example, not empty, no display:none, no visibility:hidden),? It might become too verbose though.

Sure, I'll update docs more.

3. In the docs at https://github.com/microsoft/playwright/blob/master/docs/core-concepts.md#auto-waiting it says ... or to become hidden or detached but the example only show 'detached' - not sure if that can be confusing for user or not.

Great point!

4. Is there a reason waitForSelector behaves differently than the Auto-waiting functionality such as on page.click()? waitForSelector does not wait for e.g. wait for it to stop moving, for example, until css transition finishes (and some of the other auto-waiting functionalities).

waitForSelector just waits for the element. Since we don't know what the user is going to do with the element (for example, clicking, getting text content or evaluating), waiting for actionability can be a wrong thing to do.

5. https://github.com/microsoft/playwright/blob/master/docs/core-concepts.md#auto-waiting says nothing about bounding-box, whilst the API docs for waitForSelector() does. I assume the Auto-wait also behaves the same in regards to the bounding box?

non empty means non empty bounding box. I will clarify that.

[thernstig]

Great!

Regarding 1, what is the reason that an element is not considered waitFor: 'visible if it has display:block and visibility:visible, as an example? Because you expect the user to also want some content in it, that might be put there via JavaScript or something?

Regarding 4, would a waitForActionable make sense to implement? I've been needing to use a waitForSelector when it comes to a table where I want to pick out all <tr> with page.$$(). But the table is somewhat animated and it can mess up things.

[dgozman]

Regarding 1, what is the reason that an element is not considered waitFor: 'visible if it has display:block and visibility:visible, as an example? Because you expect the user to also want some content in it, that might be put there via JavaScript or something?

The non-empty requirement means it is actually visible to the user, and also can be interacted with (e.g. clicked). Overall, Playwright has to settle on some notion of what visible means, and being consistent with "visible to be clicked" is nice.

Regarding 4, would a waitForActionable make sense to implement? I've been needing to use a waitForSelector when it comes to a table where I want to pick out all <tr> with page.$$(). But the table is somewhat animated and it can mess up things.

That could be a valid feature request. The main problem is defining what waitForActionable means. When you click, the context suggests that "actionable" means "can be clicked". For a free-standing method without extra context, defining this state is trickier.

[maurusrv]

... I've been needing to use a waitForSelector when it comes to a table where I want to pick out all with page.$$(). But the table is somewhat animated and it can mess up things.

I think I have a similar issue with this. Say, for example, my chosen selector is already in the DOM, and I will also be using page.$$() to get all that satifies my selector, but my problem is i need to wait for other elements with the same selector even though one element is already visible or actionable in the DOM. any workaround for this?

thank you!

[dgozman]

@maurusrv Please see #2370, where we discuss possible solutions.