FrameLocator

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

Sync
Async

locator = page.locator("my-frame").content_frame.get_by_text("Submit")
locator.click()

locator = page.locator("#my-frame").content_frame.get_by_text("Submit")
await locator.click()

Строгость

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

Sync
Async

# Вызывает ошибку, если в DOM несколько фреймов:
page.locator('.result-frame').content_frame.get_by_role('button').click()

# Работает, потому что мы явно указываем локатору выбрать первый фрейм:
page.locator('.result-frame').first.content_frame.get_by_role('button').click()

# Вызывает ошибку, если в DOM несколько фреймов:
await page.locator('.result-frame').content_frame.get_by_role('button').click()

# Работает, потому что мы явно указываем локатору выбрать первый фрейм:
await page.locator('.result-frame').first.content_frame.get_by_role('button').click()

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

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

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

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

Методы

frame_locator

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

frameLocator.frame_locator

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

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

frame_locator.frame_locator(selector)

Аргументы

selector str #

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

Возвращает

FrameLocator #

get_by_alt_text

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

frameLocator.get_by_alt_text

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

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

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

<img alt='Playwright logo'>

Sync
Async

page.get_by_alt_text("Playwright logo").click()

await page.get_by_alt_text("Playwright logo").click()

Аргументы

text str | Pattern #

Текст для поиска элемента.
exact bool (опционально)#

Искать точное совпадение: с учетом регистра и целой строки. По умолчанию false. Игнорируется при поиске по регулярному выражению. Обратите внимание, что точное совпадение все равно обрезает пробелы.

Возвращает

Locator #

get_by_label

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

frameLocator.get_by_label

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

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

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

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

Sync
Async

page.get_by_label("Username").fill("john")
page.get_by_label("Password").fill("secret")

await page.get_by_label("Username").fill("john")
await page.get_by_label("Password").fill("secret")

Аргументы

text str | Pattern #

Текст для поиска элемента.
exact bool (опционально)#

Искать точное совпадение: с учетом регистра и целой строки. По умолчанию false. Игнорируется при поиске по регулярному выражению. Обратите внимание, что точное совпадение все равно обрезает пробелы.

Возвращает

Locator #

get_by_placeholder

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

frameLocator.get_by_placeholder

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

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

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

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

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

Sync
Async

page.get_by_placeholder("name@example.com").fill("playwright@microsoft.com")

await page.get_by_placeholder("name@example.com").fill("playwright@microsoft.com")

Аргументы

text str | Pattern #

Текст для поиска элемента.
exact bool (опционально)#

Искать точное совпадение: с учетом регистра и целой строки. По умолчанию false. Игнорируется при поиске по регулярному выражению. Обратите внимание, что точное совпадение все равно обрезает пробелы.

Возвращает

Locator #

get_by_role

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

frameLocator.get_by_role

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

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

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

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

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

Sync
Async

expect(page.get_by_role("heading", name="Sign up")).to_be_visible()

page.get_by_role("checkbox", name="Subscribe").check()

page.get_by_role("button", name=re.compile("submit", re.IGNORECASE)).click()

await expect(page.get_by_role("heading", name="Sign up")).to_be_visible()

await page.get_by_role("checkbox", name="Subscribe").check()

await page.get_by_role("button", name=re.compile("submit", re.IGNORECASE)).click()

Аргументы

role "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 роль.
checked bool (опционально)#

Атрибут, который обычно устанавливается aria-checked или нативными <input type=checkbox> контролами.

Узнайте больше о aria-checked.
disabled bool (опционально)#

Атрибут, который обычно устанавливается aria-disabled или disabled.

примечание
В отличие от большинства других атрибутов, disabled наследуется через иерархию DOM. Узнайте больше о aria-disabled.
exact bool (опционально) Добавлено в: v1.28#

Совпадает ли name точно: с учетом регистра и целой строки. По умолчанию false. Игнорируется, когда name является регулярным выражением. Обратите внимание, что точное совпадение все равно обрезает пробелы.
expanded bool (опционально)#

Атрибут, который обычно устанавливается aria-expanded.

Узнайте больше о aria-expanded.
include_hidden bool (опционально)#

Опция, которая контролирует, соответствуют ли скрытые элементы. По умолчанию, только не скрытые элементы, как определено ARIA, соответствуют селектору роли.

Узнайте больше о aria-hidden.
level int (опционально)#

Числовой атрибут, который обычно присутствует для ролей heading, listitem, row, treeitem, с значениями по умолчанию для элементов <h1>-<h6>.

Узнайте больше о aria-level.
name str | Pattern (опционально)#

Опция для сопоставления доступного имени. По умолчанию, сопоставление не учитывает регистр и ищет подстроку, используйте exact для управления этим поведением.

Узнайте больше о доступном имени.
pressed bool (опционально)#

Атрибут, который обычно устанавливается aria-pressed.

Узнайте больше о aria-pressed.
selected bool (опционально)#

Атрибут, который обычно устанавливается aria-selected.

Узнайте больше о aria-selected.

Возвращает

Locator #

Детали

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

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

get_by_test_id

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

frameLocator.get_by_test_id

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

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

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

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

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

Sync
Async

page.get_by_test_id("directions").click()

await page.get_by_test_id("directions").click()

