Локатор

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

Подробнее о локаторах.

Методы​

all​

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

примечание

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

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

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

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

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

Возвращает

• Promise<Array<Locator>>

allInnerTexts​

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

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

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

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

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

Возвращает

• Promise<Array<string>>

allTextContents​

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

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

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

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

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

Возвращает

• Promise<Array<string>>

and​

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

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

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

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

Аргументы

• locator Locator

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

Возвращает

• Locator

ariaSnapshot​

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

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

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

Аргументы

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

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

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

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

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

  • mode "ai" | "default" (необязательно)

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

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<string>

Подробности

Этот метод создаёт снимок 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> внутри целевого элемента.

ariaSnapshotJSON​

Создаёт снимок ARIA указанного элемента в виде JSON-объекта произвольной структуры.

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

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

Аргументы

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

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

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

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

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

  • mode "ai" | "default" (необязательно)

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

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<Serializable>

Подробности

Этот метод возвращает то же дерево, что и 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​

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

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

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

Аргументы

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

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<void>

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 (необязательно)

    Позволяет отменить операцию с помощью 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​

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

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

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

Аргументы

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

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

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

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

    Устарело

    Этот параметр не влияет на результат.

    Этот параметр не влияет на результат.

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

    • x number

    • y number

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

  • scroll "auto" | "none" (необязательно)

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

  • signal AbortSignal (необязательно)

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

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

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

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

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

Возвращает

• Promise<void>

Подробности

Выполняет следующие действия:

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

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

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

clear​

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

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

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

Аргументы

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

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

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

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

    Устарело

    Этот параметр не влияет на результат.

    Этот параметр не влияет на результат.

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<void>

Подробности

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

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

click​

Нажимает на элемент.

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

Нажмите кнопку:

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

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

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 (необязательно)

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

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

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

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

    Устарело

    В будущем значение этого параметра по умолчанию будет true.

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

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

    • x number

    • y number

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

  • scroll "auto" | "none" (необязательно)

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

  • signal AbortSignal (необязательно)

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

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

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

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

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

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

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

Возвращает

• Promise<void>

Подробности

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

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

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

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

contentFrame​

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

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

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

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

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

Возвращает

• FrameLocator

count​

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

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

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

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

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

Возвращает

• Promise<number>

dblclick​

Дважды щёлкает по элементу.

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

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

Аргументы

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

  • button "left" | "right" | "middle" (необязательно)

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

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

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

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

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

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

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

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

    Устарело

    Этот параметр не влияет на результат.

    Этот параметр не влияет на результат.

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

    • x number

    • y number

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

  • scroll "auto" | "none" (необязательно)

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

  • signal AbortSignal (необязательно)

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

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

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

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

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

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

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

Возвращает

• Promise<void>

Подробности

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

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

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

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

примечание

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

describe​

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

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

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

Аргументы

• description string

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

Возвращает

• 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

Возвращает

• null | string

dispatchEvent​

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

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

await locator.dispatchEvent('click');

Аргументы

• type string

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

• eventInit EvaluationArgument (необязательно)

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

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

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<void>

Подробности

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

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

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

• DeviceMotionEvent
• DeviceOrientationEvent
• DragEvent
• Event
• FocusEvent
• KeyboardEvent
• MouseEvent
• PointerEvent
• TouchEvent
• WheelEvent

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

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

dragTo​

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

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

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

await source.dragTo(target);
// or specify exact positions relative to the top-left corners of the elements:
await source.dragTo(target, {
  sourcePosition: { x: 34, y: 7 },
  targetPosition: { x: 10, y: 20 },
});

Аргументы

• target Locator

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

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

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

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

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

    Устарело

    Этот параметр не влияет на результат.

    Этот параметр не влияет на результат.

  • scroll "auto" | "none" (необязательно)

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

  • signal AbortSignal (необязательно)

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

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

    • x number

    • y number

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

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

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

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

    • x number

    • y number

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

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

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

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

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

Возвращает

• Promise<void>

