Локатор

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

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

Методы

all

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

примечание

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

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

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

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

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

Возвращает

Promise<Массив<Локатор>>

allInnerTexts

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

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

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

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

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

Возвращает

Promise<Массив<строка>>

allTextContents

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

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

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

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

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

Возвращает

Promise<Массив<строка>>

and

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

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

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

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

Аргументы

locator Локатор

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

Возвращает

Локатор

ariaSnapshot

Захватывает снимок ARIA заданного элемента. Подробнее см. снимки ARIA и expect(locator).toMatchAriaSnapshot() для соответствующего утверждения.

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

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

Аргументы

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

Возвращает

Promise<строка>

Подробности

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

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

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

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

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

- list "Links":
  - listitem:
    - link "Home"
  - listitem:
    - link "About"

blur

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

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

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

Аргументы

options Объект (необязательно)
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 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 Объект (необязательно)
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — без таймаута. Значение по умолчанию можно изменить через опцию actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

Promise<null | Object>
- x число
  
  координата x элемента в пикселях.
- y число
  
  координата y элемента в пикселях.
- width число
  
  ширина элемента в пикселях.
- height число
  
  высота элемента в пикселях.

Подробности

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

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

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

проверка

Убедитесь, что элемент типа checkbox или радиокнопки выбран.

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

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

Аргументы

options Объект (необязательно)
- force логическое значение (необязательно)
  
  Пропустить проверки активности. По умолчанию false.
- noWaitAfter логическое значение (необязательно)
  
  Устарело
  
  Этот параметр не имеет эффекта.
  
  Этот параметр не имеет эффекта.
- position Объект (необязательно)
  - x число
  - y число
  Точка, используемая относительно верхнего левого угла области заполнения элемента. Если не указана, используется какая-либо видимая точка элемента.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().
- trial логическое значение (необязательно)
  
  В случае установки, этот метод выполняет только проверки активности и пропускает действие. По умолчанию false. Полезно для ожидания готовности элемента к действию без его выполнения.

Возвращает

Promise<void>

Подробности

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

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

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

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

очистка

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

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

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

Аргументы

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

Возвращает

Promise<void>

Подробности

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

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

щелчок

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

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

Нажать на кнопку:

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

Нажать правой кнопкой мыши со смещением на определенной позиции на холсте:

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

Аргументы

options Объект (необязательно)
- button "слева" | "справа" | "посередине" (необязательно)
  
  По умолчанию left.
- clickCount число (необязательно)
  
  по умолчанию 1. См. UIEvent.detail.
- delay число (необязательно)
  
  Время ожидания между mousedown и mouseup в миллисекундах. По умолчанию 0.
- force логическое значение (необязательно)
  
  Пропустить проверки действительности действия. По умолчанию false.
- modifiers Массив<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (необязательно)
  
  Ключи модификаторов для нажатия. Гарантирует нажатие только этих модификаторов во время операции, а затем восстанавливает текущие модификаторы. Если не указано, используются текущие нажатые модификаторы. "ControlOrMeta" разрешается в "Control" в Windows и Linux и в "Meta" в macOS.
- noWaitAfter логическое значение (необязательно)
  
  Устарело
  
  В будущем этот параметр будет по умолчанию true.
  
  Действия, которые инициируют навигацию, ожидают, пока эти навигации произойдут и страницы начнут загружаться. Вы можете отказаться от ожидания, установив этот флаг. Вам потребуется этот параметр только в исключительных случаях, таких как навигация к недоступным страницам. По умолчанию false.
- position Объект (необязательно)
  - x число
  - y число
  Точка для использования относительно верхнего левого угла области отступа элемента. Если не указано, используется какая-то видимая точка элемента.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 - нет таймаута. Значение по умолчанию может быть изменено с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().
- trial логическое значение (необязательно)
  
  При установке этот метод выполняет только проверки действительности действия и пропускает его. По умолчанию false. Полезно дождаться, пока элемент будет готов к действию, не выполняя его. Обратите внимание, что нажатие клавиатурных modifiers будет выполняться независимо от trial для проверки элементов, которые видны только при нажатии этих клавиш.

Возвращает

Обещание<пустое>

Подробное описание

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

Ожидание проверок действительности действия на элементе, если параметр force не установлен.
Прокрутка элемента в видимую область при необходимости.
Использование page.mouse для нажатия в центре элемента или указанной позиции.
Ожидание завершения инициированных навигаций, если параметр 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();

Возвращает

Обещание<число>

dblclick

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

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

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

Аргументы

options Объект (необязательно)
- button "слева" | "справа" | "посередине" (необязательно)
  
  По умолчанию left.
- delay число (необязательно)
  
  Время ожидания между mousedown и mouseup в миллисекундах. По умолчанию 0.
- force булево (необязательно)
  
  Пропустить проверки действительности. По умолчанию false.
- modifiers Массив<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (необязательно)
  
  Модификаторы клавиш. Обеспечивает нажатие только этих модификаторов во время операции, а затем восстанавливает текущие модификаторы. Если не указано, используются текущие нажатые модификаторы. "ControlOrMeta" преобразуется в "Control" в Windows и Linux и в "Meta" в macOS.
- noWaitAfter булево (необязательно)
  
  Устарело
  
  Этот параметр не имеет эффекта.
  
  Этот параметр не имеет эффекта.
- position Объект (необязательно)
  - x число
  - y число
  Точка, используемая относительно верхнего левого угла области отступа элемента. Если не указано, используется какая-то видимая точка элемента.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — без таймаута. Значение по умолчанию можно изменить через параметр actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().
- trial булево (необязательно)
  
  При установке этот метод выполняет только проверки действительности и пропускает действие. По умолчанию false. Полезно для ожидания готовности элемента к действию без его выполнения. Обратите внимание, что нажатие клавиш modifiers будет выполняться независимо от trial для тестирования элементов, которые видны только при нажатии этих клавиш.

Возвращает

Promise<void>

Подробности

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

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

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

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

Примечание

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

dispatchEvent

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

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

await locator.dispatchEvent('click');

Аргументы

type строка

Тип события DOM: "click", "dragstart", и т.д.
eventInit EvaluationArgument (необязательно)

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

Возвращает

Promise<void>

Подробности

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

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

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

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

// Note you can only create DataTransfer in Chromium and Firefox
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 Объект (необязательно)
- force boolean (необязательно)
  
  Игнорировать проверки действительности действия. По умолчанию false.
- noWaitAfter boolean (необязательно)
  
  Устаревшее
  
  Этот параметр не имеет эффекта.
  
  Этот параметр не имеет эффекта.
- sourcePosition Объект (необязательно)
  - x число
  - y число
  Координаты клика на исходном элементе относительно верхнего левого угла области отступа элемента. Если не указаны, используется какая-либо видимая точка элемента.
- targetPosition Объект (необязательно)
  - x число
  - y число
  Координаты отпуска на целевом элементе относительно верхнего левого угла области отступа элемента. Если не указаны, используется какая-либо видимая точка элемента.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или используя методы browserContext.setDefaultTimeout() или page.setDefaultTimeout().
- trial boolean (необязательно)
  
  Если установлено, метод выполняет только проверки действительности действия и пропускает его. По умолчанию false. Полезно для ожидания готовности элемента к действию без его выполнения.

Возвращает

Promise<void>

Подробности

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

evaluate

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

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

const tweets = page.locator('.tweet .retweets');
expect(await tweets.evaluate(node => node.innerText)).toBe('10 retweets');

Аргументы

pageFunction функция | строка

Функция, которая будет выполнена в контексте страницы.
arg EvaluationArgument (необязательно)

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

Возвращает

Promise<Сериализуемый>

Подробности

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

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

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

evaluateAll

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

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

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

Аргументы

pageFunction функция | строка

Функция, которая будет выполнена в контексте страницы.
arg EvaluationArgument (необязательно)

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

Возвращает

Promise<Сериализуемый>

Подробности

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

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

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

evaluateHandle

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

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

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

Аргументы

pageFunction функция | строка

Функция, которая будет выполнена в контексте страницы.
arg EvaluationArgument (необязательно)

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

Возвращает

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 строка

Значение для установки для элемента <input>, <textarea> или [contenteditable].
options Объект (необязательно)
- force логическое значение (необязательно)
  
  Указывает, нужно ли пропустить проверки actionability. По умолчанию false.
- noWaitAfter логическое значение (необязательно)
  
  Устарело
  
  Этот параметр не имеет эффекта.
  
  Этот параметр не имеет эффекта.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию может быть изменено с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращаемое значение

Promise<void>

Подробности

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

Для отправки событий клавиатуры с высокой точностью используйте 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 Объект (необязательно)
- 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 строка | RegExp (необязательно)
  
  Соответствует элементам, которые не содержат указанный текст где-то внутри, возможно, в дочернем или потомке. При передаче строки соответствие регистронезависимое и ищет подстроку.
- hasText строка | RegExp (необязательно)
  
  Соответствует элементам, содержащим указанный текст где-то внутри, возможно, в дочернем или потомке. При передаче строки соответствие регистронезависимое и ищет подстроку. Например, "Playwright" соответствует <article><div>Playwright</div></article>.

Возвращаемое значение

Locator

first

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

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

locator.first();

Возвращаемое значение

Locator

focus

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

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

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

Аргументы

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

Возвращаемое значение

Promise<void>

frameLocator

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

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

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

Аргументы

selector строка

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

Возвращаемое значение

FrameLocator

getAttribute

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

Утверждение атрибутов

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

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

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

Аргументы

name строка

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

Возвращает

Promise<null | строка>

getByAltText

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

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

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

<img alt='Playwright logo'>

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

Аргументы

text строка | RegExp

Текст для поиска элемента.
options Объект (необязательно)
- exact булево (необязательно)
  
  Необходимо ли найти точное совпадение: регистрозависимое и по всему тексту. По умолчанию 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 строка | RegExp

Текст для поиска элемента.
options Объект (необязательно)
- exact булево (необязательно)
  
  Необходимо ли найти точное совпадение: регистрозависимое и по всему тексту. По умолчанию false. Игнорируется при поиске по регулярному выражению. Обратите внимание, что точное совпадение всё равно обрезает пробелы.

Возвращает

Locator

getByPlaceholder

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

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

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

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

Вы можете заполнить поле ввода после его нахождения по заглушке:

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

Аргументы

text строка | RegExp

Текст для поиска элемента.
options Объект (необязательно)
- exact булево (необязательно)
  
  Необходимо ли найти точное совпадение: регистрозависимое и по всему тексту. По умолчанию 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.
- disabled boolean (необязательно)
  
  Атрибут, который обычно устанавливается aria-disabled или disabled.
  
  примечание
  
  В отличие от большинства других атрибутов, disabled наследуется через иерархию DOM. Узнайте больше о aria-disabled.
- exact boolean (необязательно)
  
  Указывает, соответствует ли имя точно: регистрозависимо и по всему строке. По умолчанию значение false. Игнорируется, когда имя представляет собой регулярное выражение. Обратите внимание, что точное совпадение все равно обрезает пробелы.
- expanded boolean (необязательно)
  
  Атрибут, обычно устанавливаемый aria-expanded.
  
  Узнайте больше о aria-expanded.
- includeHidden boolean (необязательно)
  
  Параметр, определяющий, включать ли в соответствие скрытые элементы. По умолчанию выбираются только нескрытые элементы, как определено ARIA, при использовании селектора по роли.
  
  Узнайте больше о aria-hidden.
- level number (необязательно)
  
  Числовой атрибут, обычно присутствующий для ролей heading, listitem, row, treeitem, с значениями по умолчанию для элементов <h1>-<h6>.
  
  Узнайте больше о aria-level.
- name string | RegExp (необязательно)
  
  Вариант для соответствия доступному имени. По умолчанию соответствие регистронезависимое и ищет подстроку, используйте exact для управления этим поведением.
  
  Узнайте больше о доступном имени.
- pressed boolean (необязательно)
  
  Атрибут, обычно устанавливаемый aria-pressed.
  
  Узнайте больше о aria-pressed.
- selected boolean (необязательно)
  
  Атрибут, обычно устанавливаемый aria-selected.
  
  Узнайте больше о aria-selected.

Возвращает

Locator

Подробности

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

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

getByTestId

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

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

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

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

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

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

Аргументы

testId string | RegExp

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

Возвращает

Locator

Подробности

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

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

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

getByText

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

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

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

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

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

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

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

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

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

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

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

Аргументы

text string | RegExp

Текст для поиска элемента.
options Object (необязательно)
- exact boolean (необязательно)
  
  Требовать точное соответствие: регистрозависимое и по всей строке. По умолчанию false. Игнорируется при поиске по регулярному выражению. Точное соответствие все равно обрезает пробелы.

Возвращает

Locator

Подробности

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

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

getByTitle

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

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

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

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

Вы можете проверить количество проблем после нахождения элемента по текстовому значению title:

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

Аргументы

text строка | RegExp

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

Возвращает

Объект поиска

highlight

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

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

await locator.highlight();

Возвращает

Promise<void>

hover

Наведет указатель мыши на соответствующий элемент.

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

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

Аргументы

options Объект (необязательно)
- force логическое значение (необязательно)
  
  Пропустить проверки действия. По умолчанию false.
- modifiers Массив<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (необязательно)
  
  Модификаторы клавиш для нажатия. Гарантирует, что нажаты только эти модификаторы, а затем восстанавливает текущие модификаторы. Если не указано, используются текущие нажатые модификаторы. "ControlOrMeta" отображается как "Control" в Windows и Linux и как "Meta" в macOS.
- noWaitAfter логическое значение (необязательно)
  
  Устарело
  
  Этот параметр не оказывает никакого влияния.
  
  Этот параметр не оказывает никакого влияния.
- position Объект (необязательно)
  - x число
  - y число
  Точка для использования относительно верхнего левого угла области отступа элемента. Если не указано, используется какая-то видимая точка элемента.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().
- trial логическое значение (необязательно)
  
  Если установлено, этот метод выполняет только проверки действия и пропускает действие. По умолчанию false. Полезно дождаться готовности элемента для действия, не выполняя его. Обратите внимание, что нажатие клавиш modifiers будет выполняться независимо от trial, чтобы разрешить тестирование элементов, которые видны только при нажатии этих клавиш.

Возвращает

Promise<void>

Подробности

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

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

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

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

innerHTML

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

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

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

Аргументы

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

Возвращает

Promise<строка>

innerText

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

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

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

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

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

Аргументы

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

Возвращает

Promise<строка>

inputValue

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

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

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

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

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

Аргументы

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

Возвращает

Promise<строка>

Подробности

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

isChecked

Возвращает, проверено ли состояние элемента. Бросает исключение, если элемент не является чекбоксом или радиокнопкой.

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

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

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

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

Аргументы

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

Возвращает

Promise<булево значение>

isDisabled

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

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

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

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

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

Аргументы

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

Возвращает

Promise<булево значение>

isEditable

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

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

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

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

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

Аргументы

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

Возвращает

Promise<булево значение>

isEnabled

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

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

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

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

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

Аргументы

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

Возвращает

Promise<булево значение>

isHidden

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

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

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

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

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

Аргументы

options Объект (необязательно)
- timeout число (необязательно)
  
  Устарело
  
  Эта опция игнорируется. locator.isHidden() не ждет, пока элемент станет скрытым, и возвращает значение сразу же.

Возвращает

Promise<булево значение>

isVisible

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

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

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

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

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

Аргументы

options Object (необязательно)
- timeout число (необязательно)
  
  Устаревшее
  
  Этот параметр игнорируется. locator.isVisible() не ожидает, пока элемент станет видимым, и возвращает значение немедленно.

Возвращает

Promise<логическое значение>

last

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

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

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

Возвращает

Локатор

locator

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

Дополнительная информация о локаторах.

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

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

Аргументы

selectorOrLocator строка | Локатор

Селектор или локатор, используемый при разрешении DOM-элемента.
options Объект (необязательно)
- has Локатор (необязательно)
  
  Сужает результаты метода до тех, которые содержат элементы, соответствующие этому относительному локатору. Например, article содержащий text=Playwright совпадает с <article><div>Playwright</div></article>.
  
  Внутренний локатор должен быть относительным к внешнему локатору и запрашивается, начиная с совпадения внешнего локатора, а не с корня документа. Например, можно найти content содержащий div в <article><content><div>Playwright</div></content></article>. Однако поиск content содержащего article div потерпит неудачу, потому что внутренний локатор должен быть относительным и не должен использовать элементы за пределами content.
  
  Обратите внимание, что внешний и внутренний локаторы должны принадлежать одной и той же рамке. Внутренний локатор не должен содержать FrameLocator.
- hasNot Локатор (необязательно)
  
  Соответствует элементам, которые не содержат элемент, соответствующий внутреннему локатору. Внутренний локатор запрашивается относительно внешнего. Например, article не содержащий div совпадает с <article><span>Playwright</span></article>.
  
  Обратите внимание, что внешний и внутренний локаторы должны принадлежать одной и той же рамке. Внутренний локатор не должен содержать FrameLocator.
- hasNotText строка | RegExp (необязательно)
  
  Соответствует элементам, не содержащим указанный текст где-либо внутри, возможно, в дочернем или потомке элемента. При передаче строки соответствие регистронезависимое и ищет подстроку.
- hasText строка | RegExp (необязательно)
  
  Соответствует элементам, содержащим указанный текст где-либо внутри, возможно, в дочернем или потомке элемента. При передаче строки соответствие регистронезависимое и ищет подстроку. Например, "Playwright" соответствует <article><div>Playwright</div></article>.

Возвращает

Локатор

nth

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

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

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

Аргументы

index число

Возвращает

Локатор

or

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

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

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

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

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

Аргументы

locator Локатор

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

Возвращает

Локатор

page

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

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

locator.page();

Возвращает

Страница

press

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

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

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

Аргументы

key строка

Имя нажимаемой клавиши или символ для генерации, например, ArrowLeft или a.
options Объект (необязательно)
- delay число (необязательно)
  
  Время ожидания между keydown и keyup в миллисекундах. По умолчанию 0.
- noWaitAfter логическое значение (необязательно)
  
  Устаревшее
  
  Этот параметр по умолчанию будет true в будущем.
  
  Действия, запускающие навигацию, ожидают завершения этих навигаций и начала загрузки страниц. Вы можете отказаться от ожидания, установив этот флаг. Вам потребуется только этот параметр в исключительных случаях, таких как навигация по недоступным страницам. По умолчанию false.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 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 будет вводить текст, соответствующий клавише, в верхнем регистре.

Если клавиша представляет собой единственный символ, она чувствительна к регистру, поэтому значения 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 строка

Строка символов для последовательного нажатия на сфокусированный элемент.
options Объект (необязательно)
- delay число (необязательно)
  
  Время ожидания между нажатиями клавиш в миллисекундах. По умолчанию 0.
- noWaitAfter булево (необязательно)
  
  Устарело
  
  Этот параметр не оказывает никакого влияния.
  
  Этот параметр не оказывает никакого влияния.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

Promise<пустое значение>

screenshot

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

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

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

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

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

Аргументы

options Объект (необязательно)
- animations "disabled" | "allow" (необязательно)
  
  При установке в значение "disabled", останавливает CSS-анимации, CSS-переходы и Web Animations. Анимации обрабатываются по-разному в зависимости от их длительности:
  - конечные анимации быстро прокручиваются до завершения, поэтому они будут вызывать событие transitionend.
  - бесконечные анимации отменяются до начального состояния, а затем воспроизводятся после скриншота.
  По умолчанию "allow", что оставляет анимации без изменений.
- caret "hide" | "initial" (необязательно)
  
  При установке в значение "hide", скриншот скроет курсор текста. При установке в значение "initial", поведение курсора текста не изменится. По умолчанию "hide".
- mask Массив<Локатор> (необязательно)
  
  Укажите локаторы, которые должны быть замаскированы при создании скриншота. Замаскированные элементы будут наложены розовым прямоугольником #FF00FF (настраиваемым параметром maskColor), который полностью закрывает его ограничивающую рамку.
- maskColor строка (необязательно)
  
  Укажите цвет наложенного прямоугольника для замаскированных элементов в формате формата CSS цвета. Цвет по умолчанию — розовый #FF00FF.
- omitBackground булево (необязательно)
  
  Скрывает стандартный белый фон и позволяет создавать скриншоты с прозрачностью. Не применимо к изображениям jpeg. По умолчанию false.
- path строка (необязательно)
  
  Путь к файлу для сохранения изображения. Тип скриншота будет определён из расширения файла. Если путь — относительный путь, он разрешается относительно текущей рабочей директории. Если путь не указан, изображение не будет сохранено на диск.
- quality число (необязательно)
  
  Качество изображения от 0 до 100. Не применимо к изображениям png.
- scale "css" | "device" (необязательно)
  
  При установке в значение "css", скриншот будет содержать по одному пикселю на каждый пиксель CSS на странице. На устройствах с высоким разрешением это позволит поддерживать небольшие скриншоты. Использование параметра "device" создаст по одному пикселю на каждый пиксель устройства, поэтому скриншоты устройств с высоким разрешением будут в два раза больше или даже больше.
  
  По умолчанию "device".
- style строка (необязательно)
  
  Текст таблицы стилей, который нужно применить при создании скриншота. Здесь вы можете скрыть динамические элементы, сделать их невидимыми или изменить их свойства, чтобы помочь в создании повторяющихся скриншотов. Эта таблица стилей пробивает Shadow DOM и применяется к внутренним фреймам.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().
- type "png" | "jpeg" (необязательно)
  
  Укажите тип скриншота, по умолчанию png.

Возвращает

Promise<Буфер>

Подробности

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

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

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

scrollIntoViewIfNeeded

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

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

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

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

Аргументы

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

Возвращает

Promise<void>

selectOption

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

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

<select multiple>
  <option value="red">Red</div>
  <option value="green">Green</div>
  <option value="blue">Blue</div>
</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 | строка | ElementHandle | Массив<строки> | Объект | Массив<ElementHandle> | Массив<Объектов>
- value строка (необязательно)
  
  Совпадение по option.value. Необязательно.
- label строка (необязательно)
  
  Совпадение по option.label. Необязательно.
- index число (необязательно)
  
  Совпадение по индексу. Необязательно.
Опции для выбора. Если у <select> есть атрибут multiple, выбираются все совпадающие опции, иначе выбирается только первая опция, соответствующая одной из переданных опций. Строковые значения сопоставляются как со значениями, так и с метками. Опция считается соответствующей, если все указанные свойства совпадают.
options Объект (необязательно)
- force логическое значение (необязательно)
  
  Пропустить проверку actionability. По умолчанию false.
- noWaitAfter логическое значение (необязательно)
  
  Устарело
  
  Эта опция не влияет.
  
  Эта опция не влияет.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — без таймаута. Значение по умолчанию можно изменить через опцию actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

Promise<Массив<строки>>

Подробности

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

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

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

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

selectText

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

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

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

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

Аргументы

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

Возвращает

Promise<void>

setChecked

Устанавливает состояние элемента checkbox или radio.

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

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

Аргументы

checked boolean

Установить или сбросить флажок.
options Объект (необязательно)
- force boolean (необязательно)
  
  Пропустить проверки действительности. По умолчанию false.
- noWaitAfter boolean (необязательно)
  
  Устаревшее
  
  Этот параметр не оказывает влияния.
  
  Этот параметр не оказывает влияния.
- position Объект (необязательно)
  - x число
  - y число
  Точка, используемая относительно верхнего левого угла области отступа элемента. Если не указана, используется какая-либо видимая точка элемента.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — нет таймаута. Значение по умолчанию может быть изменено через параметр actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().
- trial boolean (необязательно)
  
  Если установлено, этот метод выполняет только проверки действительности и пропускает действие. По умолчанию false. Полезно ожидать, пока элемент готов к действию, не выполняя его.

Возвращает

Promise<void>

Подробности

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

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

Если все шаги не завершатся за указанное время timeout, этот метод генерирует ошибку 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 строка | Массив<строка> | Объект | Массив<Объект>
- name строка
  
  Имя файла
- mimeType строка
  
  Тип файла
- buffer Буфер
  
  Содержимое файла
options Объект (необязательно)
- noWaitAfter boolean (необязательно)
  
  Устаревшее
  
  Этот параметр не оказывает влияния.
  
  Этот параметр не оказывает влияния.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — нет таймаута. Значение по умолчанию может быть изменено через параметр actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

Promise<void>

Подробности

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

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

tap

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

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

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

Аргументы

options Объект (необязательно)
- force boolean (необязательно)
  
  Необходимо ли пропускать проверки действительности элемента. По умолчанию false.
- modifiers Массив<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (необязательно)
  
  Клавиши модификаторов для нажатия. Гарантирует, что во время операции нажаты только эти модификаторы, а затем восстанавливаются текущие модификаторы. Если не указано, используются текущие нажатые модификаторы. "ControlOrMeta" преобразуется в "Control" в Windows и Linux и в "Meta" в macOS.
- noWaitAfter boolean (необязательно)
  
  Устаревшее
  
  Этот параметр не имеет эффекта.
  
  Этот параметр не имеет эффекта.
- position Объект (необязательно)
  - x число
  - y число
  Точка, используемая относительно верхнего левого угла области отступа элемента. Если не указано, используется какая-либо видимая точка элемента.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — без таймаута. Значение по умолчанию может быть изменено с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().
- trial boolean (необязательно)
  
  При установке этот метод выполняет только проверки действительности элемента и пропускает действие. По умолчанию false. Полезно для ожидания, пока элемент готов к действию, без его выполнения. Обратите внимание, что нажатие клавиатуры modifiers будет выполняться независимо от trial для тестирования элементов, которые видны только при нажатии этих клавиш.

Возвращает

Promise<void>

Подробности

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

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

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

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

примечание

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

textContent

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

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

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

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

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

Аргументы

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

Возвращает

Promise<null | строка>

uncheck

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

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

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

Аргументы

options Объект (необязательно)
- force boolean (необязательно)
  
  Необходимо ли пропускать проверки действительности элемента. По умолчанию false.
- noWaitAfter boolean (необязательно)
  
  Устаревшее
  
  Этот параметр не имеет эффекта.
  
  Этот параметр не имеет эффекта.
- position Объект (необязательно)
  - x число
  - y число
  Точка, используемая относительно верхнего левого угла области отступа элемента. Если не указано, используется какая-либо видимая точка элемента.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — без таймаута. Значение по умолчанию может быть изменено с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().
- trial boolean (необязательно)
  
  При установке этот метод выполняет только проверки действительности элемента и пропускает действие. По умолчанию false. Полезно для ожидания, пока элемент готов к действию, без его выполнения.

Возвращает

Promise<void>

Подробности

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

Проверка, что элемент является элементом типа checkbox или radio input. В противном случае метод вызывает ошибку. Если элемент уже снят с отметки, метод возвращается сразу.
Ожидание проверок действительности элемента, если не установлен параметр force.
Прокрутка элемента в область видимости при необходимости.
Использование page.mouse для клика в центре элемента.
Проверка, что элемент теперь снят с отметки. В противном случае метод вызывает ошибку.

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

waitFor

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

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

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

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

Аргументы

options Объект (необязательно)
- state "прикреплён" | "откреплён" | "видимый" | "скрытый" (необязательно)
  
  По умолчанию 'visible'. Может быть:
  - 'attached' - ожидание наличия элемента в DOM.
  - 'detached' - ожидание отсутствия элемента в DOM.
  - 'visible' - ожидание, что у элемента есть непустая область отрисовки и нет visibility:hidden. Обратите внимание, что элемент без содержимого или с display:none имеет пустую область отрисовки и не считается видимым.
  - 'hidden' - ожидание, что элемент либо откреплён от DOM, либо имеет пустую область отрисовки или visibility:hidden. Это противоположно опции 'visible'.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 - нет таймаута. Значение по умолчанию может быть изменено через actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

Promise<void>

Устаревшее

elementHandle

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

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

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

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

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

Аргументы

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

Возвращает

Promise<ElementHandle>

elementHandles

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

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

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

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

await locator.elementHandles();

Возвращает

Promise<Массив<ElementHandle>>

тип

Устаревший

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

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

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

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

Аргументы

text строка

Текст для ввода в сфокусированный элемент.
options Объект (необязательно)
- delay число (необязательно)
  
  Время ожидания между нажатиями клавиш в миллисекундах. По умолчанию 0.
- noWaitAfter логическое значение (необязательно)
  
  Устаревшее
  
  Эта опция не имеет эффекта.
  
  Эта опция не имеет эффекта.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 - нет таймаута. Значение по умолчанию может быть изменено через actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

Promise<void>

Методы​

all​

allInnerTexts​

allTextContents​

and​

ariaSnapshot​

blur​

boundingBox​

проверка​

очистка​

щелчок​

contentFrame​

count​

dblclick​

dispatchEvent​

dragTo​

evaluate​

evaluateAll​

evaluateHandle​

fill​

filter​

first​

focus​

frameLocator​

getAttribute​

getByAltText​

getByLabel​

getByPlaceholder​

getByRole​

getByTestId​

getByText​

getByTitle​

highlight​

hover​

innerHTML​

innerText​

inputValue​

isChecked​

isDisabled​

isEditable​

isEnabled​

isHidden​

isVisible​

last​

locator​

nth​

or​

page​

press​

pressSequentially​

screenshot​

scrollIntoViewIfNeeded​

selectOption​

selectText​

setChecked​

setInputFiles​

tap​

textContent​

uncheck​

waitFor​

Устаревшее​

elementHandle​

elementHandles​

тип​

Методы

all

allInnerTexts

allTextContents

and

ariaSnapshot

blur

boundingBox

проверка

очистка

щелчок

contentFrame

count

dblclick

dispatchEvent

dragTo

evaluate

evaluateAll

evaluateHandle

fill

filter

first

focus

frameLocator

getAttribute

getByAltText

getByLabel

getByPlaceholder

getByRole

getByTestId

getByText

getByTitle

highlight

hover

innerHTML

innerText

inputValue

isChecked

isDisabled

isEditable

isEnabled

isHidden

isVisible

last

locator

nth

or

page

press

pressSequentially

screenshot

scrollIntoViewIfNeeded

selectOption

selectText

setChecked

setInputFiles

tap

textContent

uncheck

waitFor

Устаревшее

elementHandle

elementHandles

тип