Аргументы

test_id str | Pattern #

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

Возвращает

Locator #

Детали

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

get_by_text

Added in: v1.27

frameLocator.get_by_text

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

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

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

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

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

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

Sync
Async

# Соответствует <span>
page.get_by_text("world")

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

# Соответствует второму <div>
page.get_by_text("Hello", exact=True)

# Соответствует обоим <div>
page.get_by_text(re.compile("Hello"))

# Соответствует второму <div>
page.get_by_text(re.compile("^hello$", re.IGNORECASE))

# Соответствует <span>
page.get_by_text("world")

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

# Соответствует второму <div>
page.get_by_text("Hello", exact=True)

# Соответствует обоим <div>
page.get_by_text(re.compile("Hello"))

# Соответствует второму <div>
page.get_by_text(re.compile("^hello$", re.IGNORECASE))

Аргументы

text str | Pattern #

Текст для поиска элемента.
exact bool (optional)#

Искать точное совпадение: с учетом регистра и всей строки. По умолчанию false. Игнорируется при поиске по регулярному выражению. Обратите внимание, что точное совпадение все равно обрезает пробелы.

Возвращает

Locator #

Детали

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

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

get_by_title

Added in: v1.27

frameLocator.get_by_title

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

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

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

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

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

Sync
Async

expect(page.get_by_title("Issues count")).to_have_text("25 issues")

await expect(page.get_by_title("Issues count")).to_have_text("25 issues")

Аргументы

text str | Pattern #

Текст для поиска элемента.
exact bool (optional)#

Искать точное совпадение: с учетом регистра и всей строки. По умолчанию false. Игнорируется при поиске по регулярному выражению. Обратите внимание, что точное совпадение все равно обрезает пробелы.

Возвращает

Locator #

locator

Added in: v1.17

frameLocator.locator

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

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

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

frame_locator.locator(selector_or_locator)
frame_locator.locator(selector_or_locator, **kwargs)

Аргументы

selector_or_locator str | Locator #

Селектор или локатор для использования при разрешении DOM элемента.
has Locator (optional)#

Сужает результаты метода до тех, которые содержат элементы, соответствующие этому относительному локатору. Например, article, который имеет text=Playwright, соответствует <article><div>Playwright</div></article>.

Внутренний локатор должен быть относительным к внешнему локатору и запрашивается, начиная с совпадения внешнего локатора, а не с корня документа. Например, вы можете найти content, который имеет div в <article><content><div>Playwright</div></content></article>. Однако поиск content, который имеет article div, не удастся, потому что внутренний локатор должен быть относительным и не должен использовать элементы за пределами content.

Обратите внимание, что внешние и внутренние локаторы должны принадлежать одному и тому же фрейму. Внутренний локатор не должен содержать FrameLocators.
has_not Locator (optional) Added in: v1.33#

Соответствует элементам, которые не содержат элемент, соответствующий внутреннему локатору. Внутренний локатор запрашивается относительно внешнего. Например, article, который не имеет div, соответствует <article><span>Playwright</span></article>.

Обратите внимание, что внешние и внутренние локаторы должны принадлежать одному и тому же фрейму. Внутренний локатор не должен содержать FrameLocators.
has_not_text str | Pattern (optional) Added in: v1.33#

Соответствует элементам, которые не содержат указанный текст где-то внутри, возможно, в дочернем или потомке элемента. При передаче [строки] сопоставление нечувствительно к регистру и ищет подстроку.
has_text str | Pattern (optional)#

Соответствует элементам, содержащим указанный текст где-то внутри, возможно, в дочернем или потомке элемента. При передаче [строки] сопоставление нечувствительно к регистру и ищет подстроку. Например, "Playwright" соответствует <article><div>Playwright</div></article>.

Возвращает

Locator #

Свойства

owner

Added in: v1.43

frameLocator.owner

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

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

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

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

Sync
Async

frame_locator = page.locator("iframe[name=\"embedded\"]").content_frame
# ...
locator = frame_locator.owner
expect(locator).to_be_visible()

frame_locator = page.locator("iframe[name=\"embedded\"]").content_frame
# ...
locator = frame_locator.owner
await expect(locator).to_be_visible()

Возвращает

Locator #

Устаревшие

first

Added in: v1.17

frameLocator.first

Устарело

Используйте locator.first, а затем locator.content_frame.

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

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

frame_locator.first

Возвращает

FrameLocator #

last

Added in: v1.17

frameLocator.last

Устарело

Используйте locator.last, а затем locator.content_frame.

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

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

frame_locator.last

Возвращает

FrameLocator #

nth

Added in: v1.17

frameLocator.nth

Устарело

Используйте locator.nth(), а затем locator.content_frame.

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

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

frame_locator.nth(index)

Аргументы

index int #

Возвращает

FrameLocator #

Методы​

frame_locator​

get_by_alt_text​

get_by_label​

get_by_placeholder​

get_by_role​

get_by_test_id​

get_by_text​

get_by_title​

locator​

Свойства​

owner​

Устаревшие​

first​

last​

nth​

Методы

frame_locator

get_by_alt_text

get_by_label

get_by_placeholder

get_by_role

get_by_test_id

get_by_text

get_by_title

locator

Свойства

owner

Устаревшие

first

last

nth