Действия 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' });
Клик с клавишей-модификатором
Пример
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()Он вводит символы один за другим, имитируя реальные нажатия клавиш, и вы можете задать интервал между каждым нажатием клавиши.
Пример
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() Выбор из раскрывающегося списка
Пример
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() Нажать клавишу
Пример
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() Нажать / Отпустить
Пример
await page.keyboard.down('Shift');
// Нажимайте другие клавиши в это время (эквивалентно удержанию Shift при нажатии других клавиш)
await page.keyboard.press('ArrowRight'); // Shift + стрелка вправо (выделить текст)
await page.keyboard.press('ArrowRight');
// Отпустить Shift
await page.keyboard.up('Shift');
Специальные названия клавиш
| Название клавиши | Соответствующая клавиша |
|---|---|
Enter | Enter |
Escape | Esc для выхода |
Tab | Tab для переключения фокуса |
Backspace | Backspace для удаления |
Delete | Клавиша Delete |
ArrowUp/Down/Left/Right | Клавиши со стрелками |
PageUp/PageDown | Клавиши Page |
Home/End | Home / 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');
Действия мышью
Клик и перемещение по координатам
Пример
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();
Колесо мыши
Пример
await page.mouse.wheel(0, 500);
// Прокрутить влево на 200px
await page.mouse.wheel(200, 0);
locator.dragTo() Перетаскивание
Пример
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');