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

Locator

Локаторы являются центральной частью автоматического ожидания и возможности повторных попыток в Playwright. Вкратце, локаторы представляют собой способ найти элемент(ы) на странице в любой момент. Локатор можно создать с помощью метода page.locator().

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


Методы​

all​

Добавлено в: v1.29 locator.all

Когда локатор указывает на список элементов, этот метод возвращает массив локаторов, указывающих на соответствующие элементы.

примечание

locator.all() не ждет, пока элементы соответствуют локатору, и вместо этого немедленно возвращает то, что присутствует на странице.

Когда список элементов изменяется динамически, locator.all() будет давать непредсказуемые и нестабильные результаты.

Когда список элементов стабилен, но загружается динамически, дождитесь полной загрузки списка перед вызовом locator.all().

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

for (const li of await page.getByRole('listitem').all())
await li.click();

Возвращает


allInnerTexts​

Добавлено в: v1.14 locator.allInnerTexts

Возвращает массив значений node.innerText для всех соответствующих узлов.

Проверка текста

Если вам нужно проверить текст на странице, предпочтите expect(locator).toHaveText() с опцией useInnerText, чтобы избежать нестабильности. Подробнее см. в руководстве по проверкам.

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

const texts = await page.getByRole('link').allInnerTexts();

Возвращает


allTextContents​

Добавлено в: v1.14 locator.allTextContents

Возвращает массив значений node.textContent для всех соответствующих узлов.

Проверка текста

Если вам нужно проверить текст на странице, предпочтите expect(locator).toHaveText(), чтобы избежать нестабильности. Подробнее см. в руководстве по проверкам.

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

const texts = await page.getByRole('link').allTextContents();

Возвращает


and​

Добавлено в: v1.34 locator.and

Создает локатор, который соответствует как этому локатору, так и аргументу локатора.

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

Следующий пример находит кнопку с определенным заголовком.

const button = page.getByRole('button').and(page.getByTitle('Subscribe'));

Аргументы

  • locator Locator#

    Дополнительный локатор для соответствия.

Возвращает


ariaSnapshot​

Добавлено в: v1.49 locator.ariaSnapshot

Создает снимок aria для данного элемента. Подробнее о снимках aria и expect(locator).toMatchAriaSnapshot() для соответствующей проверки.

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

await page.getByRole('link').ariaSnapshot();

Аргументы

  • options Object (необязательно)
    • boxes boolean (необязательно) Добавлено в: v1.60#

      Если установлено значение true, добавляет к снимку ограничивающий прямоугольник каждого элемента в формате [box=x,y,width,height]. Координаты задаются относительно области просмотра в CSS-пикселях, как их возвращает метод Element.getBoundingClientRect(). По умолчанию — false.

    • depth number (необязательно) Добавлено в: v1.59#

      Если параметр указан, ограничивает глубину снимка.

    • mode "ai" | "default" (необязательно) Добавлено в: v1.59#

      Если установлено значение "ai", возвращает снимок, оптимизированный для обработки искусственным интеллектом. По умолчанию — "default". Дополнительную информацию см. в подробном описании.

    • signal AbortSignal (необязательно) Добавлено в: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и будет выброшена ошибка. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

      Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью опции actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

Детали

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

Снимок ARIA представлен с использованием языка разметки YAML:

  • Ключи объектов - это роли и необязательные доступные имена элементов.
  • Значения - это либо текстовое содержимое, либо массив дочерних элементов.
  • Общий статический текст может быть представлен с помощью ключа text.

Ниже приведена HTML-разметка и соответствующий снимок ARIA:

<ul aria-label="Links">
<li><a href="/">Home</a></li>
<li><a href="/about">About</a></li>
<ul>
- list "Links":
- listitem:
- link "Home"
- listitem:
- link "About"

Снимок, оптимизированный для ИИ и управляемый параметром mode, отличается от снимка по умолчанию:

  1. Включает идентификаторы элементов, например [ref=e2].
  2. Не ждёт появления элемента, соответствующего локатору, и выбрасывает исключение, если совпадений нет.
  3. Включает снимки <iframe> внутри целевого элемента.
  4. Может опускать имена, повторяющие содержимое дочерних элементов в снимке, например имя заголовка со ссылкой. Имена диалогов, ориентиров, групп, таблиц и заголовков таблиц сохраняются.

ariaSnapshotJSON​

Добавлено в: v1.63 locator.ariaSnapshotJSON

Сохраняет снимок дерева доступности указанного элемента в виде объекта JSON.

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

await page.getByRole('list').ariaSnapshotJSON();

Аргументы

  • options Object (optional)
    • boxes boolean (optional)#

      При значении true добавляет к каждому элементу свойство box с полями x, y, width и height. Координаты относительно области просмотра измеряются в CSS-пикселях и возвращаются методом Element.getBoundingClientRect(). По умолчанию false.

    • depth number (optional)#

      Если указан, ограничивает глубину снимка.

    • mode "ai" | "default" (optional)#

      При значении "ai" возвращает снимок, оптимизированный для ИИ. По умолчанию "default". Подробнее см. locator.ariaSnapshot().

    • signal AbortSignal (необязательно) Added in: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. При отмене операция прерывается и выбрасывает ошибку. Сигнал не отключает тайм-аут по умолчанию. Его можно изменить методами browserContext.setDefaultTimeout() или page.setDefaultTimeout().

    • timeout number (optional)#

      Максимальное время в миллисекундах. По умолчанию 0, то есть тайм-аут отключён. Значение можно изменить параметром actionTimeout в конфигурации или методами browserContext.setDefaultTimeout() и page.setDefaultTimeout().

Возвращает

Подробности

Метод возвращает то же дерево, что и locator.ariaSnapshot(), в виде JSON вместо YAML. Результат представляет собой список узлов. Каждый узел — объект со следующими свойствами:

  • role — роль ARIA элемента или "text" для статического фрагмента текста.
  • name — доступное имя элемента, если оно задано.
  • text — текст элемента, если это его единственный потомок, или содержимое статического фрагмента текста.
  • children — дочерние узлы и фрагменты текста.
  • Логические и числовые свойства состояния элемента: checked, disabled, expanded, active, invalid, level, pressed и selected.
  • Дополнительные свойства элемента, например url для ссылок и placeholder для текстовых полей.
  • ref — идентификатор элемента в снимках, оптимизированных для ИИ.
  • cursor — значение "pointer" для кликабельных элементов в снимках, оптимизированных для ИИ.
  • box — ограничивающий прямоугольник элемента, если задан параметр boxes.

blur​

Добавлено в: v1.28 locator.blur

Вызывает blur на элементе.

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

await locator.blur();
await locator.blur(options);

Аргументы

  • options Object (необязательно)
    • signal AbortSignal (необязательно) Добавлено в: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отмены сработает, операция будет прервана и будет выброшено исключение. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

      Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью опции actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает


boundingBox​

Добавлено в: v1.14 locator.boundingBox

Этот метод возвращает ограничивающий прямоугольник элемента, соответствующего локатору, или null, если элемент не виден. Ограничивающий прямоугольник рассчитывается относительно области просмотра основного фрейма - обычно это то же самое, что и окно браузера.

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

const box = await page.getByRole('button').boundingBox();
await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);

Аргументы

  • options Object (необязательно)
    • signal AbortSignal (необязательно) Добавлено в: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана с выбросом ошибки. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

      Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью опции actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

  • Promise<null | Object>#
    • x number

      координата x элемента в пикселях.

    • y number

      координата y элемента в пикселях.

    • width number

      ширина элемента в пикселях.

    • height number

      высота элемента в пикселях.

Детали

Прокрутка влияет на возвращаемый ограничивающий прямоугольник, аналогично Element.getBoundingClientRect. Это означает, что x и/или y могут быть отрицательными.

Элементы из дочерних фреймов возвращают ограничивающий прямоугольник относительно основного фрейма, в отличие от Element.getBoundingClientRect.

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


check​

Добавлено в: v1.14 locator.check

Убедитесь, что элемент checkbox или radio установлен.

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

await page.getByRole('checkbox').check();

Аргументы

  • options Object (опционально)
    • force boolean (опционально)#

      Следует ли обходить проверки actionability. По умолчанию false.

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

      Устарело

      Этот параметр не имеет эффекта.

      Этот параметр не имеет эффекта.

    • position Object (опционально)#