Подробности

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

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 string | Array<string> | Object | Array<Object> (необязательно)

    • name string

      Имя файла

    • mimeType string

      Тип файла

    • buffer Buffer

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

  • data Object<string, string> (необязательно)

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

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

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

    • x number

    • y number

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

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<void>

Подробности

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

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

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 (необязательно)

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

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<Serializable>

Подробности

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

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

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

evaluateAll​

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

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

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

Аргументы

• pageFunction function | string

  Функция, которую нужно выполнить в контексте страницы.

• arg EvaluationArgument (необязательно)

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

Возвращает

• Promise<Serializable>

Подробности

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

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

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

evaluateHandle​

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

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

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

Аргументы

• pageFunction function | string

  Функция, которую нужно выполнить в контексте страницы.

• arg EvaluationArgument (необязательно)

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

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

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

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

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<JSHandle>

Подробности

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

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

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

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

Подробнее см. в описании page.evaluateHandle().

fill​

Задать значение поля ввода.

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

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

Аргументы

• value string

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

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

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

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

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

    Устарело

    Этот параметр не влияет на результат.

    Этот параметр не влияет на результат.

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<void>

Подробности

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

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

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

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.

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

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

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

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

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

    Соответствует элементам, внутри которых нет указанного текста, в том числе в дочерних или вложенных элементах. Если передана строка string, поиск подстроки выполняется без учёта регистра.

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

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

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

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

Возвращает

• Locator

first​

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

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

locator.first();

Возвращает

• Locator

focus​

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

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

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

Аргументы

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

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<void>

frameLocator​

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

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

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

Аргументы

• selector string

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

Возвращает

• FrameLocator

getAttribute​

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

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

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

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

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

Аргументы

• name string

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

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

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<null | string>

getByAltText​

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

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

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

<img alt='Playwright logo'>

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

Аргументы

• text string | RegExp

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

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

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

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

Возвращает

• Locator

getByLabel​

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

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

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

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

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

Аргументы

• text string | RegExp

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

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

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

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

Возвращает

• Locator

getByPlaceholder​

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

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

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

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

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

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

Аргументы

• text string | RegExp

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

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

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

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

Возвращает

• Locator

getByRole​

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

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

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

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

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

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

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

await page.getByRole('button', { name: /submit/i }).click();

Аргументы

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

  Обязательная роль ARIA.

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

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

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

    Подробнее об атрибуте aria-checked.

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

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

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

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

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

    Примечание

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

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

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

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

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

    Подробнее об атрибуте aria-expanded.

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

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

    Подробнее об атрибуте aria-hidden.

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

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

    Подробнее об атрибуте aria-level.

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

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

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

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

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

    Подробнее об атрибуте aria-pressed.

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

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

    Подробнее об атрибуте aria-selected.

Возвращает

• Locator

Подробности

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

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

getByTestId​

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

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

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

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

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

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

Аргументы

• testId string | RegExp

  Идентификатор, по которому нужно найти элемент.

Возвращает

• Locator

Подробности

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

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

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

getByText​

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

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

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

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

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

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

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

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

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

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

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

Аргументы

• text string | RegExp

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

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

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

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

Возвращает

• Locator

Подробности

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

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

getByTitle​

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

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

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

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

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

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

Аргументы

• text string | RegExp

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

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

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

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

Возвращает

• Locator

hideHighlight​

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

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

await locator.hideHighlight();

Возвращает

• Promise<void>

highlight​

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

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

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

Аргументы

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

  • style string | Object<string, string | number> (необязательно)

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

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

Возвращает

• Promise<Disposable>

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 (необязательно)

    Устарело

    Этот параметр не влияет на результат.

    Этот параметр не влияет на результат.

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

    • x number

    • y number

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

  • scroll "auto" | "none" (необязательно)

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

  • signal AbortSignal (необязательно)

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

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

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

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

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

Возвращает

• Promise<void>

Подробности

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

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

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

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

innerHTML​

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

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

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

Аргументы

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

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<string>

innerText​

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

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

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

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

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

Аргументы

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

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<string>

inputValue​

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

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

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

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

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

