FrameLocator

FrameLocator представляет собой представление iframe на странице. Он захватывает логику, достаточную для получения iframe и поиска элементов в этом iframe. FrameLocator может быть создан с помощью методов Locator.ContentFrame, Page.FrameLocator() или Locator.FrameLocator().

var locator = page.Locator("#my-frame").ContentFrame.GetByText("Submit");
await locator.ClickAsync();

Строгость

Локаторы фреймов являются строгими. Это означает, что все операции с локаторами фреймов будут вызывать ошибку, если более одного элемента соответствует заданному селектору.

// Вызывает ошибку, если в DOM несколько фреймов:
await page.Locator(".result-frame").ContentFrame.GetByRole(AriaRole.Button).ClickAsync();

// Работает, потому что мы явно указываем локатору выбрать первый фрейм:
await page.Locator(".result-frame").First.ContentFrame.getByRole(AriaRole.Button).ClickAsync();

Преобразование Locator в FrameLocator

Если у вас есть объект Locator, указывающий на iframe, его можно преобразовать в FrameLocator с помощью Locator.ContentFrame.

Преобразование FrameLocator в Locator

Если у вас есть объект FrameLocator, его можно преобразовать в Locator, указывающий на тот же iframe, с помощью FrameLocator.Owner.

Методы

FrameLocator

Добавлено в: v1.17

frameLocator.FrameLocator

При работе с iframes вы можете создать локатор фрейма, который войдет в iframe и позволит выбирать элементы в этом iframe.

Использование

FrameLocator.FrameLocator(selector);

Аргументы

selector string #

Селектор для использования при разрешении элемента DOM.

Возвращает

FrameLocator #

GetByAltText

Добавлено в: v1.27

frameLocator.GetByAltText

Позволяет находить элементы по их alt-тексту.

Использование

Например, этот метод найдет изображение по alt-тексту "Playwright logo":

<img alt='Playwright logo'>

await page.GetByAltText("Playwright logo").ClickAsync();

Аргументы

text string | Regex #

Текст для поиска элемента.
options FrameLocatorGetByAltTextOptions? (опционально)
- Exact bool? (опционально)#
  
  Искать точное совпадение: с учетом регистра и всей строки. По умолчанию false. Игнорируется при поиске по регулярному выражению. Обратите внимание, что точное совпадение все равно обрезает пробелы.

Возвращает

Locator #

GetByLabel

Добавлено в: v1.27

frameLocator.GetByLabel

Позволяет находить элементы ввода по тексту связанного элемента <label> или элемента с aria-labelledby, или по атрибуту aria-label.

Использование

Например, этот метод найдет поля ввода по меткам "Username" и "Password" в следующем DOM:

<input aria-label="Username">
<label for="password-input">Password:</label>
<input id="password-input">

await page.GetByLabel("Username").FillAsync("john");
await page.GetByLabel("Password").FillAsync("secret");

Аргументы

text string | Regex #

Текст для поиска элемента.
options FrameLocatorGetByLabelOptions? (опционально)
- Exact bool? (опционально)#
  
  Искать точное совпадение: с учетом регистра и всей строки. По умолчанию false. Игнорируется при поиске по регулярному выражению. Обратите внимание, что точное совпадение все равно обрезает пробелы.

Возвращает

Locator #

GetByPlaceholder

Добавлено в: v1.27

frameLocator.GetByPlaceholder

Позволяет находить элементы ввода по тексту-заполнителю.

Использование

Например, рассмотрим следующую структуру DOM.

<input type="email" placeholder="name@example.com" />

Вы можете заполнить поле ввода, найдя его по тексту-заполнителю:

await page
    .GetByPlaceholder("name@example.com")
    .FillAsync("playwright@microsoft.com");

Аргументы

text string | Regex #

Текст для поиска элемента.
options FrameLocatorGetByPlaceholderOptions? (опционально)
- Exact bool? (опционально)#
  
  Искать точное совпадение: с учетом регистра и всей строки. По умолчанию false. Игнорируется при поиске по регулярному выражению. Обратите внимание, что точное совпадение все равно обрезает пробелы.

