docs(examples): add section on working with elements #1624
Merged
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
reviewed
Apr 1, 2020
docs/examples/README.md
Outdated
|
|
||
| * Types of selectors: Playwright can query elements on a web page through multiple selector engines like CSS, HTML attributes, XPath and text contents. | ||
| * See the [selectors guide](../selectors.md). | ||
| * Actions on elements: Use methods like [`page.click`](../api.md#pageclickselector-options) or [`page.fill`](#pagefillselector-value-options) to execute actions on elements. |
docs/examples/README.md
Outdated
| * Use the [`page.waitForSelector`](../api.md#pagewaitforselectorselector-options) method to explicitly wait for elements. | ||
| * Assertions on elements: Use [`page.$`](../api.md#pageselector) to fetch the element from the page and [`page.$eval`](../api.md#pageevalselector-pagefunction-arg-1) to run a JS function in the execution context of the page. | ||
| * These can be used to assert the visibility or contents of the elements. | ||
| * The semantics for these methods are the same as the `$` in the DevTools console or in jQuery. They fetch the element from the page without waiting. |
There was a problem hiding this comment.
Let's reiterate that most of the time you want waitForSelector.
docs/examples/README.md
Outdated
| @@ -43,6 +43,17 @@ It is also possible to open **browser developer tools** during execution, to ins | |||
| * A [`BrowserContext`](../api.md#class-browsercontext) is an isolated incognito session within a browser instance. Browser contexts are fast to create and can be used to parallelize isolated test executions. | |||
| * A [`Page`](../api.md#class-page) refers to a single tab within a browser context, which includes one or more [`Frame`](../api.md#class-frame) objects. | |||
|
|
|||
| ### Working with elements | |||
There was a problem hiding this comment.
I think this section will benefit from small code snippet for each bullet.
arjunattam
force-pushed
the
examples-3
branch
5 times, most recently
from
2f2ce01
to
b4c510a
Compare
|
Thanks for the suggestions - made these changes. Please take another look |
dgozman
approved these changes
Apr 1, 2020
docs/examples/README.md
Outdated
|
|
||
| ```js | ||
| // Explicitly wait for element to be present in the DOM | ||
| await page.waitForSelector('data-test-id=foo'); |
There was a problem hiding this comment.
// Explicitly wait for the #search field to be present in the DOM
const search = await page.waitForSelector('#search');
// Retrieve the query
const query = await search.evaluate(element => element.value);
docs/examples/README.md
Outdated
|
|
||
| ```js | ||
| // Get value of the #search field | ||
| await page.$eval('#search', element => element.value); |
There was a problem hiding this comment.
const query = await page.$eval('#search', element => element.value);
docs/examples/README.md
Outdated
|
|
||
| * Assertions on elements: Use [`page.$`](../api.md#pageselector) to get the element from the page and [`page.$eval`](../api.md#pageevalselector-pagefunction-arg-1) to run a JS function in the execution context of the page. | ||
| * These can be used to assert element properties, like visibility or text contents. | ||
| * These methods behave similar to the `$` operator in DevTools console or jQuery. They fetch the element from the page without waiting. If required, use `page.waitForSelector` to explicitly wait here. |
There was a problem hiding this comment.
If required, use page.waitForSelector and evaluate instead, as described above.
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.
With the goal of introducing the API to new comers, I've added a section to the getting started guide on elements, selectors and introduced some key API methods.