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

Locator

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

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

Методы​

all​

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

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

примечание

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

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

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

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

for li in page.get_by_role('listitem').all():
  li.click();

Возвращает

all_inner_texts​

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

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

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

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

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

texts = page.get_by_role("link").all_inner_texts()

Возвращает

all_text_contents​

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

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

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

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

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

texts = page.get_by_role("link").all_text_contents()

Возвращает

and_​

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

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

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

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

button = page.get_by_role("button").and_(page.getByTitle("Subscribe"))

Аргументы

  • locator Locator#

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

Возвращает

aria_snapshot​

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

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

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

page.get_by_role("link").aria_snapshot()

Аргументы

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

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

Возвращает

Детали

Этот метод захватывает снимок 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"

blur​

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

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

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

locator.blur()
locator.blur(**kwargs)

Аргументы

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

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

Возвращает

bounding_box​

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

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

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

box = page.get_by_role("button").bounding_box()
page.mouse.click(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)

Аргументы

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

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

Возвращает

  • NoneType | Dict#

    • x float

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

    • y float

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

    • width float

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

    • height float

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

Детали

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

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

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

check​

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

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

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

page.get_by_role("checkbox").check()

Аргументы

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

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

  • no_wait_after bool (опционально)#

    Устарело

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

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

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

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

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

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

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

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

Возвращает

Детали

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

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

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

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

clear​

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

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

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

page.get_by_role("textbox").clear()

Аргументы

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

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

  • no_wait_after bool (опционально)#

    Устарело

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

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

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

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout() methods.

Возвращает

Детали

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

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

click​

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

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

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

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

page.get_by_role("button").click()

Щелчок с правой кнопкой мыши с удержанием Shift в определенной позиции на холсте:

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

Аргументы

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

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

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

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

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

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

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

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

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (опционально)#

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

  • no_wait_after bool (опционально)#

    Устарело

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

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

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

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

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

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout() methods.

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

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

Возвращает

Детали

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

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

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

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

count​

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

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

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

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

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

count = page.get_by_role("listitem").count()

Возвращает

dblclick​

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

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

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

locator.dblclick()
locator.dblclick(**kwargs)

Аргументы

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

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

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

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

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

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

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (опционально)#

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

  • no_wait_after bool (опционально)#

    Устарело

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

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

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

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

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

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

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

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

Возвращает

Детали

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

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

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

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

примечание

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

dispatch_event​

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

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

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

locator.dispatch_event("click")

Аргументы

  • type str#

    Тип DOM события: "click", "dragstart", и т.д.

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

    Опциональные свойства инициализации события.

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

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

Возвращает

Детали

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

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

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

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

data_transfer = page.evaluate_handle("new DataTransfer()")
locator.dispatch_event("#source", "dragstart", {"dataTransfer": data_transfer})

drag_to​

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

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

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

source = page.locator("#source")
target = page.locator("#target")

source.drag_to(target)
# или укажите точные позиции относительно верхних левых углов элементов:
source.drag_to(
  target,
  source_position={"x": 34, "y": 7},
  target_position={"x": 10, "y": 20}
)

Аргументы

  • target Locator#

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

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

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

  • no_wait_after bool (опционально)#

    Устарело

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

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

  • source_position Dict (опционально)#

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

  • target_position Dict (опционально)#

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

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

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

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

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

Возвращает

Детали

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

evaluate​

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

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

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

Аргументы

  • expression str#

    JavaScript выражение, которое будет выполнено в контексте браузера. Если выражение оценивается как функция, функция автоматически вызывается.

  • arg EvaluationArgument (optional)#

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

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

Возвращает

Детали

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

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

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

evaluate_all​

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

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

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

locator = page.locator("div")
more_than_ten = locator.evaluate_all("(divs, min) => divs.length > min", 10)

Аргументы

  • expression str#

    JavaScript выражение, которое будет выполнено в контексте браузера. Если выражение оценивается как функция, функция автоматически вызывается.

  • arg EvaluationArgument (optional)#

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

Возвращает

Детали

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

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

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

evaluate_handle​

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

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

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

locator.evaluate_handle(expression)
locator.evaluate_handle(expression, **kwargs)

Аргументы

  • expression str#

    JavaScript выражение, которое будет выполнено в контексте браузера. Если выражение оценивается как функция, функция автоматически вызывается.

  • arg EvaluationArgument (optional)#

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

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

Возвращает

Детали

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

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

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

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

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

fill​

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

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

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

page.get_by_role("textbox").fill("example value")