Точка относительно верхнего левого угла области элемента, включающей внутренние отступы (padding box). Если не указана, используется одна из видимых точек элемента.

  • scroll "auto" | "none" (необязательно) Добавлено в: v1.62#

    Определяет, прокручивает ли Playwright страницу, чтобы элемент оказался в области видимости, перед выполнением действия. По умолчанию используется "auto": при необходимости выполняется прокрутка, чтобы элемент оказался в области видимости, в том числе прокрутка вложенных прокручиваемых контейнеров. При значении "none" Playwright не выполняет прокрутку, и действие завершается ошибкой, если элемент ещё не находится в области просмотра. Это полезно для проверки того, что элемент доступен пользователю без дополнительной прокрутки.

  • signal AbortSignal (необязательно) Добавлено в: v1.62#

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и будет выброшена ошибка. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

    Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

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

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

Возвращает

Детали

Выполняет следующие шаги:

  1. Убедитесь, что элемент является checkbox или radio input. Если нет, этот метод выбрасывает исключение. Если элемент уже установлен, этот метод сразу возвращает результат.
  2. Ожидайте проверки actionability на элементе, если не установлен параметр force.
  3. Прокрутите элемент в вид, если это необходимо.
  4. Используйте page.mouse для клика в центре элемента.
  5. Убедитесь, что элемент теперь установлен. Если нет, этот метод выбрасывает исключение.

Если элемент отсоединен от DOM в любой момент во время действия, этот метод выбрасывает исключение.

Когда все шаги в совокупности не завершены в течение указанного timeout, этот метод выбрасывает TimeoutError. Установка нулевого таймаута отключает это.


clear​

Добавлено в: v1.28 locator.clear

Очистите поле ввода.

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

await page.getByRole('textbox').clear();

Аргументы

  • options Object (опционально)
    • force boolean (опционально)#

      Следует ли обходить проверки actionability. По умолчанию false.

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

      Устарело

      Этот параметр не имеет эффекта.

Этот параметр не оказывает никакого влияния.

  • signal AbortSignal (необязательный) Добавлено в: v1.62#

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и будет выброшена ошибка. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • timeout number (необязательный)#

    Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

Детали

Этот метод ожидает проверки actionability, фокусируется на элементе, очищает его и вызывает событие input после очистки.

Если целевой элемент не является элементом <input>, <textarea> или [contenteditable], этот метод выбрасывает ошибку. Однако, если элемент находится внутри элемента <label>, который имеет связанный control, будет очищен именно этот элемент управления.


click​

Добавлено в: v1.14 locator.click

Клик по элементу.

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

Клик по кнопке:

await page.getByRole('button').click();

Shift-right-click в определенной позиции на canvas:

await page.locator('canvas').click({
button: 'right',
modifiers: ['Shift'],
position: { x: 23, y: 32 },
});

Аргументы

  • options Object (опционально)
    • button "left" | "right" | "middle" (опционально)#

      По умолчанию left.

    • clickCount number (опционально)#

      По умолчанию 1. См. UIEvent.detail.

    • delay number (опционально)#

      Время ожидания между mousedown и mouseup в миллисекундах. По умолчанию 0.

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

      Следует ли обходить проверки actionability. По умолчанию false.

    • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (опционально)#

      Модификаторы клавиш для нажатия. Обеспечивает, что только эти модификаторы нажаты во время операции, а затем восстанавливает текущие модификаторы. Если не указано, используются текущие нажатые модификаторы. "ControlOrMeta" разрешается как "Control" на Windows и Linux и как "Meta" на macOS.

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

      Устарело

      Этот параметр по умолчанию будет true в будущем.

      Действия, инициирующие навигации, ожидают, пока эти навигации произойдут и страницы начнут загружаться. Вы можете отказаться от ожидания, установив этот флаг. Вам понадобится этот параметр только в исключительных случаях, таких как навигация на недоступные страницы. По умолчанию false.

    • position Object (опционально)#

Точка относительно верхнего левого угла области элемента, включающей внутренние отступы (padding box). Если не указана, используется одна из видимых точек элемента.

  • scroll "auto" | "none" (необязательно) Добавлено в: v1.62#

    Определяет, прокручивает ли Playwright страницу, чтобы сделать элемент видимым перед выполнением действия. По умолчанию используется "auto": при необходимости выполняется прокрутка до элемента, в том числе во вложенных прокручиваемых контейнерах. При значении "none" Playwright не выполняет прокрутку, и действие завершается ошибкой, если элемент ещё не находится в области просмотра. Это полезно для проверки того, что элемент доступен пользователю без дополнительной прокрутки.

  • signal AbortSignal (необязательно) Добавлено в: v1.62#

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана с ошибкой. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • steps number (необязательно) Добавлено в: v1.57#

    По умолчанию 1. Отправляет n интерполированных событий mousemove, чтобы смоделировать перемещение между текущей позицией курсора Playwright и указанной точкой назначения. Если установить 1, будет сгенерировано одно событие mousemove в точке назначения.

  • timeout number (опционально)#

    Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

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

    Если установлено, этот метод выполняет только проверки actionability и пропускает действие. По умолчанию false. Полезно для ожидания, пока элемент будет готов к действию без его выполнения. Обратите внимание, что клавиатурные modifiers будут нажаты независимо от trial, чтобы позволить тестировать элементы, которые видны только при нажатии этих клавиш.

Возвращает

Детали

Этот метод кликает по элементу, выполняя следующие шаги:

  1. Ожидайте проверки actionability на элементе, если не установлен параметр force.
  2. Прокрутите элемент в вид, если это необходимо.
  3. Используйте page.mouse для клика в центре элемента или в указанной position.
  4. Ожидайте, пока инициированные навигации либо завершатся успешно, либо завершатся с ошибкой, если не установлен параметр noWaitAfter.

Если элемент отсоединен от DOM в любой момент во время действия, этот метод выбрасывает исключение.

Когда все шаги в совокупности не завершены в течение указанного timeout, этот метод выбрасывает TimeoutError. Установка нулевого таймаута отключает это.


contentFrame​

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

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

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

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

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

const locator = page.locator('iframe[name="embedded"]');
// ...
const frameLocator = locator.contentFrame();
await frameLocator.getByRole('button').click();

Возвращает


count​

Добавлено в: v1.14 locator.count

Возвращает количество элементов, соответствующих локатору.

Проверка количества

Если вам нужно проверить количество элементов на странице, предпочтите expect(locator).toHaveCount(), чтобы избежать нестабильности. Подробнее см. в руководстве по утверждениям.

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

const count = await page.getByRole('listitem').count();

Возвращает


dblclick​

Добавлено в: v1.14 locator.dblclick

Двойной клик по элементу.

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

await locator.dblclick();
await locator.dblclick(options);

Аргументы

  • options Object (опционально)
    • button "left" | "right" | "middle" (опционально)#

      По умолчанию left.

    • delay number (опционально)#

      Время ожидания между mousedown и mouseup в миллисекундах. По умолчанию 0.

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

      Следует ли обходить проверки actionability. По умолчанию false.

    • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (опционально)#

      Клавиши-модификаторы для нажатия. Гарантирует, что только эти модификаторы будут нажаты во время операции, а затем восстанавливает текущие модификаторы. Если не указано, используются текущие нажатые модификаторы. "ControlOrMeta" разрешается как "Control" на Windows и Linux и как "Meta" на macOS.

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

      Устарело

      Этот параметр не имеет эффекта.

      Этот параметр не имеет эффекта.

    • position Object (опционально)#

Точка, заданная относительно левого верхнего угла области элемента, включающей внутренние отступы (padding box). Если не указана, используется какая-либо видимая точка элемента.

  • scroll "auto" | "none" (необязательно) Добавлено в: v1.62#

    Определяет, прокручивает ли Playwright страницу, чтобы элемент оказался в области просмотра перед выполнением действия. По умолчанию используется "auto": при необходимости элемент прокручивается в область просмотра, в том числе за счёт прокрутки вложенных прокручиваемых контейнеров. Если установлено значение "none", Playwright не выполняет прокрутку к элементу, и действие завершается ошибкой, если элемент ещё не находится в области просмотра. Это полезно для проверки того, что элемент доступен пользователю без дополнительной прокрутки.

  • signal AbortSignal (необязательно) Добавлено в: v1.62#

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана с выбросом ошибки. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • steps number (необязательно) Добавлено в: v1.57#

    По умолчанию 1. Отправляет n интерполированных событий mousemove, чтобы смоделировать перемещение между текущей позицией курсора Playwright и указанной точкой назначения. Если установить 1, будет сгенерировано одно событие mousemove в точке назначения.

  • timeout number (опционально)#

    Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

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

    Если установлено, этот метод выполняет только проверки actionability и пропускает действие. По умолчанию false. Полезно для ожидания, пока элемент будет готов к действию без его выполнения. Обратите внимание, что клавиатурные modifiers будут нажаты независимо от trial, чтобы позволить тестировать элементы, которые видны только при нажатии этих клавиш.

Возвращает

Детали

