Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(examples): add section on working with elements #1624

Merged
merged 1 commit into from
Apr 1, 2020

Conversation

arjunattam
Copy link
Contributor

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.

@arjunattam arjunattam requested a review from dgozman April 1, 2020 17:38

* 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

page.fill link is broken.

* 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's reiterate that most of the time you want waitForSelector.

@@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this section will benefit from small code snippet for each bullet.

@arjunattam arjunattam force-pushed the examples-3 branch 5 times, most recently from 2f2ce01 to b4c510a Compare April 1, 2020 21:45
@arjunattam
Copy link
Contributor Author

Thanks for the suggestions - made these changes. Please take another look

Copy link
Contributor

@dgozman dgozman left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dropped some code suggestions, otherwise looks great.


```js
// Explicitly wait for element to be present in the DOM
await page.waitForSelector('data-test-id=foo');
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

// 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);


```js
// Get value of the #search field
await page.$eval('#search', element => element.value);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

const query = await page.$eval('#search', element => element.value);


* 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If required, use page.waitForSelector and evaluate instead, as described above.

@arjunattam arjunattam merged commit 9d04dcc into microsoft:master Apr 1, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants