Skip to content

Commit

Permalink
feat(roll): roll to ToT Playwright (28-10-22) (microsoft#818)
Browse files Browse the repository at this point in the history
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
  • Loading branch information
playwrightmachine and github-actions[bot] authored Oct 28, 2022
1 parent 59548d2 commit 3b46f1f
Show file tree
Hide file tree
Showing 41 changed files with 1,455 additions and 587 deletions.
46 changes: 40 additions & 6 deletions dotnet/docs/api/class-frame.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -511,7 +511,7 @@ Returns element attribute value.

- `text`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-get-by-alt-text-option-text"/> &#60;[string]|[Regex]&#62; Text to locate the element for.<a href="#frame-get-by-alt-text-option-text" class="list-anchor">#</a>
- `options` &#60;`FrameGetByAltTextOptions?`&#62;
- `Exact`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-get-by-alt-text-option-exact"/> &#60;[bool]?&#62; Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression.<a href="#frame-get-by-alt-text-option-exact" class="list-anchor">#</a>
- `Exact`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-get-by-alt-text-option-exact"/> &#60;[bool]?&#62; Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace.<a href="#frame-get-by-alt-text-option-exact" class="list-anchor">#</a>
- returns:<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-get-by-alt-text-return"/> &#60;[Locator]&#62;<a href="#frame-get-by-alt-text-return" class="list-anchor">#</a>

Allows locating elements by their alt text. For example, this method will find the image by alt text "Castle":
Expand All @@ -526,7 +526,7 @@ Allows locating elements by their alt text. For example, this method will find t

- `text`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-get-by-label-option-text"/> &#60;[string]|[Regex]&#62; Text to locate the element for.<a href="#frame-get-by-label-option-text" class="list-anchor">#</a>
- `options` &#60;`FrameGetByLabelOptions?`&#62;
- `Exact`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-get-by-label-option-exact"/> &#60;[bool]?&#62; Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression.<a href="#frame-get-by-label-option-exact" class="list-anchor">#</a>
- `Exact`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-get-by-label-option-exact"/> &#60;[bool]?&#62; Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace.<a href="#frame-get-by-label-option-exact" class="list-anchor">#</a>
- returns:<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-get-by-label-return"/> &#60;[Locator]&#62;<a href="#frame-get-by-label-return" class="list-anchor">#</a>

Allows locating input elements by the text of the associated label. For example, this method will find the input by label text "Password" in the following DOM:
Expand All @@ -542,7 +542,7 @@ Allows locating input elements by the text of the associated label. For example,

- `text`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-get-by-placeholder-option-text"/> &#60;[string]|[Regex]&#62; Text to locate the element for.<a href="#frame-get-by-placeholder-option-text" class="list-anchor">#</a>
- `options` &#60;`FrameGetByPlaceholderOptions?`&#62;
- `Exact`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-get-by-placeholder-option-exact"/> &#60;[bool]?&#62; Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression.<a href="#frame-get-by-placeholder-option-exact" class="list-anchor">#</a>
- `Exact`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-get-by-placeholder-option-exact"/> &#60;[bool]?&#62; Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace.<a href="#frame-get-by-placeholder-option-exact" class="list-anchor">#</a>
- returns:<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-get-by-placeholder-return"/> &#60;[Locator]&#62;<a href="#frame-get-by-placeholder-return" class="list-anchor">#</a>

Allows locating input elements by the placeholder text. For example, this method will find the input by placeholder "Country":
Expand Down Expand Up @@ -605,18 +605,52 @@ Locate element by the test id. By default, the `data-testid` attribute is used a

- `text`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-get-by-text-option-text"/> &#60;[string]|[Regex]&#62; Text to locate the element for.<a href="#frame-get-by-text-option-text" class="list-anchor">#</a>
- `options` &#60;`FrameGetByTextOptions?`&#62;
- `Exact`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-get-by-text-option-exact"/> &#60;[bool]?&#62; Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression.<a href="#frame-get-by-text-option-exact" class="list-anchor">#</a>
- `Exact`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-get-by-text-option-exact"/> &#60;[bool]?&#62; Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace.<a href="#frame-get-by-text-option-exact" class="list-anchor">#</a>
- returns:<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-get-by-text-return"/> &#60;[Locator]&#62;<a href="#frame-get-by-text-return" class="list-anchor">#</a>

Allows locating elements that contain given text.
Allows locating elements that contain given text. Consider the following DOM structure:

```html
<div>Hello <span>world</span></div>
<div>Hello</div>
```

You can locate by text substring, exact string, or a regular expression:

```csharp
// Matches <span>
page.GetByText("world")

// Matches first <div>
page.GetByText("Hello world")

// Matches second <div>
page.GetByText("Hello", new() { Exact: true })

// Matches both <div>s
page.GetByText(new Regex("Hello"))

// Matches second <div>
page.GetByText(new Regex("^hello$", RegexOptions.IgnoreCase))
```

See also [Locator.Filter(options)](/api/class-locator.mdx#locator-filter) that allows to match by another criteria, like an accessible role, and then filter by the text content.

:::note
Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple spaces into one, turns line breaks into spaces and ignores leading and trailing whitespace.
:::

:::note
Input elements of the type `button` and `submit` are matched by their `value` instead of the text content. For example, locating by text `"Log in"` matches `<input type=button value="Log in">`.
:::

## Frame.GetByTitle(text, options) {#frame-get-by-title}

<font size="2" style={{position: "relative", top: "-20px"}}>Added in: v1.27</font>

- `text`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-get-by-title-option-text"/> &#60;[string]|[Regex]&#62; Text to locate the element for.<a href="#frame-get-by-title-option-text" class="list-anchor">#</a>
- `options` &#60;`FrameGetByTitleOptions?`&#62;
- `Exact`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-get-by-title-option-exact"/> &#60;[bool]?&#62; Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression.<a href="#frame-get-by-title-option-exact" class="list-anchor">#</a>
- `Exact`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-get-by-title-option-exact"/> &#60;[bool]?&#62; Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace.<a href="#frame-get-by-title-option-exact" class="list-anchor">#</a>
- returns:<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-get-by-title-return"/> &#60;[Locator]&#62;<a href="#frame-get-by-title-return" class="list-anchor">#</a>

Allows locating elements by their title. For example, this method will find the button by its title "Place the order":
Expand Down
48 changes: 41 additions & 7 deletions dotnet/docs/api/class-framelocator.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import TabItem from '@theme/TabItem';
FrameLocator represents a view to the `iframe` on the page. It captures the logic sufficient to retrieve the `iframe` and locate elements in that iframe. FrameLocator can be created with either [Page.FrameLocator(selector)](/api/class-page.mdx#page-frame-locator) or [Locator.FrameLocator(selector)](/api/class-locator.mdx#locator-frame-locator) method.

```csharp
var locator = page.FrameLocator("#my-frame").Locator("text=Submit");
var locator = page.FrameLocator("#my-frame").GetByText("Submit");
await locator.ClickAsync();
```

Expand Down Expand Up @@ -69,7 +69,7 @@ When working with iframes, you can create a frame locator that will enter the if

- `text`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-locator-get-by-alt-text-option-text"/> &#60;[string]|[Regex]&#62; Text to locate the element for.<a href="#frame-locator-get-by-alt-text-option-text" class="list-anchor">#</a>
- `options` &#60;`FrameLocatorGetByAltTextOptions?`&#62;
- `Exact`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-locator-get-by-alt-text-option-exact"/> &#60;[bool]?&#62; Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression.<a href="#frame-locator-get-by-alt-text-option-exact" class="list-anchor">#</a>
- `Exact`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-locator-get-by-alt-text-option-exact"/> &#60;[bool]?&#62; Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace.<a href="#frame-locator-get-by-alt-text-option-exact" class="list-anchor">#</a>
- returns:<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-locator-get-by-alt-text-return"/> &#60;[Locator]&#62;<a href="#frame-locator-get-by-alt-text-return" class="list-anchor">#</a>

Allows locating elements by their alt text. For example, this method will find the image by alt text "Castle":
Expand All @@ -84,7 +84,7 @@ Allows locating elements by their alt text. For example, this method will find t

- `text`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-locator-get-by-label-option-text"/> &#60;[string]|[Regex]&#62; Text to locate the element for.<a href="#frame-locator-get-by-label-option-text" class="list-anchor">#</a>
- `options` &#60;`FrameLocatorGetByLabelOptions?`&#62;
- `Exact`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-locator-get-by-label-option-exact"/> &#60;[bool]?&#62; Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression.<a href="#frame-locator-get-by-label-option-exact" class="list-anchor">#</a>
- `Exact`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-locator-get-by-label-option-exact"/> &#60;[bool]?&#62; Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace.<a href="#frame-locator-get-by-label-option-exact" class="list-anchor">#</a>
- returns:<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-locator-get-by-label-return"/> &#60;[Locator]&#62;<a href="#frame-locator-get-by-label-return" class="list-anchor">#</a>

Allows locating input elements by the text of the associated label. For example, this method will find the input by label text "Password" in the following DOM:
Expand All @@ -100,7 +100,7 @@ Allows locating input elements by the text of the associated label. For example,

- `text`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-locator-get-by-placeholder-option-text"/> &#60;[string]|[Regex]&#62; Text to locate the element for.<a href="#frame-locator-get-by-placeholder-option-text" class="list-anchor">#</a>
- `options` &#60;`FrameLocatorGetByPlaceholderOptions?`&#62;
- `Exact`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-locator-get-by-placeholder-option-exact"/> &#60;[bool]?&#62; Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression.<a href="#frame-locator-get-by-placeholder-option-exact" class="list-anchor">#</a>
- `Exact`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-locator-get-by-placeholder-option-exact"/> &#60;[bool]?&#62; Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace.<a href="#frame-locator-get-by-placeholder-option-exact" class="list-anchor">#</a>
- returns:<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-locator-get-by-placeholder-return"/> &#60;[Locator]&#62;<a href="#frame-locator-get-by-placeholder-return" class="list-anchor">#</a>

Allows locating input elements by the placeholder text. For example, this method will find the input by placeholder "Country":
Expand Down Expand Up @@ -163,18 +163,52 @@ Locate element by the test id. By default, the `data-testid` attribute is used a

- `text`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-locator-get-by-text-option-text"/> &#60;[string]|[Regex]&#62; Text to locate the element for.<a href="#frame-locator-get-by-text-option-text" class="list-anchor">#</a>
- `options` &#60;`FrameLocatorGetByTextOptions?`&#62;
- `Exact`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-locator-get-by-text-option-exact"/> &#60;[bool]?&#62; Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression.<a href="#frame-locator-get-by-text-option-exact" class="list-anchor">#</a>
- `Exact`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-locator-get-by-text-option-exact"/> &#60;[bool]?&#62; Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace.<a href="#frame-locator-get-by-text-option-exact" class="list-anchor">#</a>
- returns:<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-locator-get-by-text-return"/> &#60;[Locator]&#62;<a href="#frame-locator-get-by-text-return" class="list-anchor">#</a>

Allows locating elements that contain given text.
Allows locating elements that contain given text. Consider the following DOM structure:

```html
<div>Hello <span>world</span></div>
<div>Hello</div>
```

You can locate by text substring, exact string, or a regular expression:

```csharp
// Matches <span>
page.GetByText("world")

// Matches first <div>
page.GetByText("Hello world")

// Matches second <div>
page.GetByText("Hello", new() { Exact: true })

// Matches both <div>s
page.GetByText(new Regex("Hello"))

// Matches second <div>
page.GetByText(new Regex("^hello$", RegexOptions.IgnoreCase))
```

See also [Locator.Filter(options)](/api/class-locator.mdx#locator-filter) that allows to match by another criteria, like an accessible role, and then filter by the text content.

:::note
Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple spaces into one, turns line breaks into spaces and ignores leading and trailing whitespace.
:::

:::note
Input elements of the type `button` and `submit` are matched by their `value` instead of the text content. For example, locating by text `"Log in"` matches `<input type=button value="Log in">`.
:::

## FrameLocator.GetByTitle(text, options) {#frame-locator-get-by-title}

<font size="2" style={{position: "relative", top: "-20px"}}>Added in: v1.27</font>

- `text`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-locator-get-by-title-option-text"/> &#60;[string]|[Regex]&#62; Text to locate the element for.<a href="#frame-locator-get-by-title-option-text" class="list-anchor">#</a>
- `options` &#60;`FrameLocatorGetByTitleOptions?`&#62;
- `Exact`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-locator-get-by-title-option-exact"/> &#60;[bool]?&#62; Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression.<a href="#frame-locator-get-by-title-option-exact" class="list-anchor">#</a>
- `Exact`<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-locator-get-by-title-option-exact"/> &#60;[bool]?&#62; Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace.<a href="#frame-locator-get-by-title-option-exact" class="list-anchor">#</a>
- returns:<a aria-hidden="true" tabindex="-1" class="list-anchor-link" id="frame-locator-get-by-title-return"/> &#60;[Locator]&#62;<a href="#frame-locator-get-by-title-return" class="list-anchor">#</a>

Allows locating elements by their title. For example, this method will find the button by its title "Place the order":
Expand Down
Loading

0 comments on commit 3b46f1f

Please sign in to comment.