Filip/playwright
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

docs: explain label retargeting in selectors doc and some input actions (#13725)

Browse source
This commit is contained in:
Dmitry Gozman 2022-04-25 13:55:41 +01:00 committed by GitHub
parent 01a8977b4d
commit d2bdb1d7cf
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
7 changed files with 156 additions and 48 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
docs/src/api/class-elementhandle.md
View file

@ -515,7 +515,9 @@ Returns the `element.innerText`.
## async method: ElementHandle.inputValue
- returns: <[string]>
Returns `input.value` for `<input>` or `<textarea>` or `<select>` element. Throws for non-input elements.
Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the control.
### option: ElementHandle.inputValue.timeout = %%-input-timeout-%%
@ -719,6 +721,8 @@ await handle.SelectOptionAsync(new[] {
This method waits for [actionability](../actionability.md) checks, then focuses the element and selects all its text
content.
If the element is inside the `<label>` element that has an associated [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), focuses and selects text in the control instead.
### option: ElementHandle.selectText.force = %%-input-force-%%
### option: ElementHandle.selectText.timeout = %%-input-timeout-%%
@ -746,12 +750,13 @@ When all steps combined have not finished during the specified [`option: timeout
## async method: ElementHandle.setInputFiles
This method expects `elementHandle` to point to an
[input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they
are resolved relative to the the current working directory. For empty array, clears the selected files.
This method expects [`elementHandle`] to point to an
[input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside the `<label>` element that has an associated [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
### param: ElementHandle.setInputFiles.files = %%-input-files-%%
### option: ElementHandle.setInputFiles.noWaitAfter = %%-input-no-wait-after-%%

10
docs/src/api/class-frame.md
View file

@ -904,7 +904,9 @@ Returns `element.innerText`.
## async method: Frame.inputValue
- returns: <[string]>
Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element. Throws for non-input elements.
Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the control.
### param: Frame.inputValue.selector = %%-input-selector-%%
@ -1192,12 +1194,12 @@ HTML markup to assign to the page.
## async method: Frame.setInputFiles
This method expects [`param: selector`] to point to an
[input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they
are resolved relative to the the current working directory. For empty array, clears the selected files.
This method expects [`param: selector`] to point to an
[input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside the `<label>` element that has an associated [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
### param: Frame.setInputFiles.selector = %%-input-selector-%%
### param: Frame.setInputFiles.files = %%-input-files-%%
### option: Frame.setInputFiles.noWaitAfter = %%-input-no-wait-after-%%

12
docs/src/api/class-locator.md
View file

@ -482,7 +482,9 @@ Returns the `element.innerText`.
## async method: Locator.inputValue
- returns: <[string]>
Returns `input.value` for `<input>` or `<textarea>` or `<select>` element. Throws for non-input elements.
Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the control.
### option: Locator.inputValue.timeout = %%-input-timeout-%%
@ -698,6 +700,8 @@ await element.SelectOptionAsync(new[] {
This method waits for [actionability](../actionability.md) checks, then focuses the element and selects all its text
content.
If the element is inside the `<label>` element that has an associated [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), focuses and selects text in the control instead.
### option: Locator.selectText.force = %%-input-force-%%
### option: Locator.selectText.timeout = %%-input-timeout-%%
@ -725,12 +729,12 @@ When all steps combined have not finished during the specified [`option: timeout
## async method: Locator.setInputFiles
This method expects `element` to point to an
[input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they
are resolved relative to the the current working directory. For empty array, clears the selected files.
This method expects [`locator`] to point to an
[input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside the `<label>` element that has an associated [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
### param: Locator.setInputFiles.files = %%-input-files-%%
### option: Locator.setInputFiles.noWaitAfter = %%-input-no-wait-after-%%
### option: Locator.setInputFiles.timeout = %%-input-timeout-%%

10
docs/src/api/class-page.md
View file

@ -2109,7 +2109,9 @@ Returns `element.innerText`.
## async method: Page.inputValue
- returns: <[string]>
Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element. Throws for non-input elements.
Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the control.
### param: Page.inputValue.selector = %%-input-selector-%%
@ -2894,12 +2896,12 @@ An object containing additional HTTP headers to be sent with every request. All
## async method: Page.setInputFiles
This method expects [`param: selector`] to point to an
[input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they
are resolved relative to the the current working directory. For empty array, clears the selected files.
This method expects [`param: selector`] to point to an
[input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside the `<label>` element that has an associated [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
### param: Page.setInputFiles.selector = %%-input-selector-%%
### param: Page.setInputFiles.files = %%-input-files-%%

39
docs/src/selectors.md
View file

@ -762,6 +762,45 @@ await page.Locator("button:near(.promo-card)").ClickAsync();
All layout selectors support optional maximum pixel distance as the last argument. For example
`button:near(:text("Username"), 120)` matches a button that is at most 120 pixels away from the element with the text "Username".
## Selecting elements by label text
Targeted input actions in Playwright automatically distinguish between labels and controls, so you can target the label to perform an action on the associated control.
For example, consider the following DOM structure: `<label for="password">Password:</label><input id="password" type="password">`. You can target the label with something like `text=Password` and perform the following actions on the input instead:
- `click` will click the label and automatically focus the input field;
- `fill` will fill the input field;
- `inputValue` will return the value of the input field;
- `selectText` will select text in the input field;
- `setInputFiles` will set files for the input field with `type=file`;
- `selectOption` will select an option from the select box.
```js
// Fill the input by targeting the label.
await page.fill('text=Password', 'secret');
```
```java
// Fill the input by targeting the label.
page.fill("text=Password", "secret");
```
```python async
# Fill the input by targeting the label.
await page.fill('text=Password', 'secret')
```
```python sync
# Fill the input by targeting the label.
page.fill('text=Password', 'secret')
```
```csharp
// Fill the input by targeting the label.
await page.FillAsync("text=Password", "secret");
```
However, other methods will target the label itself, for example `textContent` will return the text content of the label, not the input field.
## XPath selectors
XPath selectors are equivalent to calling [`Document.evaluate`](https://developer.mozilla.org/en/docs/Web/API/Document/evaluate).

60
packages/playwright-core/types/types.d.ts vendored
View file

@ -2450,7 +2450,10 @@ export interface Page {
}): Promise<string>;
/**
* Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element. Throws for non-input elements.
* Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
*
* Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the control.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param options
*/
@ -3187,11 +3190,13 @@ export interface Page {
setExtraHTTPHeaders(headers: { [key: string]: string; }): Promise<void>;
/**
* This method expects `selector` to point to an
* [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
*
* Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they
* are resolved relative to the the current working directory. For empty array, clears the selected files.
*
* This method expects `selector` to point to an
* [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside the
* `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param files
* @param options
@ -5274,7 +5279,10 @@ export interface Frame {
}): Promise<string>;
/**
* Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element. Throws for non-input elements.
* Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
*
* Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the control.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param options
*/
@ -5693,11 +5701,13 @@ export interface Frame {
}): Promise<void>;
/**
* This method expects `selector` to point to an
* [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
*
* Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they
* are resolved relative to the the current working directory. For empty array, clears the selected files.
*
* This method expects `selector` to point to an
* [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside the
* `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param files
* @param options
@ -8037,7 +8047,10 @@ export interface ElementHandle<T=Node> extends JSHandle<T> {
innerText(): Promise<string>;
/**
* Returns `input.value` for `<input>` or `<textarea>` or `<select>` element. Throws for non-input elements.
* Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
*
* Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the control.
* @param options
*/
inputValue(options?: {
@ -8300,6 +8313,10 @@ export interface ElementHandle<T=Node> extends JSHandle<T> {
/**
* This method waits for [actionability](https://playwright.dev/docs/actionability) checks, then focuses the element and selects all its text
* content.
*
* If the element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), focuses and selects text in the
* control instead.
* @param options
*/
selectText(options?: {
@ -8372,11 +8389,13 @@ export interface ElementHandle<T=Node> extends JSHandle<T> {
}): Promise<void>;
/**
* This method expects `elementHandle` to point to an
* [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
*
* Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they
* are resolved relative to the the current working directory. For empty array, clears the selected files.
*
* This method expects [`elementHandle`] to point to an
* [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside the
* `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
* @param files
* @param options
*/
@ -9283,7 +9302,10 @@ export interface Locator {
}): Promise<string>;
/**
* Returns `input.value` for `<input>` or `<textarea>` or `<select>` element. Throws for non-input elements.
* Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
*
* Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the control.
* @param options
*/
inputValue(options?: {
@ -9570,6 +9592,10 @@ export interface Locator {
/**
* This method waits for [actionability](https://playwright.dev/docs/actionability) checks, then focuses the element and selects all its text
* content.
*
* If the element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), focuses and selects text in the
* control instead.
* @param options
*/
selectText(options?: {
@ -9642,11 +9668,13 @@ export interface Locator {
}): Promise<void>;
/**
* This method expects `element` to point to an
* [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
*
* Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they
* are resolved relative to the the current working directory. For empty array, clears the selected files.
*
* This method expects [`locator`] to point to an
* [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside the
* `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
* @param files
* @param options
*/

60
tests/config/experimental.d.ts vendored
View file

@ -2452,7 +2452,10 @@ export interface Page {
}): Promise<string>;
/**
* Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element. Throws for non-input elements.
* Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
*
* Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the control.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param options
*/
@ -3189,11 +3192,13 @@ export interface Page {
setExtraHTTPHeaders(headers: { [key: string]: string; }): Promise<void>;
/**
* This method expects `selector` to point to an
* [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
*
* Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they
* are resolved relative to the the current working directory. For empty array, clears the selected files.
*
* This method expects `selector` to point to an
* [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside the
* `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param files
* @param options
@ -5276,7 +5281,10 @@ export interface Frame {
}): Promise<string>;
/**
* Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element. Throws for non-input elements.
* Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
*
* Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the control.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param options
*/
@ -5695,11 +5703,13 @@ export interface Frame {
}): Promise<void>;
/**
* This method expects `selector` to point to an
* [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
*
* Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they
* are resolved relative to the the current working directory. For empty array, clears the selected files.
*
* This method expects `selector` to point to an
* [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside the
* `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
* @param files
* @param options
@ -8039,7 +8049,10 @@ export interface ElementHandle<T=Node> extends JSHandle<T> {
innerText(): Promise<string>;
/**
* Returns `input.value` for `<input>` or `<textarea>` or `<select>` element. Throws for non-input elements.
* Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
*
* Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the control.
* @param options
*/
inputValue(options?: {
@ -8309,6 +8322,10 @@ export interface ElementHandle<T=Node> extends JSHandle<T> {
/**
* This method waits for [actionability](https://playwright.dev/docs/actionability) checks, then focuses the element and selects all its text
* content.
*
* If the element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), focuses and selects text in the
* control instead.
* @param options
*/
selectText(options?: {
@ -8381,11 +8398,13 @@ export interface ElementHandle<T=Node> extends JSHandle<T> {
}): Promise<void>;
/**
* This method expects `elementHandle` to point to an
* [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
*
* Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they
* are resolved relative to the the current working directory. For empty array, clears the selected files.
*
* This method expects [`elementHandle`] to point to an
* [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside the
* `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
* @param files
* @param options
*/
@ -9292,7 +9311,10 @@ export interface Locator {
}): Promise<string>;
/**
* Returns `input.value` for `<input>` or `<textarea>` or `<select>` element. Throws for non-input elements.
* Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element.
*
* Throws for non-input elements. However, if the element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), returns the value of the control.
* @param options
*/
inputValue(options?: {
@ -9579,6 +9601,10 @@ export interface Locator {
/**
* This method waits for [actionability](https://playwright.dev/docs/actionability) checks, then focuses the element and selects all its text
* content.
*
* If the element is inside the `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), focuses and selects text in the
* control instead.
* @param options
*/
selectText(options?: {
@ -9651,11 +9677,13 @@ export interface Locator {
}): Promise<void>;
/**
* This method expects `element` to point to an
* [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
*
* Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they
* are resolved relative to the the current working directory. For empty array, clears the selected files.
*
* This method expects [`locator`] to point to an
* [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). However, if the element is inside the
* `<label>` element that has an associated
* [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), targets the control instead.
* @param files
* @param options
*/