Перейти к основному содержимому

FrameLocator

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

Locator locator = page.locator("#my-frame").contentFrame().getByText("Submit");
locator.click();

Строгость

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

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

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

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

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

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

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

Methods​

frameLocator​

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

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

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

FrameLocator.frameLocator(selector);

Аргументы

  • selector String#

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

Возвращает

getByAltText​

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

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

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

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

<img alt='Playwright logo'>
page.getByAltText("Playwright logo").click();

Аргументы

  • text String | Pattern#

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

  • options FrameLocator.GetByAltTextOptions (опционально)

    • setExact boolean (опционально)#

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

Возвращает

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">
page.getByLabel("Username").fill("john");
page.getByLabel("Password").fill("secret");

Аргументы

  • text String | Pattern#

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

  • options FrameLocator.GetByLabelOptions (опционально)

    • setExact boolean (опционально)#

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

Возвращает

getByPlaceholder​

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

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

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

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

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

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

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

Аргументы

  • text String | Pattern#

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

  • options FrameLocator.GetByPlaceholderOptions (опционально)

    • setExact boolean (опционально)#

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

Возвращает

getByRole​

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

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

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

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

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

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

assertThat(page
    .getByRole(AriaRole.HEADING,
               new Page.GetByRoleOptions().setName("Sign up")))
    .isVisible();

page.getByRole(AriaRole.CHECKBOX,
               new Page.GetByRoleOptions().setName("Subscribe"))
    .check();

page.getByRole(AriaRole.BUTTON,
               new Page.GetByRoleOptions().setName(
                   Pattern.compile("submit", Pattern.CASE_INSENSITIVE)))
    .click();

Аргументы

  • 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 FrameLocator.GetByRoleOptions (опционально)

    • setChecked boolean (опционально)#

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

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

    • setDisabled boolean (опционально)#

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

      примечание

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

    • setExact boolean (опционально) Добавлено в: v1.28#

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

    • setExpanded boolean (опционально)#

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

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

    • setIncludeHidden boolean (опционально)#

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

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

    • setLevel int (опционально)#

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

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

    • setName String | Pattern (опционально)#

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

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

    • setPressed boolean (опционально)#

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

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

    • setSelected boolean (опционально)#

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

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

Возвращает

Детали

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

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

getByTestId​

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

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

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

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

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

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

page.getByTestId("directions").click();

Аргументы

  • testId String | Pattern#

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

Возвращает

Детали

По умолчанию используется атрибут 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 Page.GetByTextOptions().setExact(true));

// Соответствует обоим <div>
page.getByText(Pattern.compile("Hello"));

// Соответствует второму <div>
page.getByText(Pattern.compile("^hello$", Pattern.CASE_INSENSITIVE));

Аргументы

  • text String | Pattern#

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

  • options FrameLocator.GetByTextOptions (опционально)

    • setExact boolean (опционально)#

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

Возвращает

Детали

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

Элементы ввода типа 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>

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

assertThat(page.getByTitle("Issues count")).hasText("25 issues");

Аргументы

  • text String | Pattern#

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

  • options FrameLocator.GetByTitleOptions (опционально)

    • setExact boolean (опционально)#

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

Возвращает

locator​

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

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

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

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

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

Аргументы

  • selectorOrLocator String | Locator#

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

  • options FrameLocator.LocatorOptions (опционально)

    • setHas Locator (опционально)#

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

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

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

    • setHasNot Locator (опционально) Добавлено в: v1.33#

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

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

    • setHasNotText String | Pattern (опционально) Добавлено в: v1.33#

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

    • setHasText String | Pattern (опционально)#

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

Возвращает

owner​

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

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

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

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

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

FrameLocator frameLocator = page.locator("iframe[name=\"embedded\"]").contentFrame();
// ...
Locator locator = frameLocator.owner();
assertThat(locator).isVisible();

Возвращает

Deprecated​

first​

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

Используйте Locator.first() с последующим Locator.contentFrame() вместо этого.

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

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

FrameLocator.first();

Возвращает

last​

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

Используйте Locator.last() с последующим Locator.contentFrame() вместо этого.

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

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

FrameLocator.last();

Возвращает

nth​

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

Используйте Locator.nth() с последующим Locator.contentFrame() вместо этого.

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

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

FrameLocator.nth(index);

Аргументы

Возвращает