Возвращает

Locator #

GetByRole

Добавлено в: v1.27

frameLocator.GetByRole

Позволяет находить элементы по их ARIA роли, ARIA атрибутам и доступному имени.

Использование

Рассмотрим следующую структуру DOM.

<h3>Sign up</h3>
<label>
  <input type="checkbox" /> Subscribe
</label>
<br/>
<button>Submit</button>

Вы можете найти каждый элемент по его неявной роли:

await Expect(Page
    .GetByRole(AriaRole.Heading, new() { Name = "Sign up" }))
    .ToBeVisibleAsync();

await page
    .GetByRole(AriaRole.Checkbox, new() { Name = "Subscribe" })
    .CheckAsync();

await page
    .GetByRole(AriaRole.Button, new() {
        NameRegex = new Regex("submit", RegexOptions.IgnoreCase)
    })
    .ClickAsync();

Аргументы

role enum AriaRole { Alert, Alertdialog, Application, Article, Banner, Blockquote, Button, Caption, Cell, Checkbox, Code, Columnheader, Combobox, Complementary, Contentinfo, Definition, Deletion, Dialog, Directory, Document, Emphasis, Feed, Figure, Form, Generic, Grid, Gridcell, Group, Heading, Img, Insertion, Link, List, Listbox, Listitem, Log, Main, Marquee, Math, Meter, Menu, Menubar, Menuitem, Menuitemcheckbox, Menuitemradio, Navigation, None, Note, Option, Paragraph, Presentation, Progressbar, Radio, Radiogroup, Region, Row, Rowgroup, Rowheader, Scrollbar, Search, Searchbox, Separator, Slider, Spinbutton, Status, Strong, Subscript, Superscript, Switch, Tab, Table, Tablist, Tabpanel, Term, Textbox, Time, Timer, Toolbar, Tooltip, Tree, Treegrid, Treeitem }#

Требуемая ARIA роль.
options FrameLocatorGetByRoleOptions? (опционально)
- Checked bool? (опционально)#
  
  Атрибут, который обычно устанавливается с помощью aria-checked или нативных <input type=checkbox> контролов.
  
  Узнайте больше о aria-checked.
- Disabled bool? (опционально)#
  
  Атрибут, который обычно устанавливается с помощью aria-disabled или disabled.
  
  примечание
  В отличие от большинства других атрибутов, disabled наследуется через иерархию DOM. Узнайте больше о aria-disabled.
- Exact bool? (опционально) Добавлено в: v1.28#
  
  Совпадает ли Name|NameRegex точно: с учетом регистра и всей строки. По умолчанию false. Игнорируется, когда Name|NameRegex является регулярным выражением. Обратите внимание, что точное совпадение все равно обрезает пробелы.
- Expanded bool? (опционально)#
  
  Атрибут, который обычно устанавливается с помощью aria-expanded.
  
  Узнайте больше о aria-expanded.
- IncludeHidden bool? (опционально)#
  
  Опция, которая контролирует, соответствуют ли скрытые элементы. По умолчанию, только не скрытые элементы, как определено ARIA, соответствуют селектору роли.
  
  Узнайте больше о aria-hidden.
- Level int? (опционально)#
  
  Числовой атрибут, который обычно присутствует для ролей heading, listitem, row, treeitem, с значениями по умолчанию для элементов <h1>-<h6>.
  
  Узнайте больше о aria-level.
- Name|NameRegex string? | Regex? (опционально)#
  
  Опция для соответствия доступному имени. По умолчанию, соответствие не учитывает регистр и ищет подстроку, используйте Exact для управления этим поведением.
  
  Узнайте больше о доступном имени.
- Pressed bool? (опционально)#
  
  Атрибут, который обычно устанавливается с помощью aria-pressed.
  
  Узнайте больше о aria-pressed.
