FrameLocator

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

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

Строгий режим

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

// Throws if there are several frames in DOM:
await page.locator('.result-frame').contentFrame().getByRole('button').click();

// Works because we explicitly tell locator to pick the first frame:
await page.locator('.result-frame').contentFrame().first().getByRole('button').click();

Любой фрейм

Вызов page.frameLocator() или frame.frameLocator() без селектора создаёт локатор фрейма, который начинает поиск в любом фрейме поддерева, поэтому сначала искать iframe не нужно.

// Finds the button in any frame on the page:
await page.frameLocator().getByRole('button').click();

// Finds the iframe with id "my-frame" anywhere on the page, and clicks the button inside it:
await page.frameLocator().locator('#my-frame').contentFrame().getByRole('button').click();

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

Такой локатор фрейма не указывает на определённый iframe, поэтому для него не поддерживаются методы frameLocator.owner(), frameLocator.first(), frameLocator.last() и frameLocator.nth().

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

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

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

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

Методы​

frameLocator​

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

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

frameLocator.frameLocator(selector);

Аргументы

• selector string

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

Возвращает

• FrameLocator

getByAltText​

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

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

Например, этот метод найдёт изображение по тексту alt «Логотип Playwright»:

<img alt='Playwright logo'>

await page.getByAltText('Playwright logo').click();

Аргументы

• text string | RegExp

  Текст, по которому нужно найти элемент.

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

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

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

Возвращает

• Locator

getByLabel​

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

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

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

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

await page.getByLabel('Username').fill('john');
await page.getByLabel('Password').fill('secret');

Аргументы

• text string | RegExp

  Текст, по которому нужно найти элемент.

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

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

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

Возвращает

• Locator

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. Не учитывается при поиске по регулярному выражению. Обратите внимание: при точном совпадении пробелы всё равно обрезаются.

Возвращает

• Locator

getByRole​

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

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

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

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

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

await expect(page.getByRole('heading', { name: 'Sign up' })).toBeVisible();

await page.getByRole('checkbox', { name: 'Subscribe' }).check();

await page.getByRole('button', { name: /submit/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.

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

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

    Подробнее о доступном описании.

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

    Атрибут, который обычно задаётся элементом aria-disabled или disabled.

    примечание

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

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

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

  • 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.

Возвращает

• Locator

Подробности

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

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

getByTestId​

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

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

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

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

Элемент можно найти по его идентификатору теста:

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

Аргументы

• testId string | RegExp

  Идентификатор элемента, по которому нужно выполнить поиск.

Возвращает

• Locator

Подробности

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

// Set custom test id attribute from @playwright/test config:
import { defineConfig } from '@playwright/test';

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

getByText​

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

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

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

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

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

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

// Matches <span>
page.getByText('world');

// Matches first <div>
page.getByText('Hello world');

// Matches second <div>
page.getByText('Hello', { exact: true });

// Matches both <div>s
page.getByText(/Hello/);

// Matches second <div>
page.getByText(/^hello$/i);

Аргументы

• text string | RegExp

  Текст, по которому нужно найти элемент.

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

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

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

Возвращает

• Locator

Подробности

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

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

getByTitle​

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

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

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

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

После поиска по тексту атрибута title можно проверить количество проблем:

await expect(page.getByTitle('Issues count')).toHaveText('25 issues');

Аргументы

• text string | RegExp

  Текст, по которому нужно найти элемент.

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

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

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

Возвращает

• Locator

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.

    Обратите внимание, что внешний и внутренний локаторы должны принадлежать одному фрейму. Внутренний локатор не должен содержать FrameLocator.

  • hasNot Locator (необязательно)

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

    Обратите внимание, что внешний и внутренний локаторы должны принадлежать одному фрейму. Внутренний локатор не должен содержать FrameLocator.

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

    Находит элементы, не содержащие указанный текст где-либо внутри, в том числе в дочернем или вложенном элементе. Если передана строка string, поиск подстроки не учитывает регистр.

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

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

Возвращает

• Locator

owner​

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

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

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

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

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

Возвращает

• Locator

Устаревшие методы​

first​

Устарело

Вместо этого используйте locator.first(), а затем locator.contentFrame().

Возвращает локатор первого подходящего фрейма.

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

frameLocator.first();

Возвращает

• FrameLocator

last​

Устарело

Вместо этого используйте locator.last(), а затем locator.contentFrame().

Возвращает локатор последнего подходящего фрейма.

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

frameLocator.last();

Возвращает

• FrameLocator

nth​

Устарело

Вместо этого используйте locator.nth(), а затем locator.contentFrame().

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

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

frameLocator.nth(index);

Аргументы

• index number

Возвращает

• FrameLocator