From 324cdcd874e1a9548251a64e29fa178c5e97c934 Mon Sep 17 00:00:00 2001 From: Dmitry Gozman Date: Mon, 13 Jun 2022 17:44:53 -0700 Subject: [PATCH] docs: warn about problematic usages of layout selectors (#14850) --- docs/src/selectors.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/src/selectors.md b/docs/src/selectors.md index 4719819d27..5b8795a8c4 100644 --- a/docs/src/selectors.md +++ b/docs/src/selectors.md @@ -702,9 +702,11 @@ More advanced Shadow DOM use cases: ## Selecting elements based on layout -Playwright can select elements based on the page layout. These can be combined with regular CSS for -better results, for example `input:right-of(:text("Password"))` matches an input field that is to the -right of text "Password". +Sometimes, it is hard to come up with a good selector to the target element when it lacks distinctive features. In this case, using Playwright layout selectors could help. These can be combined with regular CSS to pinpoint one of the multiple choices. + +For example, `input:right-of(:text("Password"))` matches an input field that is to the right of text "Password" - useful when the page has multiple inputs that are hard to distinguish between each other. + +Note that layout selector is useful in addition to something else, like `input`. If you use layout selector alone, like `:right-of(:text("Password"))`, most likely you'll get not the input you are looking for, but some empty element in between the text and the target input. :::note Layout selectors depend on the page layout and may produce unexpected results. For example, a different @@ -719,7 +721,7 @@ to compute distance and relative position of the elements. * `:below(inner > selector)` - Matches elements that are below any of the elements matching the inner selector, at any horizontal position. * `:near(inner > selector)` - Matches elements that are near (within 50 CSS pixels) any of the elements matching the inner selector. -Note that resulting matches are sorted by their distance to the anchor element, so you can use [`method: Locator.first`] to pick the closest one. +Note that resulting matches are sorted by their distance to the anchor element, so you can use [`method: Locator.first`] to pick the closest one. This is only useful if you have something like a list of similar elements, where the closest is obviously the right one. However, using [`method: Locator.first`] in other cases most likely won't work as expected - it will not target the element you are searching for, but some other element that happens to be the closest like a random empty `
`, or an element that is scrolled out and is not currently visible. ```js // Fill an input to the right of "Username".