- Selected bool? (опционально)#
  
  Атрибут, который обычно устанавливается с помощью aria-selected.
  
  Узнайте больше о aria-selected.

Возвращает

Locator #

Детали

Селектор роли не заменяет аудиты доступности и тесты на соответствие, но дает раннюю обратную связь о рекомендациях ARIA.

Многие HTML-элементы имеют неявно определенную роль, которая распознается селектором роли. Вы можете найти все поддерживаемые роли здесь. Рекомендации ARIA не рекомендуют дублировать неявные роли и атрибуты, устанавливая role и/или aria-* атрибуты на значения по умолчанию.

GetByTestId

Добавлено в: v1.27

frameLocator.GetByTestId

Находит элемент по тестовому идентификатору.

Использование

Рассмотрим следующую структуру DOM.

<button data-testid="directions">Itinéraire</button>

Вы можете найти элемент по его тестовому идентификатору:

await page.GetByTestId("directions").ClickAsync();

Аргументы

testId string | Regex #

Идентификатор для поиска элемента.

Возвращает

Locator #

Детали

По умолчанию атрибут data-testid используется как тестовый идентификатор. Используйте Selectors.SetTestIdAttribute(), чтобы настроить другой атрибут тестового идентификатора, если это необходимо.

GetByText

Добавлено в: v1.27

frameLocator.GetByText

Позволяет находить элементы, содержащие заданный текст.

Смотрите также Locator.Filter(), который позволяет сопоставлять по другим критериям, таким как доступная роль, а затем фильтровать по текстовому содержимому.

Использование

Рассмотрим следующую структуру DOM:

<div>Hello <span>world</span></div>
<div>Hello</div>

Вы можете найти по подстроке текста, точной строке или регулярному выражению:

// Соответствует <span>
page.GetByText("world");

// Соответствует первому <div>
page.GetByText("Hello world");

// Соответствует второму <div>
page.GetByText("Hello", new() { Exact = true });

// Соответствует обоим <div>
page.GetByText(new Regex("Hello"));

// Соответствует второму <div>
page.GetByText(new Regex("^hello$", RegexOptions.IgnoreCase));

Аргументы

text string | Regex #

Текст для поиска элемента.
options FrameLocatorGetByTextOptions? (опционально)
- Exact bool? (опционально)#
  
  Искать точное совпадение: с учетом регистра и всей строки. По умолчанию false. Игнорируется при поиске по регулярному выражению. Обратите внимание, что точное совпадение все равно обрезает пробелы.

Возвращает

Locator #

Детали

Сопоставление по тексту всегда нормализует пробелы, даже при точном совпадении. Например, оно превращает несколько пробелов в один, превращает разрывы строк в пробелы и игнорирует начальные и конечные пробелы.

Элементы ввода типа button и submit сопоставляются по их value, а не по текстовому содержимому. Например, поиск по тексту "Log in" соответствует <input type=button value="Log in">.

GetByTitle

Добавлено в: v1.27

frameLocator.GetByTitle

Позволяет находить элементы по их атрибуту title.

Использование

Рассмотрим следующую структуру DOM.

<span title='Issues count'>25 issues</span>

Вы можете проверить количество проблем, найдя его по тексту заголовка:

await Expect(Page.GetByTitle("Issues count")).toHaveText("25 issues");

Аргументы

text string | Regex #

Текст для поиска элемента.
options FrameLocatorGetByTitleOptions? (опционально)
- Exact bool? (опционально)#
  
  Искать точное совпадение: с учетом регистра и всей строки. По умолчанию false. Игнорируется при поиске по регулярному выражению. Обратите внимание, что точное совпадение все равно обрезает пробелы.

Возвращает

Locator #

Locator

Добавлено в: v1.17

frameLocator.Locator

Метод находит элемент, соответствующий указанному селектору в поддереве локатора. Он также принимает параметры фильтрации, аналогичные методу Locator.Filter().

Узнайте больше о локаторах.

Использование

FrameLocator.Locator(selectorOrLocator, options);

Аргументы