Этот метод выполняет двойной клик по элементу, выполняя следующие шаги:

  1. Ожидание проверок actionability на элементе, если не установлен параметр force.
  2. Прокрутка элемента в вид, если необходимо.
  3. Использование page.mouse для двойного клика в центре элемента или в указанной position.

Если элемент отсоединен от DOM в любой момент во время действия, этот метод выбрасывает исключение.

Когда все шаги в совокупности не завершены в течение указанного timeout, этот метод выбрасывает TimeoutError. Передача нулевого таймаута отключает это.

примечание

element.dblclick() генерирует два события click и одно событие dblclick.


describe​

Добавлено в: v1.53 locator.describe

Описывает локатор; описание используется в Trace Viewer и отчётах. Возвращает локатор, указывающий на тот же элемент.

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

const button = page.getByTestId('btn-sub').describe('Subscribe button');
await button.click();

Аргументы

  • description string#

    Описание локатора.

Возвращает


description​

Добавлено в: v1.57 locator.description

Возвращает описание локатора, ранее заданное с помощью locator.describe(). Возвращает null, если пользовательское описание не было задано. Для получения представления в удобочитаемом виде предпочтительнее использовать locator.toString(), поскольку этот метод использует описание, если оно доступно.

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

const button = page.getByRole('button').describe('Subscribe button');
console.log(button.description()); // "Subscribe button"

const input = page.getByRole('textbox');
console.log(input.description()); // null

Возвращает


dispatchEvent​

Добавлено в: v1.14 locator.dispatchEvent

Программно отправляет событие на соответствующий элемент.

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

await locator.dispatchEvent('click');

Аргументы

Необязательные свойства инициализации, специфичные для события.

  • options Object (необязательно)
    • signal AbortSignal (необязательно) Добавлено в: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и завершится с ошибкой. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

      Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

Детали

Приведенный выше фрагмент отправляет событие click на элемент. Независимо от состояния видимости элемента, click отправляется. Это эквивалентно вызову element.click().

Внутри создается экземпляр события на основе указанного type, инициализируется с помощью свойств eventInit и отправляется на элемент. События по умолчанию composed, cancelable и всплывают.

Поскольку eventInit специфичен для события, пожалуйста, обратитесь к документации по событиям для списков начальных свойств:

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

const dataTransfer = await page.evaluateHandle(() => new DataTransfer());
await locator.dispatchEvent('dragstart', { dataTransfer });

dragTo​

Добавлено в: v1.18 locator.dragTo

Перетащите исходный элемент к целевому элементу и отпустите его.

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

const source = page.locator('#source');
const target = page.locator('#target');

await source.dragTo(target);
// или укажите точные позиции относительно верхних левых углов элементов:
await source.dragTo(target, {
sourcePosition: { x: 34, y: 7 },
targetPosition: { x: 10, y: 20 },
});

Аргументы

  • target Locator#

    Локатор элемента, к которому нужно перетащить.

  • options Object (опционально)

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

      Следует ли обходить проверки actionability. По умолчанию false.

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

      Устарело

      Этот параметр не имеет эффекта.

Этот параметр не оказывает никакого влияния.

  • scroll "auto" | "none" (необязательный) Добавлено в: v1.62#

    Определяет, будет ли Playwright прокручивать страницу, чтобы сделать элемент видимым перед выполнением действия. По умолчанию используется значение "auto", при котором элемент при необходимости прокручивается в область видимости, в том числе за счёт прокрутки вложенных прокручиваемых контейнеров. При значении "none" Playwright не выполняет прокрутку, и действие завершается ошибкой, если элемент ещё не находится в области просмотра. Это полезно для проверки того, что элемент доступен пользователю без дополнительной прокрутки.

  • signal AbortSignal (необязательный) Добавлено в: v1.62#

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана с выбросом ошибки. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • sourcePosition Object (необязательный)#

    Кликает по исходному элементу в этой точке, заданной относительно верхнего левого угла области padding элемента. Если не указано, используется какая‑то видимая точка элемента.

  • steps number (опционально) Добавлено в: v1.57#

    По умолчанию 1. Отправляет n интерполированных событий mousemove, чтобы смоделировать перемещение между mousedown и mouseup при перетаскивании. Если установить 1, будет сгенерировано одно событие mousemove в точке назначения.

  • targetPosition Object (опционально)#

    Отпустите на целевом элементе в этой точке относительно верхнего левого угла элемента. Если не указано, используется видимая точка элемента.

  • timeout number (опционально)#

    Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

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

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

Возвращает

Детали

Этот метод перетаскивает локатор к другому целевому локатору или целевой позиции. Сначала он перемещается к исходному элементу, выполняет mousedown, затем перемещается к целевому элементу или позиции и выполняет mouseup.


drop​

Добавлено в: v1.60 locator.drop

Имитирует внешнее перетаскивание файлов или данных, подобных содержимому буфера обмена, на элемент, соответствующий этому локатору.

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

Перетащить буфер с содержимым файла в область загрузки:

await page.locator('#dropzone').drop({
files: { name: 'note.txt', mimeType: 'text/plain', buffer: Buffer.from('hello') },
});

Перетащить обычный текст и URL вместе:

await page.locator('#dropzone').drop({
data: {
'text/plain': 'hello world',
'text/uri-list': 'https://example.com',
},
});

Аргументы

  • payload Object#

    Данные для перетаскивания на целевой элемент. Укажите files (пути к файлам или буферы в памяти), data (отображение MIME-тип → строка для содержимого, подобного данным буфера обмена, например text/plain, text/html, text/uri-list), или оба параметра.

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

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

      Точка относительно верхнего левого угла области элемента, включающей внутренние отступы (padding box). Если не указана, используется какая-либо видимая точка элемента.

    • signal AbortSignal (необязательно) Добавлено в: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. При отмене операция прерывается и выбрасывает ошибку. Сигнал не отключает тайм-аут по умолчанию. Его можно изменить методами browserContext.setDefaultTimeout() или page.setDefaultTimeout().

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

      Максимальное время в миллисекундах. По умолчанию 0, то есть тайм-аут отключён. Значение можно изменить параметром actionTimeout в конфигурации или методами browserContext.setDefaultTimeout() и page.setDefaultTimeout().

Возвращает

Подробности

Отправляет нативные события dragenter, dragover и drop в центре целевого элемента с синтетическим объектом [DataTransfer], содержащим предоставленные файлы и/или записи данных. Работает во всех браузерах благодаря созданию [DataTransfer] в контексте страницы.

Если обработчик dragover целевого элемента не вызывает preventDefault(), считается, что целевой элемент отклонил перетаскивание: Playwright отправляет dragleave и этот метод выбрасывает исключение.


evaluate​

Добавлено в: v1.14 locator.evaluate

Выполняет JavaScript код на странице, принимая соответствующий элемент в качестве аргумента.

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

Передача аргумента в pageFunction:

const result = await page.getByTestId('myId').evaluate((element, [x, y]) => {
return element.textContent + ' ' + x * y;
}, [7, 8]);
console.log(result); // prints "myId text 56"

Аргументы

  • pageFunction function | string#

    Функция, которая будет выполнена в контексте страницы.

  • arg EvaluationArgument (опционально)#

Необязательный аргумент для передачи в pageFunction.

  • options Object (необязательно)
    • exposeFunctions boolean (необязательно) Добавлено в: v1.62#

      Если установлено значение true, функции, переданные внутри arg, становятся доступны на странице и могут вызываться из функции, выполняемой в контексте страницы. Вызов каждой из них возвращает Promise с результатом её выполнения. Внутри каждая функция предоставляется через page.exposeFunction(), поэтому технически она доступна из всех фреймов страницы. Предоставленные функции удаляются при навигации верхнего уровня. По умолчанию установлено значение false: в этом случае функции не подлежат сериализации, и передача функции приводит к ошибке.

    • signal AbortSignal (необязательно) Добавлено в: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и завершится ошибкой. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

      Максимальное время ожидания локатора перед выполнением вычисления (в миллисекундах). Обратите внимание: после того как локатор будет найден, само вычисление таймаутом не ограничивается. По умолчанию 0 — без таймаута.

Возвращает

Детали

Возвращает значение, возвращаемое pageFunction, вызываемой с соответствующим элементом в качестве первого аргумента и arg в качестве второго аргумента.

Если pageFunction возвращает Promise, этот метод будет ждать разрешения промиса и вернет его значение.

Если pageFunction выбрасывает исключение или отклоняет промис, этот метод выбрасывает исключение.


evaluateAll​

Добавлено в: v1.14 locator.evaluateAll

Выполняет JavaScript код на странице, принимая все соответствующие элементы в качестве аргумента.

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

const locator = page.locator('div');
const moreThanTen = await locator.evaluateAll((divs, min) => divs.length > min, 10);

Аргументы

  • pageFunction function | string#

    Функция, которая будет выполнена в контексте страницы.

  • arg EvaluationArgument (опционально)#

    Необязательный аргумент для передачи в pageFunction.

Возвращает

Детали

Возвращает значение, возвращаемое pageFunction, вызываемой с массивом всех соответствующих элементов в качестве первого аргумента и arg в качестве второго аргумента.

Если pageFunction возвращает Promise, этот метод будет ждать разрешения промиса и вернет его значение.

Если pageFunction выбрасывает исключение или отклоняет промис, этот метод выбрасывает исключение.


evaluateHandle​

Добавлено в: v1.14 locator.evaluateHandle

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

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

await locator.evaluateHandle(pageFunction);
await locator.evaluateHandle(pageFunction, arg, options);

Аргументы

  • pageFunction function | string#

    Функция, которая будет выполнена в контексте страницы.

  • arg EvaluationArgument (опционально)#

Необязательный аргумент для передачи в pageFunction.

  • options Object (необязательно)
    • exposeFunctions boolean (необязательно) Добавлено в: v1.62#

      Если установлено значение true, функции, переданные внутри arg, становятся доступны на странице и могут вызываться из функции, выполняемой в контексте страницы. Вызов такой функции возвращает Promise с результатом её выполнения. Внутри каждая функция предоставляется через page.exposeFunction(), поэтому технически она доступна из всех фреймов страницы. Предоставленные функции удаляются при навигации фрейма верхнего уровня. По умолчанию установлено значение false: в этом случае функции не могут быть сериализованы, и попытка передать функцию приводит к ошибке.

    • signal AbortSignal (необязательно) Добавлено в: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана с ошибкой. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

      Максимальное время ожидания локатора перед выполнением вычисления (в миллисекундах). Обратите внимание: после того как локатор будет найден, само вычисление таймаутом не ограничивается. По умолчанию 0 — без таймаута.

Возвращает

Детали

Возвращает значение, возвращаемое pageFunction как JSHandle, вызываемой с соответствующим элементом в качестве первого аргумента и arg в качестве второго аргумента.

Единственное отличие между locator.evaluate() и locator.evaluateHandle() заключается в том, что locator.evaluateHandle() возвращает JSHandle.

Если pageFunction возвращает Promise, этот метод будет ждать разрешения промиса и вернет его значение.

Если pageFunction выбрасывает исключение или отклоняет промис, этот метод выбрасывает исключение.

Смотрите page.evaluateHandle() для получения более подробной информации.


fill​

Добавлено в: v1.14 locator.fill

Устанавливает значение в поле ввода.

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

await page.getByRole('textbox').fill('example value');

Аргументы

  • value string#

    Значение для установки в элемент <input>, <textarea> или [contenteditable].

  • options Object (опционально)

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

      Нужно ли обходить проверки actionability. По умолчанию false.

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

      Устарело

      Эта опция не имеет эффекта.

Этот параметр не оказывает никакого эффекта.

  • signal AbortSignal (необязательный) Добавлено в: v1.62#

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и завершится с ошибкой. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • timeout number (необязательный)#

    Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить через опцию actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

Детали

Этот метод ждет проверки actionability, фокусируется на элементе, заполняет его и вызывает событие input после заполнения. Обратите внимание, что вы можете передать пустую строку, чтобы очистить поле ввода.

Если целевой элемент не является элементом <input>, <textarea> или [contenteditable], этот метод выбрасывает ошибку. Однако, если элемент находится внутри элемента <label>, который имеет ассоциированный control, будет заполнен именно этот control.

Для отправки более детализированных событий клавиатуры используйте locator.pressSequentially().


filter​

Добавлено в: v1.22 locator.filter

Этот метод сужает существующий локатор в соответствии с опциями, например, фильтрует по тексту. Его можно использовать в цепочке для многократной фильтрации.

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

const rowLocator = page.locator('tr');
// ...
await rowLocator
.filter({ hasText: 'text in column 1' })
.filter({ has: page.getByRole('button', { name: 'column 2 button' }) })
.screenshot();

Аргументы

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

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

    • hasText string | RegExp (опционально)#

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

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

Соответствует только видимым или только невидимым элементам. Для поиска только видимых элементов предпочтительно использовать сокращённый метод locator.visible().

Возвращает


first​

Добавлено в: v1.14 locator.first

Возвращает локатор для первого элемента, соответствующего условию.

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

locator.first();

Возвращает


focus​

Добавлено в: v1.14 locator.focus

Вызывает focus на элементе, соответствующем условию.

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

await locator.focus();
await locator.focus(options);

Аргументы

  • options Object (необязательно)
    • signal AbortSignal (необязательно) Добавлено в: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и завершится с ошибкой. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

      Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить через опцию actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает


frameLocator​

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

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

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

const locator = page.frameLocator('iframe').getByText('Submit');
await locator.click();

Аргументы

  • selector string#

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

Возвращает


getAttribute​

Добавлено в: v1.14 locator.getAttribute

Возвращает значение атрибута элемента, соответствующего условию.

Проверка атрибутов

Если вам нужно проверить атрибут элемента, предпочтите expect(locator).toHaveAttribute(), чтобы избежать нестабильности. Подробнее см. в руководстве по проверкам.

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

await locator.getAttribute(name);
await locator.getAttribute(name, options);

Аргументы

Имя атрибута, значение которого нужно получить.

  • options Object (необязательно)
    • signal AbortSignal (необязательно) Добавлено в: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и выбросит ошибку. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

      Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить через опцию actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает


getByAltText​

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

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

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

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

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

Аргументы

  • text string | RegExp#

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

  • options Object (опционально)

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

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

Возвращает


getByLabel​

Добавлено в: v1.27 locator.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').fill('john');
await page.getByLabel('Password').fill('secret');

Аргументы

  • text string | RegExp#

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

  • options Object (опционально)

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

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

Возвращает


getByPlaceholder​

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

Возвращает


getByRole​

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

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

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

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

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

    примечание

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

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

Определяет, сопоставляются ли name и description точно: с учётом регистра и по всей строке. По умолчанию — 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.

Возвращает

Детали

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

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


getByTestId​

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

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

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

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

<button data-testid="directions">Itinéraire</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 locator.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', { exact: true });

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

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

Аргументы

  • text string | RegExp#

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

  • options Object (опционально)

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

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

Возвращает

Детали

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

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


getByTitle​

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

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

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

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

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

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

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

Аргументы

  • text string | RegExp#

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

  • options Object (опционально)

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

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

Возвращает


hideHighlight​

Добавлено в: v1.60 locator.hideHighlight

Скрывает подсветку элемента, ранее добавленную с помощью locator.highlight().

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

await locator.hideHighlight();

Возвращает


highlight​

Добавлено в: v1.20 locator.highlight

Подсвечивает соответствующий элемент(ы) на экране. Полезно для отладки, но не стоит коммитить код, использующий locator.highlight().

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

await locator.highlight();
await locator.highlight(options);

Аргументы

  • options Object (необязательный)
    • style string | Object<string, string | number> (необязательный) Добавлено в: v1.60#

      Встроенные CSS-стили, применяемые к слою подсветки, например:

      await locator.highlight({ style: 'outline: 2px dashed red' });
      await locator.highlight({ style: { color: 'red' } });

Возвращает


hover​

Добавлено в: v1.14 locator.hover

Наводит курсор на соответствующий элемент.

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

await page.getByRole('link').hover();

Аргументы

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

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

    • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (необязательно)#

      Клавиши-модификаторы, которые необходимо нажать. Гарантирует, что во время операции будут нажаты только указанные модификаторы, а затем восстанавливает исходное состояние модификаторов. Если не указано, используются модификаторы, нажатые в данный момент. "ControlOrMeta" соответствует "Control" в Windows и Linux и "Meta" в macOS.

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

      Устарело

      Этот параметр ни на что не влияет.

      Этот параметр ни на что не влияет.

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

      Точка, заданная относительно верхнего левого угла области элемента, включающей внутренние отступы (padding box). Если не указана, используется одна из видимых точек элемента.

    • scroll "auto" | "none" (необязательно) Добавлено в: v1.62#

      Определяет, прокручивает ли Playwright страницу до появления элемента в области просмотра перед выполнением действия. По умолчанию используется "auto": при необходимости выполняется прокрутка до элемента, в том числе во вложенных прокручиваемых контейнерах. При значении "none" Playwright не выполняет прокрутку до элемента, и действие завершается ошибкой, если элемент ещё не находится в области просмотра. Это полезно для проверки того, что элемент доступен пользователю без дополнительной прокрутки.

    • signal AbortSignal (необязательно) Добавлено в: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана с выбросом ошибки. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

      Максимальное время ожидания в миллисекундах. По умолчанию — 0, то есть без ограничения времени ожидания. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

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

      Если установлено значение true, этот метод выполняет только проверки возможности выполнения действия, пропуская само действие. По умолчанию — false. Полезно для ожидания готовности элемента к действию без выполнения самого действия. Обратите внимание, что клавиши-модификаторы modifiers будут нажаты независимо от значения trial, чтобы можно было проверять элементы, которые видны только при нажатии этих клавиш.

