docs(selectors): update structure and add best practices #3817
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
dgozman
approved these changes
Sep 9, 2020
docs/selectors.md
Outdated
| Playwright supports multiple selector engines used to query elements in the web page. | ||
|
|
||
| Selector can be used to obtain `ElementHandle` (see [page.$()](api.md#pageselector) for example) or shortcut element operations to avoid intermediate handle (see [page.click()](api.md#pageclickselector-options) for example). | ||
| Selectors query elements on the web page for interactions, like [page.click](api.md#pageclickselector-options), and to obtain `ElementHandle` through [page.$](api.md#pageselector). Built-in selectors auto-pierce [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) roots. |
There was a problem hiding this comment.
nit: 'shadow DOM roots' sounds strange, I'd leave just 'shadow DOM'.
docs/selectors.md
Outdated
| - Example: `page.click('div')` is converted to `page.click('css=div')`. | ||
|
|
||
| ### Combining selectors | ||
| Selectors defined as `engine=body` can be combined with the `>>` token, e.g. `clause1 >> clause2 >> clause3`. When multiple clauses are present, next one is queried relative to the previous one's result. |
There was a problem hiding this comment.
- Short-form selectors can be combined as well:
div >> ../../.. >> "text" - I'd replace "clause" with "selector" in this section.
docs/selectors.md
Outdated
| @@ -28,12 +45,61 @@ document | |||
| .querySelector('span[attr=value]') | |||
| ``` | |||
|
|
|||
| Selector engine name can be prefixed with `*` to capture element that matches the particular clause instead of the last one. For example, `css=article >> text=Hello` captures the element with the text `Hello`, and `*css=article >> text=Hello` (note the `*`) captures the `article` element that contains some element with the text `Hello`. | |||
| If a selector needs to include `>>` in the body, it should be escaped inside a string to not be confused with clause separator, e.g. `text="some >> text"`. | |||
There was a problem hiding this comment.
nit: 'clause separator' -> 'the separator'
docs/selectors.md
Outdated
| If a selector needs to include `>>` in the body, it should be escaped inside a string to not be confused with clause separator, e.g. `text="some >> text"`. | ||
|
|
||
| ### Intermediate matches | ||
| Selector clauses can be prefixed with `*` to capture element that matches a particular clause instead of the last one. For example, `css=article >> text=Hello` captures the element with the text `Hello`, and `*css=article >> text=Hello` (note the `*`) captures the `article` element that contains some element with the text `Hello`. |
There was a problem hiding this comment.
nit: "Selector engine name can be prefixed ...."
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.