Аргументы

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

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<string>

Подробности

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

isChecked​

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

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

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

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

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

Аргументы

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

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<boolean>

isDisabled​

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

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

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

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

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

Аргументы

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

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<boolean>

isEditable​

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

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

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

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

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

Аргументы

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

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<boolean>

isEnabled​

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

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

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

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

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

Аргументы

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

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<boolean>

isHidden​

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

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

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

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

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

Аргументы

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

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

    Устарело

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

Возвращает

• Promise<boolean>

isVisible​

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

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

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

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

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

Аргументы

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

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

    Устарело

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

Возвращает

• Promise<boolean>

last​

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

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

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

Возвращает

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

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

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

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

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

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

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

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

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

Возвращает

• Locator

normalize​

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

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

await locator.normalize();

Возвращает

• Promise<Locator>

nth​

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

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

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

Аргументы

• index number

Возвращает

• Locator

or​

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

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

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

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

примечание

Если на экране появятся и кнопка «Новое письмо», и диалоговое окно настроек безопасности, локатор «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

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

Возвращает

• Locator

page​

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

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

locator.page();

Возвращает

• Page

press​

Устанавливает фокус на соответствующий элемент и нажимает сочетание клавиш.

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

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

Аргументы

• key string

  Имя клавиши, которую нужно нажать, или символа, который нужно сгенерировать, например ArrowLeft или a.

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

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

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

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

    Устарело

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

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

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<void>

Подробности

Переводит фокус на элемент, а затем вызывает 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​

совет

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

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

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

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

await locator.pressSequentially('Hello'); // Types instantly
await locator.pressSequentially('World', { delay: 100 }); // Types slower, like a user

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

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 (необязательно)

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

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

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

Возвращает

• Promise<void>

screenshot​

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

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

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

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

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

Аргументы

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

  • animations "disabled" | "allow" (необязательно)

    Если задано значение "disabled", останавливает CSS-анимацию, CSS-переходы и Web Animations. Обработка анимации зависит от её длительности:

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

    По умолчанию используется значение "allow", при котором анимация не затрагивается.

  • caret "hide" | "initial" (необязательно)

    Если задано значение "hide", курсор в тексте будет скрыт на снимке экрана. Если задано значение "initial", поведение курсора в тексте не изменится. По умолчанию — "hide".

  • mask Array<Locator> (необязательно)

    Укажите локаторы элементов, которые нужно замаскировать при создании снимка экрана. Поверх замаскированных элементов будет наложен розовый прямоугольник #FF00FF (цвет можно изменить с помощью maskColor), полностью закрывающий их ограничивающую рамку. Маска также применяется к невидимым элементам. Чтобы отключить это, см. раздел Выбор только видимых элементов.

  • maskColor string (необязательно)

    Задаёт цвет прямоугольника, накладываемого на замаскированные элементы, в формате цвета CSS. Цвет по умолчанию — розовый #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 (необязательно)

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

  • style string (необязательно)

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

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

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

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

    Задаёт тип снимка экрана. По умолчанию — png.

Возвращает

• Promise<Buffer>

Подробности

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

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

Возвращает буфер с созданным снимком экрана.

scrollIntoViewIfNeeded​

Метод ожидает прохождения проверок возможности взаимодействия, а затем пытается прокрутить страницу до появления элемента в области просмотра, если только он уже полностью не виден согласно ratio объекта IntersectionObserver.

Другие способы прокрутки см. в разделе Прокрутка.

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

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

Аргументы

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

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<void>

selectOption​

Выбирает один или несколько вариантов в <select>.

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

<select multiple>
  <option value="red">Red</option>
  <option value="green">Green</option>
  <option value="blue">Blue</option>
</select>

// single selection matching the value or label
element.selectOption('blue');

// single selection matching the label
element.selectOption({ label: 'Blue' });

// multiple selection for red, green and blue options
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 (необязательно)

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

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

    Устарело

    Этот параметр не влияет на результат.

    Этот параметр не влияет на результат.

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<Array<string>>

Подробности

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

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

Возвращает массив значений выбранных вариантов.