Возвращает

Подробности

Этот метод выполняет наведение курсора на элемент, выполняя следующие шаги:

  1. Ожидание завершения проверок доступности к действию, если не установлен параметр force.
  2. Прокрутка элемента в область видимости, если это необходимо.
  3. Использование page.mouse для наведения курсора на центр элемента или указанную позицию.

Если элемент будет удалён из DOM в любой момент во время выполнения, метод вызовет исключение.

Если все шаги не были выполнены в течение указанного таймаута, метод вызовет TimeoutError. Указание нулевого таймаута отключает это ограничение.


innerHTML​

Добавлено в: v1.14 locator.innerHTML

Возвращает значение element.innerHTML.

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

await locator.innerHTML();
await locator.innerHTML(options);

Аргументы

  • options Object (необязательно)
    • signal AbortSignal (необязательно) Добавлено в версии: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и будет выброшена ошибка. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

      Максимальное время ожидания в миллисекундах. По умолчанию равно 0 — без ограничения времени ожидания. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает


innerText​

Добавлено в: v1.14 locator.innerText

Возвращает значение element.innerText.

Проверка текста

Если вам нужно проверить текст на странице, рекомендуется использовать expect(locator).toHaveText() с параметром useInnerText, чтобы избежать нестабильных тестов. Подробнее см. в руководстве по проверкам.

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

await locator.innerText();
await locator.innerText(options);

Аргументы

  • options Object (необязательно)
    • signal AbortSignal (необязательно) Добавлено в: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и завершится с ошибкой. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

      Максимальное время ожидания в миллисекундах. По умолчанию равно 0 — без ограничения времени ожидания. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает


inputValue​

Добавлено в: v1.14 locator.inputValue

Возвращает значение для соответствующего элемента <input>, <textarea> или <select>.

Проверка значения

Если вам нужно проверить значение поля ввода, рекомендуется использовать expect(locator).toHaveValue(), чтобы избежать нестабильных тестов. Подробнее см. в руководстве по проверкам.

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

const value = await page.getByRole('textbox').inputValue();

Аргументы

  • options Object (необязательно)
    • signal AbortSignal (необязательно) Добавлено в: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и завершится с ошибкой. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

      Максимальное время ожидания в миллисекундах. По умолчанию равно 0 — без ограничения времени ожидания. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

Подробности

Генерирует исключение, если элемент не является <input>, <textarea> или <select>. Однако, если элемент находится внутри <label>, который связан с контролом, возвращается значение этого контрола.


isChecked​

Добавлено в: v1.14 locator.isChecked

Возвращает true, если элемент отмечен (например, чекбокс или радио-кнопка). Генерирует исключение, если элемент не является чекбоксом или радио-кнопкой.

Проверка состояния

Если вам нужно проверить, что чекбокс установлен, рекомендуется использовать expect(locator).toBeChecked(), чтобы избежать нестабильных тестов. Подробнее см. в руководстве по проверкам.

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

const checked = await page.getByRole('checkbox').isChecked();

Аргументы

  • options Object (необязательно)
    • signal AbortSignal (необязательно) Добавлено в: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и будет выброшена ошибка. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

      Максимальное время ожидания в миллисекундах. По умолчанию равно 0 — без ограничения времени ожидания. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает


isDisabled​

Добавлено в: v1.14 locator.isDisabled

Возвращает true, если элемент отключён (противоположность enabled).

Проверка состояния

Если вам нужно проверить, что элемент отключён, рекомендуется использовать expect(locator).toBeDisabled(), чтобы избежать нестабильных тестов. Подробнее см. в руководстве по проверкам.

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

const disabled = await page.getByRole('button').isDisabled();

Аргументы

  • options Object (необязательно)
    • signal AbortSignal (необязательно) Добавлено в: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и будет выброшена ошибка. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

      Максимальное время ожидания в миллисекундах. По умолчанию равно 0 — без ограничения времени ожидания. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает


isEditable​

Добавлено в: v1.14 locator.isEditable

Возвращает, является ли элемент редактируемым. Если целевой элемент не является <input>, <textarea>, <select>, [contenteditable] и не имеет роли, допускающей [aria-readonly], этот метод вызывает ошибку.

Проверка состояния редактируемости

Если вам нужно проверить, что элемент редактируем, предпочтите expect(locator).toBeEditable(), чтобы избежать нестабильности. Подробнее см. в руководстве по утверждениям.

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

const editable = await page.getByRole('textbox').isEditable();

Аргументы

  • options Object (необязательно)
    • signal AbortSignal (необязательно) Добавлено в: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и завершится с ошибкой. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

      Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью опции actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает


isEnabled​

Добавлено в: v1.14 locator.isEnabled

Возвращает, является ли элемент включенным.

Проверка состояния включенности

Если вам нужно проверить, что элемент включен, предпочтите expect(locator).toBeEnabled(), чтобы избежать нестабильности. Подробнее см. в руководстве по утверждениям.

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

const enabled = await page.getByRole('button').isEnabled();

Аргументы

  • options Object (необязательно)
    • signal AbortSignal (необязательно) Добавлено в: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и выбросит ошибку. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

      Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью опции actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает


isHidden​

Добавлено в: v1.14 locator.isHidden

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

Проверка видимости

Если вам нужно проверить, что элемент скрыт, предпочтите expect(locator).toBeHidden(), чтобы избежать нестабильности. Подробнее см. в руководстве по утверждениям.

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

const hidden = await page.getByRole('button').isHidden();

Аргументы

  • options Object (опционально)
    • timeout number (опционально)#

      Устарело

      Этот параметр игнорируется. locator.isHidden() не ждет, пока элемент станет скрытым, и возвращает результат немедленно.

Возвращает


isVisible​

Добавлено в: v1.14 locator.isVisible

Возвращает, является ли элемент видимым.

Проверка видимости

Если вам нужно проверить, что элемент видим, предпочтите expect(locator).toBeVisible(), чтобы избежать нестабильности. Подробнее см. в руководстве по утверждениям.

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

const visible = await page.getByRole('button').isVisible();

Аргументы

  • options Object (опционально)
    • timeout number (опционально)#

      Устарело

      Этот параметр игнорируется. locator.isVisible() не ждет, пока элемент станет видимым, и возвращает результат немедленно.

Возвращает


last​

Добавлено в: v1.14 locator.last

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

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

const banana = await page.getByRole('listitem').last();

Возвращает


locator​

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

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

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

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

locator.locator(selectorOrLocator);
locator.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#

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

    • hasText string | RegExp (опционально)#

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

Возвращает


normalize​

Добавлено в: v1.59 locator.normalize

Возвращает новый локатор, использующий рекомендуемые подходы к поиску соответствующего элемента, отдавая предпочтение тестовым идентификаторам, ролям ARIA и другим атрибутам, видимым пользователю, перед CSS-селекторами. Это полезно для преобразования селекторов, зависящих от деталей реализации, в более устойчивые, удобочитаемые локаторы.

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

Агент может выбрать элемент по идентификатору из снимка page.ariaSnapshot(), полученного в режиме "ai". Идентификаторы действуют только для последнего снимка. Нормализуйте локатор и преобразуйте результат в строку, чтобы получить код устойчивого локатора, как это делает codegen.

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

- button "Submit" [ref=e2]

Идентификатор элемента можно преобразовать в код локатора:

const normalized = await page.getByRef('e2').normalize();
console.log(normalized.toString());
// getByRole('button', { name: 'Submit' })

Возвращает


nth​

Добавлено в: v1.14 locator.nth

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

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

const banana = await page.getByRole('listitem').nth(2);

Аргументы

Возвращает


or​

Добавлено в: v1.33 locator.or

Создает локатор, соответствующий всем элементам, которые соответствуют одному или обоим из двух локаторов.

Обратите внимание, что когда оба локатора что-то совпадают, результирующий локатор будет иметь несколько совпадений, что может вызвать нарушение строгого режима локатора.

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

Рассмотрим сценарий, когда вы хотите нажать на кнопку "New email", но иногда вместо этого появляется диалоговое окно настроек безопасности. В этом случае вы можете ждать либо кнопку "New email", либо диалог и действовать соответственно.