Аргументы

  • value str#

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

  • force bool (optional)#

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

  • no_wait_after bool (optional)#

    Устарело

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

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

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

Возвращает

Детали

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

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

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

filter​

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

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

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

row_locator = page.locator("tr")
# ...
row_locator.filter(has_text="text in column 1").filter(
    has=page.get_by_role("button", name="column 2 button")
).screenshot()

Аргументы

  • has Locator (optional)#

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

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

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

  • has_not Locator (optional) Добавлено в: v1.33#

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

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

  • has_not_text str | Pattern (optional) Добавлено в: v1.33#

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

  • has_text str | Pattern (optional)#

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

  • visible bool (optional) Добавлено в: v1.51#

    Соответствует только видимым или невидимым элементам.

Возвращает

focus​

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

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

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

locator.focus()
locator.focus(**kwargs)

Аргументы

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout() methods.

Возвращает

frame_locator​

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

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

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

locator = page.frame_locator("iframe").get_by_text("Submit")
locator.click()

Аргументы

  • selector str#

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

Возвращает

get_attribute​

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

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

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

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

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

locator.get_attribute(name)
locator.get_attribute(name, **kwargs)

Аргументы

  • name str#

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

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

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

Возвращает

get_by_alt_text​

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

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

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

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

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

Аргументы

  • text str | Pattern#

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

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

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

Возвращает

get_by_label​

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

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

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

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

<input aria-label="Username">
<label for="password-input">Password:</label>
<input id="password-input">
page.get_by_label("Username").fill("john")
page.get_by_label("Password").fill("secret")

Аргументы

  • text str | Pattern#

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

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

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

Возвращает

get_by_placeholder​

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

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

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

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

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

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

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

Аргументы

  • text str | Pattern#

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

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

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

Возвращает

get_by_role​

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

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

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

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

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

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

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

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

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

Аргументы

  • role "alert" | "alertdialog" | "application" | "article" | "banner" | "blockquote" | "button" | "caption" | "cell" | "checkbox" | "code" | "columnheader" | "combobox" | "complementary" | "contentinfo" | "definition" | "deletion" | "dialog" | "directory" | "document" | "emphasis" | "feed" | "figure" | "form" | "generic" | "grid" | "gridcell" | "group" | "heading" | "img" | "insertion" | "link" | "list" | "listbox" | "listitem" | "log" | "main" | "marquee" | "math" | "meter" | "menu" | "menubar" | "menuitem" | "menuitemcheckbox" | "menuitemradio" | "navigation" | "none" | "note" | "option" | "paragraph" | "presentation" | "progressbar" | "radio" | "radiogroup" | "region" | "row" | "rowgroup" | "rowheader" | "scrollbar" | "search" | "searchbox" | "separator" | "slider" | "spinbutton" | "status" | "strong" | "subscript" | "superscript" | "switch" | "tab" | "table" | "tablist" | "tabpanel" | "term" | "textbox" | "time" | "timer" | "toolbar" | "tooltip" | "tree" | "treegrid" | "treeitem"#

    Требуемая ARIA роль.

  • checked bool (опционально)#

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

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

  • disabled bool (опционально)#

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

    примечание

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

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

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

  • expanded bool (опционально)#

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

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

  • include_hidden bool (опционально)#

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

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

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

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

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

  • name str | Pattern (опционально)#

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

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

  • pressed bool (опционально)#

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

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

  • selected bool (опционально)#

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

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

Возвращает

Детали

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

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

get_by_test_id​

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

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

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

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

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

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

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

Аргументы

  • test_id str | Pattern#

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

Возвращает

Детали

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

get_by_text​

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

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

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

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

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

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

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

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

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

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

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

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

Аргументы

  • text str | Pattern#

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

  • exact bool (optional)#

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

Возвращает

Детали

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

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

get_by_title​

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

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

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

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

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

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

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

Аргументы

  • text str | Pattern#

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

  • exact bool (optional)#

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

Возвращает

highlight​

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

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

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

locator.highlight()

Возвращает

hover​

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

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

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

page.get_by_role("link").hover()

Аргументы

  • force bool (optional)#

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

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (optional)#

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

  • no_wait_after bool (optional) Добавлено в: v1.28#

    Устарело

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

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

  • position Dict (optional)#

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

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

  • trial bool (optional)#

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

Возвращает

Детали

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

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

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

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

inner_html​

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

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

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

locator.inner_html()
locator.inner_html(**kwargs)

Аргументы

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

Возвращает

inner_text​

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

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

Asserting text

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

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

locator.inner_text()
locator.inner_text(**kwargs)

Аргументы

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

Возвращает

input_value​

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

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