selectorOrLocator string | Locator #

Селектор или локатор для использования при разрешении элемента DOM.
options FrameLocatorLocatorOptions? (опционально)
- Has Locator? (опционально)#
  
  Сужает результаты метода до тех, которые содержат элементы, соответствующие этому относительному локатору. Например, article, который имеет text=Playwright, соответствует <article><div>Playwright</div></article>.
  
  Внутренний локатор должен быть относительным к внешнему локатору и запрашивается, начиная с совпадения внешнего локатора, а не с корня документа. Например, вы можете найти content, который имеет div в <article><content><div>Playwright</div></content></article>. Однако поиск content, который имеет article div, не удастся, потому что внутренний локатор должен быть относительным и не должен использовать элементы за пределами content.
  
  Обратите внимание, что внешние и внутренние локаторы должны принадлежать одному и тому же фрейму. Внутренний локатор не должен содержать FrameLocators.
- HasNot Locator? (опционально) Добавлено в: v1.33#
  
  Соответствует элементам, которые не содержат элемента, соответствующего внутреннему локатору. Внутренний локатор запрашивается относительно внешнего. Например, article, который не имеет div, соответствует <article><span>Playwright</span></article>.
  
  Обратите внимание, что внешние и внутренние локаторы должны принадлежать одному и тому же фрейму. Внутренний локатор не должен содержать FrameLocators.
- HasNotText|HasNotTextRegex string? | Regex? (опционально) Добавлено в: v1.33#
  
  Соответствует элементам, которые не содержат указанный текст где-либо внутри, возможно, в дочернем или потомке. При передаче string соответствие не учитывает регистр и ищет подстроку.
- HasText|HasTextRegex string? | Regex? (опционально)#
  
  Соответствует элементам, содержащим указанный текст где-либо внутри, возможно, в дочернем или потомке. При передаче string соответствие не учитывает регистр и ищет подстроку. Например, "Playwright" соответствует <article><div>Playwright</div></article>.

Возвращает

Locator #

Owner

Добавлено в: v1.43

frameLocator.Owner

Возвращает объект Locator, указывающий на тот же iframe, что и этот локатор фрейма.

Полезно, когда у вас есть объект FrameLocator, полученный где-то, и позже вы хотите взаимодействовать с элементом iframe.

Для обратной операции используйте Locator.ContentFrame.

Использование

var frameLocator = Page.Locator("iframe[name=\"embedded\"]").ContentFrame;
// ...
var locator = frameLocator.Owner;
await Expect(locator).ToBeVisibleAsync();

Возвращает

Locator #

Устаревшие

First

Добавлено в: v1.17

frameLocator.First

Устарело

Используйте Locator.First, а затем Locator.ContentFrame вместо этого.

Возвращает локатор к первому совпадающему фрейму.

Использование

FrameLocator.First

Возвращает

FrameLocator #

Last

Добавлено в: v1.17

frameLocator.Last

Устарело

Используйте Locator.Last, а затем Locator.ContentFrame вместо этого.

Возвращает локатор к последнему совпадающему фрейму.

Использование

FrameLocator.Last

Возвращает

FrameLocator #

Nth

Добавлено в: v1.17

frameLocator.Nth

Устарело

Используйте Locator.Nth(), а затем Locator.ContentFrame вместо этого.

Возвращает локатор к n-му совпадающему фрейму. Нумерация начинается с нуля, nth(0) выбирает первый фрейм.

Использование

FrameLocator.Nth(index);

Аргументы

index int #

Возвращает

FrameLocator #

Методы​

FrameLocator​

GetByAltText​

GetByLabel​

GetByPlaceholder​

GetByRole​

GetByTestId​

GetByText​

GetByTitle​

Locator​

Owner​

Устаревшие​

First​

Last​

Nth​

Методы

FrameLocator

GetByAltText

GetByLabel

GetByPlaceholder

GetByRole

GetByTestId

GetByText

GetByTitle

Locator

Owner

Устаревшие

First

Last

Nth