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

Locator

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

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

Методы​

all​

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

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

примечание

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

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

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

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

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

Возвращает

allInnerTexts​

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

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

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

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

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

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

Возвращает

allTextContents​

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

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

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

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

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

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

Возвращает

and​

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

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

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

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

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

Аргументы

  • locator Locator#

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

Возвращает

ariaSnapshot​

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

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

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

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

Аргументы

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

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

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

Возвращает

Детали

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

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

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

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

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

blur​

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

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

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

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

Аргументы

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

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

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

Возвращает

boundingBox​

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

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

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

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

Аргументы

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

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

Added in: v1.14 locator.check

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

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

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

Аргументы

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

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

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

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

      Устарело

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

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

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

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

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

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

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

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

Возвращает

Детали

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

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

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

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

clear​

Added in: v1.28 locator.clear

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

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

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

Аргументы

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

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

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

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

      Устарело

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

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

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

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

Возвращает

Детали

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

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

click​

Added in: v1.14 locator.click

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

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

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

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

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

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

Аргументы

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

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

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

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

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

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

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

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

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

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

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

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

      Устарело

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

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

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

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

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

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

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

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

Возвращает

Детали

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

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

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

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

contentFrame​

Added in: v1.43 locator.contentFrame

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

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

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

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

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

Возвращает

count​

Added in: v1.14 locator.count

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

Asserting count

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

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

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

Возвращает

dblclick​

Added in: v1.14 locator.dblclick

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

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

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

Аргументы

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

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

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

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

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

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

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

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

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

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

      Deprecated

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

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

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

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

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

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

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

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

Возвращает

Детали

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

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

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

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

примечание

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

dispatchEvent​

Added in: v1.14 locator.dispatchEvent

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

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

await locator.dispatchEvent('click');

Аргументы

  • type string#

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

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

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

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

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

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

Возвращает

Детали

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

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

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

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

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

dragTo​

Added in: v1.18 locator.dragTo

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

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

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

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

Аргументы

  • target Locator#

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

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

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

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

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

      Deprecated

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

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

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

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

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

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

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

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

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

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

Возвращает

Детали

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

evaluate​

Added in: v1.14 locator.evaluate

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

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

Аргументы

  • pageFunction function | string#

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

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

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

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

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

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

Возвращает

Детали

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

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

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

evaluateAll​

Added in: v1.14 locator.evaluateAll

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

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

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

Аргументы

  • pageFunction function | string#

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

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

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

Возвращает

Детали

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

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

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

evaluateHandle​

Added in: v1.14 locator.evaluateHandle

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

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

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

Аргументы

  • pageFunction function | string#

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

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

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

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

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

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

Возвращает

Детали

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

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

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

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

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

fill​

Added in: v1.14 locator.fill

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

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

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

Аргументы

  • value string#

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

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

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

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

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

      Устарело

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

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

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

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

Возвращает

Детали

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

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

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

filter​

Added in: v1.22 locator.filter

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

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

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

Аргументы

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

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

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

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

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

    • hasNot Locator (опционально) Added in: v1.33#

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

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

    • hasNotText string | RegExp (опционально) Added in: v1.33#

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

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

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

    • visible boolean (опционально) Added in: v1.51#

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

Возвращает

first​

Added in: v1.14 locator.first

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

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

locator.first();

Возвращает

focus​

Added in: v1.14 locator.focus

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

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

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

Аргументы

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

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

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

Возвращает

frameLocator​

Added in: v1.17 locator.frameLocator

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

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

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

Аргументы

  • selector string#

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

Возвращает

getAttribute​

Added in: v1.14 locator.getAttribute

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

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

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

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

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

Аргументы

  • name string#

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

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

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

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

Возвращает

getByAltText​

Added in: v1.27 locator.getByAltText

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

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

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

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

Аргументы

  • text string | RegExp#

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

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

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

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

Возвращает

getByLabel​

Added in: v1.27 locator.getByLabel

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

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

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

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

Аргументы

  • text string | RegExp#

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

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

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

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

Возвращает

getByPlaceholder​

Added in: v1.27 locator.getByPlaceholder

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

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

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

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

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

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

Аргументы

  • text string | RegExp#

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

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

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

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

Возвращает

getByRole​

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

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

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

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

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

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

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

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

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

Аргументы

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

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

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

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

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

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

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

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

      примечание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Возвращает

Детали

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

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

getByTestId​

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

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

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

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

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

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

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

Аргументы

  • testId string | RegExp#

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

Возвращает

Детали

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

// Установите пользовательский атрибут тестового идентификатора из конфигурации @playwright/test:
import { defineConfig } from '@playwright/test';

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

getByText​

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

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

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

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

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

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

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

// Соответствует <span>
page.getByText('world');

// Соответствует первому <div>
page.getByText('Hello world');

// Соответствует второму <div>
page.getByText('Hello', { exact: true });

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

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

Аргументы

  • text string | RegExp#

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

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

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

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

Возвращает

Детали

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

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

getByTitle​

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

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

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

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

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

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

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

Аргументы

  • text string | RegExp#

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

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

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

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

Возвращает

highlight​

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

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

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

await locator.highlight();

Возвращает

hover​

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

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

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

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

Аргументы

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

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

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

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

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

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

      Устарело

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

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

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

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

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

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

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

Возвращает

Подробности

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

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

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

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

innerHTML​

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

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

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

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

Аргументы

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

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

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

Возвращает

innerText​

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

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

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

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

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

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

Аргументы

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

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

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

Возвращает

inputValue​

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

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

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

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

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

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

Аргументы

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

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

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

Возвращает

Подробности

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

isChecked​

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

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

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

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

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

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

Аргументы

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

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

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

Возвращает

isDisabled​

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

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

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

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

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

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

Аргументы

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

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

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

Возвращает

isEditable​

Added in: v1.14 locator.isEditable

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

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

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

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

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

Аргументы

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

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

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

Возвращает

isEnabled​

Added in: v1.14 locator.isEnabled

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

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

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

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

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

Аргументы

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

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

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

Возвращает

isHidden​

Added in: v1.14 locator.isHidden

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

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

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

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

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

Аргументы

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

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

      Устарело

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

Возвращает

isVisible​

Added in: v1.14 locator.isVisible

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

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

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

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

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

Аргументы

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

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

      Устарело

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

Возвращает

last​

Added in: v1.14 locator.last

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

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

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

Возвращает

locator​

Added in: v1.14 locator.locator

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

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

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

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

Аргументы

  • selectorOrLocator string | Locator#

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

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

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

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

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

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

    • hasNot Locator (опционально) Added in: v1.33#

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

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

    • hasNotText string | RegExp (опционально) Added in: v1.33#

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

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

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

Возвращает

nth​

Added in: v1.14 locator.nth

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

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

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

Аргументы

Возвращает

or​

Added in: v1.33 locator.or

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

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

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

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

примечание

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

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

Аргументы

  • locator Locator#

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

Возвращает

page​

Added in: v1.19 locator.page

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

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

locator.page();

Возвращает

press​

Added in: v1.14 locator.press

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

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

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

Аргументы

  • key string#

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

  • options Object (optional)

    • delay number (optional)#

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

    • noWaitAfter boolean (optional)#

      Deprecated

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

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

    • timeout number (optional)#

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

Возвращает

Детали

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

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

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

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

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

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

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

pressSequentially​

Added in: v1.38 locator.pressSequentially
подсказка

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

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

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

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

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

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

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

Аргументы

  • text string#

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

  • options Object (optional)

    • delay number (optional)#

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

    • noWaitAfter boolean (optional)#

      Deprecated

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

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

    • timeout number (optional)#

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

Возвращает

screenshot​

Added in: v1.14 locator.screenshot

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

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

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

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

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

Аргументы

  • options Object (optional)

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

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

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

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

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

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

    • mask Array<Locator> (optional)#

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

    • maskColor string (optional) Added in: v1.35#

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

    • omitBackground boolean (optional)#

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

    • path string (optional)#

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

    • quality number (optional)#

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

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

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

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

    • style string (optional) Added in: v1.41#

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

    • timeout number (optional)#

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

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

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

Возвращает

Детали

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

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

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

scrollIntoViewIfNeeded​

Added in: v1.14 locator.scrollIntoViewIfNeeded

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

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

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

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

Аргументы

  • options Object (optional)

    • timeout number (optional)#

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

Возвращает

selectOption​

Added in: v1.14 locator.selectOption

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

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

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

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

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

Аргументы

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

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

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

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

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

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

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

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

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

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

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

      Устарело

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

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

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

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

Возвращает

Детали

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

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

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

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

selectText​

Added in: v1.14 locator.selectText

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

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

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

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

Аргументы

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

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

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

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

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

Возвращает

setChecked​

Added in: v1.15 locator.setChecked

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

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

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

Аргументы

  • checked boolean#

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

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

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

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

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

      Устарело

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

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

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

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

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

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

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

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

Возвращает

Детали

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

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

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

setInputFiles​

Added in: v1.14 locator.setInputFiles

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

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

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

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

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

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

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

Аргументы

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

    • name string

      Имя файла

    • mimeType string

      Тип файла

    • buffer Buffer

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

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

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

      Устарело

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

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

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

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

Возвращает

Детали

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

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

tap​

Added in: v1.14 locator.tap

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

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

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

Аргументы

  • options Object (optional)

    • force boolean (optional)#

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

    • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (optional)#

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

    • noWaitAfter boolean (optional)#

      Устарело

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

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

    • position Object (optional)#

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

    • timeout number (optional)#

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

    • trial boolean (optional)#

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

Возвращает

Детали

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

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

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

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

примечание

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

textContent​

Added in: v1.14 locator.textContent

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

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

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

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

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

Аргументы

  • options Object (optional)

    • timeout number (optional)#

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

Возвращает

uncheck​

Added in: v1.14 locator.uncheck

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

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

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

Аргументы

  • options Object (optional)

    • force boolean (optional)#

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

    • noWaitAfter boolean (optional)#

      Устарело

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

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

    • position Object (optional)#

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

    • timeout number (optional)#

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

    • trial boolean (optional)#

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

Возвращает

Детали

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

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

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

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

waitFor​

Added in: v1.16 locator.waitFor

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

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

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

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

Аргументы

  • options Object (optional)

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

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

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

    • timeout number (optional)#

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

Возвращает

Устарело​

elementHandle​

Added in: v1.14 locator.elementHandle
Не рекомендуется

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

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

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

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

Аргументы

  • options Object (optional)

    • timeout number (optional)#

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

Возвращает

elementHandles​

Added in: v1.14 locator.elementHandles
Discouraged

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

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

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

await locator.elementHandles();

Возвращает

type​

Added in: v1.14 locator.type
Deprecated

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

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

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

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

Аргументы

  • text string#

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

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

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

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

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

      Deprecated

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

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

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

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

Возвращает