примечание

Если и кнопка "New email", и диалог безопасности появляются на экране, локатор "or" будет соответствовать обоим из них, возможно, вызывая ошибку "нарушение строгого режима". В этом случае вы можете использовать locator.first(), чтобы соответствовать только одному из них.

const newEmail = page.getByRole('button', { name: 'New' });
const dialog = page.getByText('Confirm security settings');
await expect(newEmail.or(dialog).first()).toBeVisible();
if (await dialog.isVisible())
await page.getByRole('button', { name: 'Dismiss' }).click();
await newEmail.click();

Аргументы

  • locator Locator#

    Альтернативный локатор для совпадения.

Возвращает


page​

Добавлено в: v1.19 locator.page

Страница, к которой относится этот локатор.

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

locator.page();

Возвращает


press​

Добавлено в: v1.14 locator.press

Фокусируется на соответствующем элементе и нажимает комбинацию клавиш.

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

await page.getByRole('textbox').press('Backspace');

Аргументы

  • key string#

    Имя клавиши для нажатия или символ для генерации, например, ArrowLeft или a.

  • options Object (опционально)

    • delay number (опционально)#

      Время ожидания между keydown и keyup в миллисекундах. По умолчанию 0.

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

      Устарело

      Эта опция по умолчанию будет true в будущем.

      Действия, инициирующие навигацию, ожидают, пока эта навигация произойдет и страницы начнут загружаться. Вы можете отказаться от ожидания, установив этот флаг. Эта опция нужна только в исключительных случаях, таких как навигация на недоступные страницы. По умолчанию false.

    • signal AbortSignal (необязательно) Добавлено в: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и завершится с ошибкой. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

      Максимальное время ожидания в миллисекундах. По умолчанию — 0, то есть без ограничения времени ожидания. Значение по умолчанию можно изменить с помощью опции actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

Детали

Фокусируется на элементе, а затем использует keyboard.down() и keyboard.up().

key может указывать предполагаемое значение keyboardEvent.key или один символ для генерации текста. Расширенный набор значений key можно найти здесь. Примеры клавиш:

F1 - F12, Digit0- Digit9, KeyA- KeyZ, Backquote, Minus, Equal, Backslash, Backspace, Tab, Delete, Escape, ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrowRight, ArrowUp и т.д.

Также поддерживаются следующие модификационные сочетания: Shift, Control, Alt, Meta, ShiftLeft, ControlOrMeta. ControlOrMeta разрешается в Control на Windows и Linux и в Meta на macOS.

Удержание Shift будет вводить текст, соответствующий key в верхнем регистре.

Если key является одним символом, он чувствителен к регистру, поэтому значения a и A будут генерировать разные тексты.

Также поддерживаются сочетания клавиш, такие как key: "Control+o", key: "Control++ или key: "Control+Shift+T". При указании с модификатором, модификатор нажимается и удерживается, пока не будет нажата последующая клавиша.


pressSequentially​

Добавлено в: v1.38 locator.pressSequentially
подсказка

В большинстве случаев следует использовать locator.fill() вместо этого. Вам нужно нажимать клавиши по одной, только если на странице есть специальная обработка клавиатуры.

Фокусируется на элементе, а затем отправляет событие keydown, keypress/input и keyup для каждого символа в тексте.

Чтобы нажать специальную клавишу, такую как Control или ArrowDown, используйте locator.press().

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

await locator.pressSequentially('Hello'); // Печатает мгновенно
await locator.pressSequentially('World', { delay: 100 }); // Печатает медленнее, как пользователь

Пример ввода в текстовое поле и затем отправки формы:

const locator = page.getByLabel('Password');
await locator.pressSequentially('my password');
await locator.press('Enter');

Аргументы

  • text string#

    Строка символов для последовательного нажатия в фокусированный элемент.

  • options Object (опционально)

    • delay number (опционально)#

      Время ожидания между нажатиями клавиш в миллисекундах. По умолчанию 0.

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

      Устарело

      Эта опция не имеет эффекта.

      Эта опция не имеет эффекта.

    • signal AbortSignal (необязательный) Добавлено в: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и выбросит ошибку. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

    • timeout number (необязательный)#

      Максимальное время ожидания в миллисекундах. По умолчанию — 0, то есть без ограничения времени ожидания. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает


screenshot​

Добавлено в: v1.14 locator.screenshot

Сделать скриншот элемента, соответствующего локатору.

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

await page.getByRole('link').screenshot();

Отключить анимации и сохранить скриншот в файл:

await page.getByRole('link').screenshot({ animations: 'disabled', path: 'link.png' });

Аргументы

  • options Object (опционально)
    • animations "disabled" | "allow" (опционально)#

      При установке в "disabled", останавливает CSS-анимации, CSS-переходы и веб-анимации. Анимации получают разное обращение в зависимости от их продолжительности:

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

      По умолчанию "allow", что оставляет анимации нетронутыми.

    • caret "hide" | "initial" (опционально)#

      При установке в "hide", скриншот скроет текстовый курсор. При установке в "initial", поведение текстового курсора не изменится. По умолчанию "hide".

    • mask Array<Locator> (опционально)#

      Укажите локаторы, которые должны быть замаскированы при создании скриншота. Замаскированные элементы будут покрыты розовым прямоугольником #FF00FF (настраивается с помощью maskColor), который полностью покрывает их ограничивающий прямоугольник. Маска также применяется к невидимым элементам, см. Matching only visible elements для отключения этого.

    • maskColor string (опционально) Добавлено в: v1.35#

      Укажите цвет наложения для замаскированных элементов в CSS color format. Цвет по умолчанию - розовый #FF00FF.

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

      Скрывает белый фон по умолчанию и позволяет делать скриншоты с прозрачностью. Не применимо к изображениям jpeg. По умолчанию false.

    • path string (опционально)#

      Путь к файлу для сохранения изображения. Тип скриншота будет определен по расширению файла. Если path является относительным путем, то он разрешается относительно текущей рабочей директории. Если путь не указан, изображение не будет сохранено на диск.

    • quality number (опционально)#

Качество изображения в диапазоне от 0 до 100. Не применяется к изображениям в формате png. Для jpeg значение по умолчанию — 80. Для webp значение качества 100 (по умолчанию) обеспечивает сжатие без потерь, а меньшие значения — сжатие с потерями.

  • scale "css" | "device" (необязательно)#

    При установке в "css", скриншот будет иметь один пиксель на каждый css пиксель на странице. Для устройств с высоким разрешением это позволит уменьшить размер скриншотов. Использование опции "device" создаст один пиксель на каждый пиксель устройства, так что скриншоты устройств с высоким разрешением будут в два раза больше или даже больше.

По умолчанию используется "device".

  • signal AbortSignal (необязательно) Добавлено в: v1.62#

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана с выбросом ошибки. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • style string (необязательно) Добавлено в: v1.41#

    Текст стиля, который будет применен при создании скриншота. Здесь вы можете скрыть динамические элементы, сделать элементы невидимыми или изменить их свойства, чтобы помочь вам создавать повторяемые скриншоты. Этот стиль проникает в Shadow DOM и применяется к внутренним фреймам.

  • timeout number (опционально)#

Максимальное время ожидания в миллисекундах. По умолчанию равно 0 — без ограничения времени ожидания. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

  • type "png" | "jpeg" | "webp" (необязательный)#

    Укажите тип скриншота, по умолчанию png.

Возвращает

Детали

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

Этот метод ожидает проверки actionability, затем прокручивает элемент в вид перед созданием скриншота. Если элемент отсоединен от DOM, метод выдает ошибку.

Возвращает буфер с захваченным скриншотом.


scrollIntoViewIfNeeded​

Добавлено в: v1.14 locator.scrollIntoViewIfNeeded

Этот метод ожидает проверки actionability, затем пытается прокрутить элемент в вид, если он не полностью виден, как определено ratio IntersectionObserver.

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

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

await locator.scrollIntoViewIfNeeded();
await locator.scrollIntoViewIfNeeded(options);

Аргументы

  • options Object (необязательно)
    • signal AbortSignal (необязательно) Добавлено в: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и будет выброшена ошибка. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

      Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью опции actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout() methods.

Возвращает


selectOption​

Добавлено в: v1.14 locator.selectOption

Выбирает опцию или опции в <select>.

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

<select multiple>
<option value="red">Red</option>
<option value="green">Green</option>
<option value="blue">Blue</option>
</select>
// одиночный выбор, соответствующий значению или метке
element.selectOption('blue');

// одиночный выбор, соответствующий метке
element.selectOption({ label: 'Blue' });