После выбора всех переданных вариантов вызывает события change и input.

selectText​

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

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

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

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

Аргументы

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

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

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

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<void>

setChecked​

Задаёт состояние флажка или переключателя.

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

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

Аргументы

• checked boolean

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

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

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

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

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

    Устарело

    Эта опция не влияет на работу.

    Эта опция не влияет на работу.

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

    • x number

    • y number

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

  • scroll "auto" | "none" (необязательно)

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

  • signal AbortSignal (необязательно)

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

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

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

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

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

Возвращает

• Promise<void>

Подробности

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

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

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

setInputFiles​

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

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

// Select one file
await page.getByLabel('Upload file').setInputFiles(path.join(__dirname, 'myfile.pdf'));

// Select multiple files
await page.getByLabel('Upload files').setInputFiles([
  path.join(__dirname, 'file1.txt'),
  path.join(__dirname, 'file2.txt'),
]);

// Select a directory
await page.getByLabel('Upload directory').setInputFiles(path.join(__dirname, 'mydir'));

// Remove all the selected files
await page.getByLabel('Upload file').setInputFiles([]);

// Upload buffer from memory
await page.getByLabel('Upload file').setInputFiles({
  name: 'file.txt',
  mimeType: 'text/plain',
  buffer: Buffer.from('this is test')
});

Аргументы

• files string | Array<string> | Object | Array<Object>

  • name string

    Имя файла

  • mimeType string

    Тип файла

  • buffer Buffer

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

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

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

    Устарело

    Эта опция не влияет на работу.

    Эта опция не влияет на работу.

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<void>

Подробности

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

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

tap​

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

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

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

Аргументы

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

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

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

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

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

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

    Устарело

    Эта опция не влияет на работу.

    Эта опция не влияет на работу.

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

    • x number

    • y number

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

  • scroll "auto" | "none" (необязательно)

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

  • signal AbortSignal (необязательно)

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

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

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

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

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

Возвращает

• Promise<void>

Подробности

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

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

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

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

примечание

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

textContent​

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

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

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

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

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

Аргументы

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

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<null | string>

toString​

Возвращает удобное для чтения представление локатора, используя locator.description(), если оно задано; в противном случае формирует строку на основе селектора локатора.

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

locator.toString();

Возвращает

• string

uncheck​

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

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

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

Аргументы

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

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

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

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

    Устарело

    Эта опция не влияет на работу.

    Эта опция не влияет на работу.

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

    • x number

    • y number

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

  • scroll "auto" | "none" (необязательно)

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

  • signal AbortSignal (необязательно)

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

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

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

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

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

Возвращает

• Promise<void>

Подробности

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

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

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

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

visible​

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

Обратите внимание: видимость проверяется каждый раз при использовании локатора, а не в момент вызова locator.visible().

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

Предположим, на странице есть две кнопки: первая невидима, а вторая видима.

<button style='display: none'>Invisible</button>
<button>Visible</button>

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

await page.locator('button').visible().click();

Чтобы вместо этого выбрать невидимые элементы, используйте locator.filter() с опцией visible, установленной в false.

Возвращает

• Locator

waitFor​

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

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

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

const orderSent = page.locator('#order-sent');
await orderSent.waitFor();

Аргументы

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

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью 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().

Возвращает

• Promise<void>

waitForFunction​

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

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

Если 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().

Возвращает

• Promise<void>

Устаревшее​

elementHandle​

Не рекомендуется

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

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

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

await locator.elementHandle();
await locator.elementHandle(options);

Аргументы

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

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<ElementHandle>

elementHandles​

Не рекомендуется

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

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

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

await locator.elementHandles();

Возвращает

• Promise<Array<ElementHandle>>

type​

Устарело

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

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

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

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

Аргументы

• text string

  Текст для ввода в элемент, находящийся в фокусе.

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

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

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

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

    Устарело

    Этот параметр не влияет на результат.

    Этот параметр не влияет на результат.

  • signal AbortSignal (необязательно)

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

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

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

Возвращает

• Promise<void>