Asserting value

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

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

value = page.get_by_role("textbox").input_value()

Аргументы

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

Возвращает

Детали

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

is_checked​

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

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

Asserting checked state

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

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

checked = page.get_by_role("checkbox").is_checked()

Аргументы

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

Возвращает

is_disabled​

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

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

Asserting disabled state

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

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

disabled = page.get_by_role("button").is_disabled()

Аргументы

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

Возвращает

is_editable​

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

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

Asserting editable state

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

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

editable = page.get_by_role("textbox").is_editable()

Аргументы

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

Возвращает

is_enabled​

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

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

Asserting enabled state

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

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

enabled = page.get_by_role("button").is_enabled()

Аргументы

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

Возвращает

is_hidden​

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

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

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

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

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

hidden = page.get_by_role("button").is_hidden()

Аргументы

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

    Устарело

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

Возвращает

is_visible​

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

Возвращает, виден ли элемент (visible).

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

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

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

visible = page.get_by_role("button").is_visible()

Аргументы

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

    Устарело

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

Возвращает

locator​

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

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

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

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

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

Аргументы

  • selector_or_locator str | Locator#

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

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

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

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

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

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

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

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

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

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

  • has_text str | Pattern (опционально)#

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

Возвращает

nth​

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

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

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

banana = page.get_by_role("listitem").nth(2)

Аргументы

Возвращает

or_​

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

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

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

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

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

примечание

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

new_email = page.get_by_role("button", name="New")
dialog = page.get_by_text("Confirm security settings")
expect(new_email.or_(dialog).first).to_be_visible()
if (dialog.is_visible()):
  page.get_by_role("button", name="Dismiss").click()
new_email.click()

Аргументы

  • locator Locator#

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

Возвращает

press​

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

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

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

page.get_by_role("textbox").press("Backspace")

Аргументы

  • key str#

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

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

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

  • no_wait_after bool (опционально)#

    Устарело

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

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

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

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Установите 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

Возвращает

Детали

Фокусируется на элементе, а затем использует 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". При указании с модификатором модификатор нажимается и удерживается, пока не будет нажата последующая клавиша.

press_sequentially​

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

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

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

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

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

locator.press_sequentially("hello") # печатает мгновенно
locator.press_sequentially("world", delay=100) # печатает медленнее, как пользователь

Пример ввода в текстовое поле и последующей отправки формы:

locator = page.get_by_label("Password")
locator.press_sequentially("my password")
locator.press("Enter")

Аргументы

  • text str#

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

  • delay float (optional)#

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

  • no_wait_after bool (optional)#

    Устарело

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

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

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Установите 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

Возвращает

screenshot​

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

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

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

page.get_by_role("link").screenshot()

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

page.get_by_role("link").screenshot(animations="disabled", path="link.png")

Аргументы

  • animations "disabled" | "allow" (optional)#

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

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

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

  • caret "hide" | "initial" (optional)#

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

  • mask List[Locator] (optional)#

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

  • mask_color str (optional) Добавлено в: v1.35#

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

  • omit_background bool (optional)#

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

  • path Union[str, pathlib.Path] (optional)#

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

  • quality int (optional)#

    Качество изображения, от 0 до 100. Не применимо к изображениям png.

  • scale "css" | "device" (optional)#

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

    По умолчанию "device".

  • style str (optional) Добавлено в: v1.41#

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

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Установите 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

  • type "png" | "jpeg" (optional)#

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

Возвращает

Детали

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

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

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

scroll_into_view_if_needed​

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

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

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

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

locator.scroll_into_view_if_needed()
locator.scroll_into_view_if_needed(**kwargs)

Аргументы

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Установите 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout() methods.

Возвращает

select_option​

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

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

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

<select multiple>
  <option value="red">Red</option>
  <option value="green">Green</option>
  <option value="blue">Blue</option>
</select>
# одиночный выбор, соответствующий значению или метке
element.select_option("blue")
# одиночный выбор, соответствующий метке
element.select_option(label="blue")
# множественный выбор для blue, red и второй опции
element.select_option(value=["red", "green", "blue"])

Аргументы

  • force bool (optional)#

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

  • no_wait_after bool (optional)#

    Устарело

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

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

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Установите 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout() methods.

  • element ElementHandle | List[ElementHandle] (optional)#

    Элементы опций для выбора. Необязательно.

  • index int | List[int] (optional)#

    Опции для выбора по индексу. Необязательно.

  • value str | List[str] (optional)#

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

  • label str | List[str] (optional)#

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

Возвращает

Детали

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

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

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

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