// множественный выбор для опций red, green и blue
element.selectOption(['red', 'green', 'blue']);

Аргументы

  • values null | string | ElementHandle | Array<string> | Object | Array<ElementHandle> | Array<Object>#

    • value string (опционально)

      Соответствует option.value. Опционально.

    • label string (опционально)

      Соответствует option.label. Опционально.

    • index number (опционально)

      Соответствует индексу. Опционально.

    Опции для выбора. Если у <select> есть атрибут multiple, выбираются все соответствующие опции, в противном случае выбирается только первая опция, соответствующая одной из переданных опций. Строковые значения соответствуют как значениям, так и меткам. Опция считается соответствующей, если все указанные свойства совпадают.

  • options Object (опционально)

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

      Следует ли обходить проверки actionability. По умолчанию false.

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

      Устарело

      Этот параметр не имеет эффекта.

Эта опция не оказывает никакого эффекта.

  • signal AbortSignal (необязательно) Добавлено в: v1.62#

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и будет выброшена ошибка. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

    Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

Детали

Этот метод ожидает проверки actionability, ждет, пока все указанные опции не появятся в элементе <select>, и выбирает эти опции.

Если целевой элемент не является элементом <select>, этот метод вызывает ошибку. Однако, если элемент находится внутри элемента <label>, который имеет связанную control, будет использован этот контрол.

Возвращает массив значений опций, которые были успешно выбраны.

Вызывает событие change и input, как только все предоставленные опции были выбраны.


selectText​

Добавлено в: v1.14 locator.selectText

Этот метод ожидает проверки actionability, затем фокусируется на элементе и выделяет весь его текстовый контент.

Если элемент находится внутри элемента <label>, который имеет связанную control, фокусируется и выделяет текст в этом контроле.

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

await locator.selectText();
await locator.selectText(options);

Аргументы

  • options Object (опционально)
    • force boolean (опционально)#

Определяет, следует ли пропускать проверки готовности к действию. По умолчанию — false.

  • signal AbortSignal (необязательно) Добавлено в: v1.62#

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и будет выброшена ошибка. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

    Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает


setChecked​

Добавлено в: v1.15 locator.setChecked

Устанавливает состояние чекбокса или радиоэлемента.

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

await page.getByRole('checkbox').setChecked(true);

Аргументы

  • checked boolean#

    Установить или снять флажок.

  • options Object (опционально)

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

      Следует ли обходить проверки actionability. По умолчанию false.

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

      Устарело

      Этот параметр не имеет эффекта.

      Этот параметр не имеет эффекта.

    • position Object (опционально)#

Точка относительно верхнего левого угла области элемента, включающей внутренние отступы (padding box). Если не указана, используется одна из видимых точек элемента.

  • scroll "auto" | "none" (необязательно) Добавлено в: v1.62#

    Определяет, прокручивает ли Playwright страницу, чтобы элемент оказался в области просмотра перед выполнением действия. По умолчанию используется "auto": при необходимости выполняется прокрутка, в том числе вложенных прокручиваемых контейнеров, чтобы элемент оказался в области просмотра. При значении "none" Playwright не выполняет прокрутку, и действие завершается с ошибкой, если элемент ещё не находится в области просмотра. Это полезно для проверки того, что элемент доступен пользователю без дополнительной прокрутки.

  • signal AbortSignal (необязательно) Добавлено в: v1.62#

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана с выбросом ошибки. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

    Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

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

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

Возвращает

Детали

Этот метод устанавливает или снимает флажок с элемента, выполняя следующие шаги:

  1. Убедитесь, что найденный элемент является чекбоксом или радио-кнопкой. Если нет, этот метод вызывает ошибку.
  2. Если элемент уже имеет правильное состояние, этот метод возвращается немедленно.
  3. Ожидайте проверки actionability на найденном элементе, если не установлен параметр force. Если элемент отсоединяется во время проверок, все действие повторяется.
  4. Прокрутите элемент в вид, если это необходимо.
  5. Используйте page.mouse для клика в центре элемента.
  6. Убедитесь, что элемент теперь установлен или снят. Если нет, этот метод вызывает ошибку.

Когда все шаги в совокупности не завершены в течение указанного timeout, этот метод вызывает TimeoutError. Передача нулевого таймаута отключает это.


setInputFiles​

Добавлено в: v1.14 locator.setInputFiles

Загружает файл или несколько файлов в <input type=file>. Для входов с атрибутом [webkitdirectory] поддерживается только один путь к директории.

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

// Выбрать один файл
await page.getByLabel('Upload file').setInputFiles(path.join(__dirname, 'myfile.pdf'));

// Выбрать несколько файлов
await page.getByLabel('Upload files').setInputFiles([
path.join(__dirname, 'file1.txt'),
path.join(__dirname, 'file2.txt'),
]);

// Выбрать директорию
await page.getByLabel('Upload directory').setInputFiles(path.join(__dirname, 'mydir'));

// Удалить все выбранные файлы
await page.getByLabel('Upload file').setInputFiles([]);

// Загрузить буфер из памяти
await page.getByLabel('Upload file').setInputFiles({
name: 'file.txt',
mimeType: 'text/plain',
buffer: Buffer.from('this is test')
});

Аргументы

Этот параметр не оказывает никакого влияния.

  • signal AbortSignal (необязательный) Добавлено в: v1.62#

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и завершится с ошибкой. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • timeout number (необязательный)#

    Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

Детали

Устанавливает значение входного файла на эти пути к файлам или файлы. Если некоторые из filePaths являются относительными путями, они разрешаются относительно текущей рабочей директории. Для пустого массива очищает выбранные файлы.

Этот метод ожидает, что Locator указывает на input element. Однако, если элемент находится внутри элемента <label>, который имеет связанную control, он нацелен на этот контрол.


tap​

Добавлено в: v1.14 locator.tap

Выполняет жест нажатия на элемент, соответствующий локатору. Примеры эмуляции других жестов путем ручной отправки событий касания см. на странице эмуляция устаревших событий касания.

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

await locator.tap();
await locator.tap(options);

Аргументы

  • options Object (опционально)
    • force boolean (опционально)#

      Следует ли обходить проверки actionability. По умолчанию false.

    • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (опционально)#

      Модификаторные клавиши для нажатия. Гарантирует, что только эти модификаторы будут нажаты во время операции, а затем восстанавливает текущие модификаторы. Если не указано, используются текущие нажатые модификаторы. "ControlOrMeta" разрешается как "Control" на Windows и Linux и как "Meta" на macOS.

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

      Устарело

      Этот параметр не имеет эффекта.

      Этот параметр не имеет эффекта.

    • position Object (опционально)#

Точка относительно верхнего левого угла области элемента, включающей внутренние отступы (padding box). Если не указана, используется какая-либо видимая точка элемента.

  • scroll "auto" | "none" (необязательно) Добавлено в: v1.62#

    Определяет, будет ли Playwright прокручивать страницу, чтобы сделать элемент видимым перед выполнением действия. По умолчанию используется "auto": при необходимости выполняется прокрутка, чтобы элемент оказался в области видимости, в том числе прокрутка вложенных прокручиваемых контейнеров. При значении "none" Playwright не выполняет прокрутку, и действие завершается ошибкой, если элемент ещё не находится в области просмотра. Это полезно для проверки того, что элемент доступен пользователю без дополнительной прокрутки.

  • signal AbortSignal (необязательно) Добавлено в: v1.62#

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и будет выброшено исключение. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

    Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

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

    Если установлено, этот метод выполняет только проверки actionability и пропускает действие. По умолчанию false. Полезно для ожидания, пока элемент будет готов к действию, без его выполнения. Обратите внимание, что клавиатурные modifiers будут нажаты независимо от trial, чтобы позволить тестировать элементы, которые видны только при нажатии этих клавиш.

Возвращает

Детали

Этот метод нажимает на элемент, выполняя следующие шаги:

  1. Ожидание проверок actionability на элементе, если не установлен параметр force.
  2. Прокрутка элемента в вид, если это необходимо.
  3. Использование page.touchscreen для нажатия в центр элемента или указанную position.

Если элемент отсоединен от DOM в любой момент во время действия, этот метод выбрасывает исключение.

Когда все шаги в совокупности не завершены в течение указанного timeout, этот метод выбрасывает TimeoutError. Передача нулевого таймаута отключает это.

примечание

element.tap() требует, чтобы параметр hasTouch контекста браузера был установлен в true.


textContent​

Добавлено в: v1.14 locator.textContent

Возвращает node.textContent.

Проверка текста

Если вам нужно проверить текст на странице, предпочтите expect(locator).toHaveText(), чтобы избежать нестабильности. Подробнее см. в руководстве по утверждениям.

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

