Skip to main content

FrameLocator

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

const locator = page.locator('#my-frame').contentFrame().getByText('Submit');
await locator.click();

Строгость

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

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

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

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

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

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

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

Методы​

frameLocator​

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

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

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

frameLocator.frameLocator(selector);

Аргументы

  • selector string#

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

Возвращает

getByAltText​

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

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

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

Например, этот метод найдет изображение по альтернативному тексту "Логотип Playwright":

<img alt='Логотип Playwright'>
await page.getByAltText('Логотип Playwright').click();

Аргументы

  • text string | RegExp#

    Текст для поиска элемента.

  • options Object (необязательно)

    • exact boolean (необязательно)#

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

Возвращает

getByLabel​

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

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

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

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

<input aria-label="Имя пользователя">
<label for="password-input">Пароль:</label>
<input id="password-input">
await page.getByLabel('Имя пользователя').fill('john');
await page.getByLabel('Пароль').fill('secret');

Аргументы

  • text string | RegExp#

    Текст для поиска элемента.

  • options Object (необязательно)

    • exact boolean (необязательно)#

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

Возвращает

getByPlaceholder​

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

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

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

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

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

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

await page
    .getByPlaceholder('name@example.com')
    .fill('playwright@microsoft.com');

Аргументы

  • text string | RegExp#

    Текст для поиска элемента.

  • options Object (необязательно)

    • exact boolean (необязательно)#

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

Возвращает

getByRole​

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

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

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

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

<h3>Подписаться</h3>
<label>
  <input type="checkbox" /> Подписаться
</label>
<br/>
<button>Отправить</button>

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

await expect(page.getByRole('heading', { name: 'Подписаться' })).toBeVisible();

await page.getByRole('checkbox', { name: 'Подписаться' }).check();

await page.getByRole('button', { name: /отправить/i }).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 роль.

  • options Object (необязательно)

    • checked boolean (необязательно)#

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

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

    • disabled boolean (необязательно)#

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

      note

      В отличие от большинства других атрибутов, disabled наследуется через иерархию DOM. Узнайте больше о aria-disabled.

    • exact boolean (необязательно) Добавлено в: v1.28#

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

    • expanded boolean (необязательно)#

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

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

    • includeHidden boolean (необязательно)#

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

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

    • level number (необязательно)#

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

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

    • name string | RegExp (необязательно)#

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

      Узнайте больше о доступном имени.

    • pressed boolean (необязательно)#

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

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

    • selected boolean (необязательно)#

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

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

Возвращает

Подробности

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

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

getByTestId​

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

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

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

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

<button data-testid="directions">Направление</button>

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

await page.getByTestId('directions').click();

Аргументы

  • testId string | RegExp#

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

Возвращает

Подробности

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

// Установите пользовательский атрибут тестового идентификатора из конфигурации @playwright/test:
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    testIdAttribute: 'data-pw'
  },
});

getByText​

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

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

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

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

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

<div>Привет <span>мир</span></div>
<div>Привет</div>

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

// Соответствует <span>
page.getByText('мир');

// Соответствует первому <div>
page.getByText('Привет мир');

// Соответствует второму <div>
page.getByText('Привет', { exact: true });

// Соответствует обоим <div>
page.getByText(/Привет/);

// Соответствует второму <div>
page.getByText(/^привет$/i);

Аргументы

  • text string | RegExp#

    Текст для поиска элемента.

  • options Object (необязательно)

    • exact boolean (необязательно)#

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

Возвращает

Подробности

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

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

getByTitle​

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

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

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

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

<span title='Количество проблем'>25 проблем</span>

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

await expect(page.getByTitle('Количество проблем')).toHaveText('25 проблем');

Аргументы

  • text string | RegExp#

    Текст для поиска элемента.

  • options Object (необязательно)

    • exact boolean (необязательно)#

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

Возвращает

locator​

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

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

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

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

frameLocator.locator(selectorOrLocator);
frameLocator.locator(selectorOrLocator, options);

Аргументы

  • selectorOrLocator string | Locator#

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

  • options Object (необязательно)

    • 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 string | RegExp (необязательно) Добавлено в: v1.33#

      Соответствует элементам, которые не содержат указанный текст где-либо внутри, возможно, в дочернем или потомственном элементе. При передаче [строки] совпадение нечувствительно к регистру и ищет подстроку.

    • hasText string | RegExp (необязательно)#

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

Возвращает

owner​

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

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

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

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

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

const frameLocator = page.locator('iframe[name="embedded"]').contentFrame();
// ...
const locator = frameLocator.owner();
await expect(locator).toBeVisible();

Возвращает

Устарело​

first​

Добавлено в: v1.17 frameLocator.first
Устарело

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

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

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

frameLocator.first();

Возвращает

last​

Добавлено в: v1.17 frameLocator.last
Устарело

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

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

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

frameLocator.last();

Возвращает

nth​

Добавлено в: v1.17 frameLocator.nth
Устарело

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

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

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

frameLocator.nth(index);

Аргументы

Возвращает