select_text​

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

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

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

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

locator.select_text()
locator.select_text(**kwargs)

Аргументы

  • force bool (optional)#

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

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

Возвращает

set_checked​

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

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

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

page.get_by_role("checkbox").set_checked(True)

Аргументы

  • checked bool#

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

  • force bool (optional)#

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

  • no_wait_after bool (optional)#

    Deprecated

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

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

  • position Dict (optional)#

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

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

  • trial bool (optional)#

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

Возвращает

Детали

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

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

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

set_input_files​

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

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

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

# Выберите один файл
page.get_by_label("Upload file").set_input_files('myfile.pdf')

# Выберите несколько файлов
page.get_by_label("Upload files").set_input_files(['file1.txt', 'file2.txt'])

# Выберите каталог
page.get_by_label("Upload directory").set_input_files('mydir')

# Удалите все выбранные файлы
page.get_by_label("Upload file").set_input_files([])

# Загрузите буфер из памяти
page.get_by_label("Upload file").set_input_files(
    files=[
        {"name": "test.txt", "mimeType": "text/plain", "buffer": b"this is a test"}
    ],
)

Аргументы

  • files Union[str, pathlib.Path] | List[Union[str, pathlib.Path]] | Dict | List[Dict]#

    • name str

      Имя файла

    • mimeType str

      Тип файла

    • buffer bytes

      Содержимое файла

  • no_wait_after bool (optional)#

    Deprecated

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

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

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout() methods.

Возвращает

Детали

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

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

tap​

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

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

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

locator.tap()
locator.tap(**kwargs)

Аргументы

  • force bool (optional)#

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

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (optional)#

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

  • no_wait_after bool (optional)#

    Deprecated

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

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

  • position Dict (optional)#

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

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout() methods.

  • trial bool (optional)#

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

Возвращает

Детали

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

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

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

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

примечание

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

text_content​

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

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

Asserting text

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

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

locator.text_content()
locator.text_content(**kwargs)

Аргументы

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout() methods.

Возвращает

uncheck​

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

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

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

page.get_by_role("checkbox").uncheck()

Аргументы

  • force bool (optional)#

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

  • no_wait_after bool (optional)#

    Устарело

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

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

  • position Dict (optional)#

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

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

  • trial bool (optional)#

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

Возвращает

Детали

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

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

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

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

wait_for​

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

Возвращает, когда элемент, указанный локатором, удовлетворяет параметру state.

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

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

order_sent = page.locator("#order-sent")
order_sent.wait_for()

Аргументы

  • state "attached" | "detached" | "visible" | "hidden" (optional)#

    По умолчанию 'visible'. Может быть:

    • 'attached' - ожидание, пока элемент будет присутствовать в DOM.
    • 'detached' - ожидание, пока элемент не будет присутствовать в DOM.
    • 'visible' - ожидание, пока элемент не будет иметь пустую ограничивающую рамку и visibility:hidden. Обратите внимание, что элемент без содержимого или с display:none имеет пустую ограничивающую рамку и не считается видимым.
    • 'hidden' - ожидание, пока элемент не будет отсоединен от DOM, или иметь пустую ограничивающую рамку или visibility:hidden. Это противоположно опции 'visible'.

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

Возвращает

Свойства​

content_frame​

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

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

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

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

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

locator = page.locator("iframe[name=\"embedded\"]")
# ...
frame_locator = locator.content_frame
frame_locator.get_by_role("button").click()

Возвращает

first​

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

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

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

locator.first

Возвращает

last​

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

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

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

banana = page.get_by_role("listitem").last

Возвращает

page​

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

Страница, к которой принадлежит этот локатор.

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

locator.page

Возвращает

Устарело​

element_handle​

Добавлено в: v1.14 locator.element_handle
Не рекомендуется

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

Разрешает данный локатор к первому совпадающему DOM элементу. Если совпадающих элементов нет, ожидает один. Если несколько элементов соответствуют локатору, выбрасывает исключение.

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

locator.element_handle()
locator.element_handle(**kwargs)

Аргументы

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout() методы.

Возвращает

element_handles​

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

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

Разрешает указанный локатор для всех соответствующих элементов DOM. Если соответствующих элементов нет, возвращает пустой список.

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

locator.element_handles()

Возвращает

type​

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

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

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

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

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

Аргументы

  • text str#

    Текст для ввода в сфокусированный элемент.

  • delay float (optional)#

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

  • no_wait_after bool (optional)#

    Deprecated

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

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

  • timeout float (optional)#

    Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы browser_context.set_default_timeout() или page.set_default_timeout().

Возвращает