Extend locateNodes with a locator to get navigable's container element

[OrKoN]

This change adds a new locator called container: when called for a parent navigable, given a child navigable as a locator, it locates the container element for the child navigable that is located within the parent navigable. While providing the parent navigable is redundant and it can be computed based on the child navigable, the interface matches existing locators which all select a node within the parent navigable that matches the locator criteria. In this case, the criterion is the child navigable identifier.

Providing start nodes to this locator would currently trigger an invalid argument error but eventually it could be supported if there is a use case.

Closes #794

---

Preview | Diff

[whimboo]

Is there a reason why we cannot have the container as part of the return value of the browsingContext.getTree command? It would be somewhat similar to the clientWindow field.

[OrKoN]

Yes, that API currently does not include any shared references from script and would not allow expressing the ownership of the returned DOM element.

[OrKoN]

To clarify: we could probably plumb it via the getTree along with the other options we might need to define how to return the element but to me it looks like locateNodes is a better place compared to the getTree.

[jgraham]

I think there's a slight misconception here: sharedId for nodes doesn't depend on ownership. locateNodes also doesn't provide a way to set the ownership. I broadly think that's fine for this API; it doesn't seem more useful to hold a reference to the container element than the Window itself.

[OrKoN]

Hm, when I was reviewing the locateNodes PR I recall there was the ownership parameter but indeed I do not see it after checking now. If we were to use the locateNodes for things other than a11y in Puppeteer, we would definitely need the ownership param to match the existing behavior.

[OrKoN]

Alright, I recall now: so in CDP we retain the resulting collection and not nodes individually so that is still different to the API here.

[jgraham]

The WebDriver model to this point is that the sharedId for a node is just an intrinsic property of the node, and returning it doesn't affect the lifetime of the node in any way. executeScript and friends also provide a way to take (shared) ownership of the (currently only root) return value.

We already have lots of APIs that return objects without providing any way to take ownership of them (notably anything returning a context). I don't immediately see why you'd need to take ownership of an iframe element with this kind of API; if something removes the iframe from the DOM you're probably in an unexpected state even if you still have a reference to the js object.

Anyway, I don't have a really strong opinion here, but if clients ~always want to know which iframe owns a nested browsing context, I think that getTree would work. If it's a rarer requirement, or there really is a strong use case for taking ownership of the iframe itself, then using either a separate command or a locator could work.

[OrKoN]

To clarify on the ownership: all element handles in Puppeteer (and maybe other clients) are retained until the client releases them. It allows getting the a handle to something and, for example, checking that it was disconnected for DOM or operating on temporary objects without polluting the global scope (e.g., creating some elements, retaining them via Puppeteer, using them in scripts later). The getter to obtain the container for a browsing context is the same kind of handle and should follow the same lifecycle.

Currently, we can evaluate using a sharedId to retain but it would be great to avoid the round trip.

[OrKoN]

so we currently only have requirements to provide this data in a separate command because this data is not always needed. Therefore, I think we should not bring it into getTree to avoid the overhead of finding out the sharedId for each browsing context. I still think the locateNodes is probably the best place given that it returns nodes and any changes made to locateNodes (e.g., bringing the ownership parameter back) should also affect this method.