await locator.textContent();
await locator.textContent(options);

Аргументы

  • options Object (необязательный)
    • signal AbortSignal (необязательный) Добавлено в: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и будет выброшена ошибка. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

    • timeout number (необязательный)#

      Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает


toString​

Добавлено в: v1.57 locator.toString

Возвращает читаемое представление локатора. Если задано описание locator.description(), использует его. В остальных случаях строит строку на основе селектора.

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

locator.toString();

Возвращает


uncheck​

Добавлено в: v1.14 locator.uncheck

Убедитесь, что элемент флажка или радио не отмечен.

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

await page.getByRole('checkbox').uncheck();

Аргументы

  • options Object (опционально)
    • force boolean (опционально)#

      Следует ли обходить проверки actionability. По умолчанию false.

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

      Устарело

      Этот параметр не имеет эффекта.

      Этот параметр не имеет эффекта.

    • position Object (опционально)#

Точка относительно верхнего левого угла области элемента, включающей внутренние отступы (padding box). Если не указана, используется какая-либо видимая точка элемента.

  • scroll "auto" | "none" (необязательно) Добавлено в: v1.62#

    Определяет, прокручивает ли Playwright страницу, чтобы сделать элемент видимым перед выполнением действия. По умолчанию используется "auto": при необходимости элемент прокручивается в видимую область, в том числе с прокруткой вложенных прокручиваемых контейнеров. Если установлено значение "none", Playwright не выполняет прокрутку к элементу, и действие завершается ошибкой, если элемент ещё не находится в области просмотра. Это полезно для проверки того, что элемент доступен пользователю без дополнительной прокрутки.

  • signal AbortSignal (необязательно) Добавлено в: v1.62#

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и будет выброшена ошибка. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

    Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

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

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

Возвращает

Детали

Этот метод снимает отметку с элемента, выполняя следующие шаги:

  1. Убедитесь, что элемент является флажком или радио-кнопкой. Если нет, этот метод выбрасывает исключение. Если элемент уже не отмечен, этот метод возвращается немедленно.
  2. Ожидание проверок actionability на элементе, если не установлен параметр force.
  3. Прокрутка элемента в вид, если это необходимо.
  4. Использование page.mouse для нажатия в центр элемента.
  5. Убедитесь, что элемент теперь не отмечен. Если нет, этот метод выбрасывает исключение.

Если элемент отсоединен от DOM в любой момент во время действия, этот метод выбрасывает исключение.

Когда все шаги в совокупности не завершены в течение указанного timeout, этот метод выбрасывает TimeoutError. Передача нулевого таймаута отключает это.


visible​

Добавлено в: v1.63 locator.visible

Возвращает локатор, соответствующий только видимым элементам, игнорируя невидимые. Это рекомендуемый способ различать элементы по видимости, в отличие от CSS-псевдокласса :visible.

Обратите внимание, что видимость проверяется при каждом использовании локатора, а не в момент вызова locator.visible().

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

Рассмотрим страницу с двумя кнопками, первая из которых невидима, а вторая видима.

<button style='display: none'>Invisible</button>
<button>Visible</button>

Этот код найдёт только вторую кнопку, поскольку она видима, а затем нажмёт её.

await page.locator('button').visible().click();

Чтобы вместо этого находить невидимые элементы, используйте locator.filter() с параметром setVisible, установленным в false.

Возвращает


waitFor​

Добавлено в: v1.16 locator.waitFor

Возвращает, когда элемент, указанный локатором, удовлетворяет параметру state.

Если целевой элемент уже удовлетворяет условию, метод возвращается немедленно. В противном случае, ожидает до timeout миллисекунд, пока условие не будет выполнено.

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

const orderSent = page.locator('#order-sent');
await orderSent.waitFor();

Аргументы

  • options Object (необязательно)
    • signal AbortSignal (необязательно) Добавлено в: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и выбросит ошибку. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

    • state "attached" | "detached" | "visible" | "hidden" (необязательно)#

      По умолчанию 'visible'. Может быть:

      • 'attached' - ожидание, пока элемент будет присутствовать в DOM.
      • 'detached' - ожидание, пока элемент не будет присутствовать в DOM.
      • 'visible' - ожидание, пока элемент не будет иметь пустую ограничивающую рамку и visibility:hidden. Обратите внимание, что элемент без содержимого или с display:none имеет пустую ограничивающую рамку и не считается видимым.
      • 'hidden' - ожидание, пока элемент не будет отсоединен от DOM, или не будет иметь пустую ограничивающую рамку или visibility:hidden. Это противоположно опции 'visible'.
    • timeout number (опционально)#

      Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает


waitForFunction​

Добавлено в: v1.62 locator.waitForFunction

Метод завершается, когда pageFunction возвращает истинное значение (truthy). Функция вызывается с соответствующим локатору элементом в качестве первого аргумента и arg в качестве второго аргумента.

Это универсальный способ дождаться, пока элемент будет удовлетворять пользовательскому условию, без использования утверждений (assertions). При каждой повторной попытке локатор заново находит элемент, поэтому повторный рендеринг элемента во время ожидания не мешает работе метода.

Если pageFunction возвращает Promise, этот метод дождётся его выполнения, прежде чем проверять полученное значение.

Если pageFunction выбрасывает исключение или возвращает промис, который отклоняется, этот метод выбрасывает исключение.

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

Ожидание появления атрибута:

const toggle = page.getByRole('button', { name: 'Menu' });
await toggle.click();
await toggle.waitForFunction(element => element.hasAttribute('aria-expanded'));

Передача аргумента в pageFunction:

await page.getByTestId('status').waitForFunction((element, value) => {
return element.textContent === value;
}, 'Ready');

Аргументы

  • pageFunction function | string#

    Функция, выполняемая в контексте страницы.

  • arg EvaluationArgument (необязательно)#

    Необязательный аргумент для передачи в pageFunction.

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

    • signal AbortSignal (необязательно)#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и выбросит ошибку. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

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

      Максимальное время ожидания в миллисекундах. По умолчанию равно 0 — без ограничения времени ожидания. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() и page.setDefaultTimeout().

Возвращает


within​

Добавлено в: v1.64 locator.within

Возвращает локатор, который находит элементы текущего локатора внутри каждого элемента, соответствующего locator.

Обратите внимание, что относительные локаторы, такие как locator.nth() или locator.first(), разрешаются отдельно внутри каждого найденного родительского элемента. В приведённом ниже примере page.getByRole('cell').nth(2) выбирает третью ячейку каждой строки, а не третью ячейку во всей таблице.

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

const thirdColumn = page.getByRole('cell').nth(2).within(page.getByRole('row'));
await expect(thirdColumn).toHaveText(['Apple', 'Banana', 'Cherry']);

Аргументы

  • locator Locator#

    Локатор, соответствующий родительским элементам, внутри которых выполняется поиск.

Возвращает


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

elementHandle​

Добавлено в: v1.14 locator.elementHandle
Не рекомендуется

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

Разрешает данный локатор к первому соответствующему элементу DOM. Если соответствующих элементов нет, ожидает один. Если несколько элементов соответствуют локатору, выбрасывает исключение.

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

await locator.elementHandle();
await locator.elementHandle(options);

Аргументы

  • options Object (необязательный)
    • signal AbortSignal (необязательный) Добавлено в: v1.62#

      Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и будет выброшена ошибка. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

    • timeout number (необязательный)#

      Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout() методов.

Возвращает


elementHandles​

Добавлено в: v1.14 locator.elementHandles
Не рекомендуется

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

Разрешает указанный локатор ко всем соответствующим элементам DOM. Если соответствующих элементов нет, возвращает пустой список.

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

await locator.elementHandles();

Возвращает


type​

Добавлено в: v1.14 locator.type
Устарело

В большинстве случаев следует использовать locator.fill() вместо этого. Вам нужно нажимать клавиши по одной только в случае специальной обработки клавиатуры на странице - в этом случае используйте locator.pressSequentially().

Фокусируется на элементе, а затем отправляет событие keydown, keypress/input и keyup для каждого символа в тексте.

Чтобы нажать специальную клавишу, такую как Control или ArrowDown, используйте locator.press().

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

Аргументы

  • text string#

    Текст для ввода в сфокусированный элемент.

  • options Object (опционально)

    • delay number (опционально)#

      Время ожидания между нажатиями клавиш в миллисекундах. По умолчанию 0.

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

      Устарело

      Этот параметр не имеет эффекта.

Этот параметр не оказывает никакого влияния.

  • signal AbortSignal (необязательный) Добавлено в: v1.62#

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и будет выброшена ошибка. Обратите внимание, что передача сигнала не отключает тайм-аут по умолчанию, который можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • timeout number (необязательный)#

    Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает