Действия Playwright

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


Что такое действие

Действие — это метод в Playwright, используемый дляимитации поведения пользователя, например, нажатия кнопок, ввода текста и выбора элементов из раскрывающихся списков.

Перед выполнением каждого действия Playwright автоматически ожидает, пока целевой элемент не перейдёт всостояние готовности к действию。


Проверки возможности выполнения действий

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

ШагПроверка УсловиеОписание
1. ПрисоединёнЭлемент присоединён к дереву DOMЭлемент присутствует на странице
2. ВиденЭлемент виден (неdisplay:noneилиvisibility:hidden)пользователь может видеть элемент
3. СтабиленЭлемент стабилен (анимации завершены)Избегайте ошибочных действий во время анимаций
4. Получает событияЭлемент не перекрыт другими элементамиУбедитесь, что элемент может получить клик
5. ВключёнЭлемент не отключён (неdisabled)пользователь может взаимодействовать с ним

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

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


Принудительные действия { force: true }

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

Пример

// Принудительный клик, пропустить все проверки выполнимости действий
await page.getByRole('button', { name: 'Submit' }).click({ force: true });

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


Навигационные действия

page.goto() Навигация по страницам

Пример

// Базовая навигация
await page.goto('https://www.example.com/');

// Ожидание DOMContentLoaded (структура страницы загружена)
await page.goto('https://www.example.com/', { waitUntil: 'domcontentloaded' });

// Ожидание простоя сети (все асинхронные данные загружены)
await page.goto('https://www.example.com/', {
  waitUntil: 'networkidle',    // Простой сети
  timeout: 60000,              // Таймаут 60 секунд
  referer: 'https://google.com', // Источник Referer
});

page.goBack() / goForward() / reload()

Пример

// Вернуться на одну страницу назад
await page.goBack();

// Перейти на одну страницу вперёд
await page.goForward();

// Обновить страницу
await page.reload();

Действия клика

locator.click() Одиночный клик

Пример

// Базовый одиночный клик
await page.getByRole('button', { name: 'Login' }).click();

// Клик с параметрами
await page.getByRole('button', { name: 'Login' }).click({
  button: 'left',     // Кнопка мыши: 'left' | 'right' | 'middle'
  clickCount: 1,      // Количество кликов
  delay: 100,         // Задержка между нажатием и отпусканием (миллисекунды)
  timeout: 5000,      // Тайм-аут
  modifiers: [],      // Клавиши-модификаторы: ['Alt', 'Control', 'Meta', 'Shift']
});

locator.dblclick() Двойной клик

Пример

// Двойной клик по элементу
await page.getByText('Double-click to edit').dblclick();

Клик правой кнопкой

Пример

// Клик правой кнопкой (открыть контекстное меню)
await page.getByText('Контекстное меню').click({ button: 'right' });

Клик с клавишей-модификатором

Пример

// Ctrl + клик (множественный выбор)
await page.getByRole('option').click({ modifiers: ['Control'] });

// Shift + клик (выбор диапазона / открытие в новом окне)
await page.getByRole('link').click({ modifiers: ['Shift'] });

Клик по координатам

Пример

// Клик в определённой позиции внутри элемента (относительно его верхнего левого угла)
await page.locator('canvas').click({
  position: { x: 100, y: 50 },
});

locator.hover() Наведение

Пример

// Наведение мыши (вызов эффекта наведения или выпадающего меню)
await page.getByRole('link', { name: 'Tutorial' }).hover();

// После наведения нажмите на всплывающее подменю
await page.getByRole('link', { name: 'Playwright Tutorial' }).click();

Сценарии использования клика и наведения

ДействиеПрименимый сценарий
click()Клики по кнопкам, переходы по ссылкам, переключение флажков
dblclick()Вход в режим редактирования, двойной щелчок для выделения текста
click({ button: 'right' })Открытие встроенного контекстного меню браузера
hover()Вызов меню при наведении, всплывающих подсказок
click({ position })Операции с Canvas, пользовательские графические взаимодействия

Действия ввода текста

locator.fill() Очистка и заполнение

fill()Сначала он очищает поле ввода, а затем вводит новое значение. Это наиболее часто используемый и рекомендуемый метод для операций ввода.

Пример

// Очистить поле ввода и ввести новое значение
await page.getByLabel('Username').fill('example_user');
await page.getByLabel('Password').fill('secure_password');
await page.getByPlaceholder('Search EXAMPLE tutorials').fill('Playwright');

locator.type() Посимвольный ввод

type()Он вводит символы один за другим, имитируя реальные нажатия клавиш, и вы можете задать интервал между каждым нажатием клавиши.

Пример

// Вводить посимвольно (задержка 100ms между символами)
await page.getByLabel('Search').type('Playwright', { delay: 100 });

Разница между fill и type

МетодПоведениеПрименимый сценарий
fill()Очистить и ввести за один разБольшинство сценариев (рекомендуется)
type()Посимвольный ввод, вызывающий событие нажатия каждой клавишиКогда нужно вызвать подсказки ввода, поиск в реальном времени

В большинстве случаев используйтеfill()Вот и всё. Только когда поле ввода поддерживает поиск в реальном времени (события keydown/keyup), необходимо использоватьtype()。

locator.clear() Очистка

Пример

// Очистить содержимое поля ввода
await page.getByLabel('Username').clear();

Действия выбора

locator.check() / uncheck() Флажок

Пример

// Установить флажок
await page.getByLabel('I agree to the service agreement').check();

// Снять флажок
await page.getByLabel('Получать уведомления по электронной почте').uncheck();

// Установить отмеченное состояние
await page.getByLabel('Запомнить меня').setChecked(true);   // Проверить, что флажок отмечен
await page.getByLabel('Запомнить меня').setChecked(false);  // Проверить, что флажок снят

locator.selectOption() Выбор из раскрывающегося списка

Пример

// Выбрать по атрибуту value
await page.getByLabel('Город').selectOption('beijing');

// Выбрать по видимому тексту
await page.getByLabel('Город').selectOption({ label: 'Shanghai' });

// Выпадающий список с множественным выбором
await page.getByLabel('Interest tags').selectOption([
  { label: 'Programming' },
  { value: 'design' },
]);

// Выбрать по индексу (элемент 0, элемент 2)
await page.getByLabel('City').selectOption({ index: 0 });

Действия с клавиатуры

page.keyboard.press() Нажать клавишу

Пример

// Нажать и отпустить Enter
await page.keyboard.press('Enter');

// Выделить все (Control + A)
await page.keyboard.press⟧3⟧'Control+A'('Control+A');

// Копировать и вставить
await page.keyboard.press('Control+C');
await page.keyboard.press('Control+V');

// Отменить
await page.keyboard.press('Control+Z');

page.keyboard.down() / up() Нажать / Отпустить

Пример

// Удерживать Shift, не отпуская
await page.keyboard.down('Shift');

// Нажимайте другие клавиши в это время (эквивалентно удержанию Shift при нажатии других клавиш)
await page.keyboard.press('ArrowRight');  // Shift + стрелка вправо (выделить текст)
await page.keyboard.press('ArrowRight');

// Отпустить Shift
await page.keyboard.up('Shift');

Специальные названия клавиш

Название клавишиСоответствующая клавиша
EnterEnter
EscapeEsc для выхода
TabTab для переключения фокуса
BackspaceBackspace для удаления
DeleteКлавиша Delete
ArrowUp/Down/Left/RightКлавиши со стрелками
PageUp/PageDownКлавиши Page
Home/EndHome / End
Control/Alt/Shift/MetaКлавиши-модификаторы

page.keyboard.type() Ввод текста с помощью клавиатуры

Пример

// Ввести текст в сфокусированный элемент
await page.keyboard.type('EXAMPLE Tutorial', { delay: 50 });

page.keyboard.insertText() Вставить напрямую

Пример

// Вставить текст напрямую в позицию в фокусе (не имитирует события клавиатуры, самый быстрый)
await page.keyboard.insertText('Quickly inserted text');

Действия мышью

Клик и перемещение по координатам

Пример

// Клик по координатам области просмотра (100, 200)
await page.mouse.click(100, 200);

// Двойной клик по координатам
await page.mouse.dblclick(100, 200);

// Переместить мышь к координатам
await page.mouse.move(100, 200);

// Нажать / Отпустить
await page.mouse.down();
await page.mouse.up();

Колесо мыши

Пример

// Прокрутить вниз на 500px
await page.mouse.wheel(0, 500);

// Прокрутить влево на 200px
await page.mouse.wheel(200, 0);

locator.dragTo() Перетаскивание

Пример

// Перетащить элемент A к элементу B
const source = page.getByText('Drag me');
const target = page.getByTestId('drop-zone');
await source.dragTo(target);

// Перетаскивание с параметрами
await source.dragTo(target, {
  sourcePosition: { x: 0, y: 0 },   // Начальная точка перетаскивания (относительно исходного элемента)
  targetPosition: { x: 10, y: 10 }, // Целевая точка перетаскивания (относительно целевого элемента)
});

Выбор между page.mouse и locator.click

МетодСценарий применения
locator.click()Клик по элементам страницы (большинство сценариев)
page.mouse.click()Клик по конкретным координатам (сценарии без DOM, такие как Canvas, диаграммы)

Загрузка файла

locator.setInputFiles() Один/несколько файлов

Пример

// Загрузить один файл
await page
  .getByLabel('Choose file')
  .setInputFiles('path/to/document.pdf');

// Загрузить несколько файлов
await page
  .getByLabel('Choose file')
  .setInputFiles([
    'path/to/file1.png',
    'path/to/file2.png',
  ]);

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

Пути к файлам указываются относительно текущего рабочего каталога (корневого каталога проекта).


Скачивание файла

Пример

// Начать ожидание события загрузки (должно быть вызвано до операции, запускающей загрузку)
const downloadPromise = page.waitForEvent('download');

// Выполнить операцию, запускающую загрузку
await page.getByRole('button', { name: 'Download report' }).click();

// Дождаться завершения загрузки
const download = await downloadPromise;

// Получить предлагаемое имя файла
console.log(download.suggestedFilename());

// Сохранить по указанному пути
await download.saveAs('downloads/report.pdf');
Другие расширения