Основы операций со страницами в Playwright

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

Навигация по страницам

Навигация по страницам — наиболее распространённая операция. Playwright предоставляет несколько API для открытия, обновления и управления навигацией по страницам.

1. Открыть веб-страницу (page.goto）

await page.goto('https://example.com');

Общие параметры:

  • url: адрес для перехода
  • timeout: тайм-аут, по умолчанию 30 секунд

  • waitUntil: условия ожидания загрузки страницы

    • 'load': ожидатьloadсобытие (страница и ресурсы полностью загружены)
    • 'domcontentloaded': дождаться завершения загрузки DOM-контента
    • 'networkidle': дождаться простоя сети

Пример

await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });

2. Обновить страницу (page.reload）

Обновить текущую страницу.

await page.reload({ waitUntil: 'networkidle' });

3. Вперёд / Назад (page.goBack / page.goForward）

Имитировать кнопки «Вперёд» и «Назад» браузера.

await page.goto('https://example.com');
await page.goto('https://playwright.dev');

await page.goBack();   // 返回 example.com
await page.goForward(); // 前进到 playwright.dev

4. Ожидание загрузки страницы

Иногда нужно явно дождаться загрузки определённого элемента на странице. Playwright предоставляет умный механизм ожидания.

await page.waitForLoadState('networkidle'); // 等待网络空闲
await page.waitForSelector('#main-content'); // 等待元素出现

Поиск элементов

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

1. CSS-селекторы

Самый распространённый способ поиска, совместимый с фронтенд-разработкой.

await page.click('#login-button');     // 通过 id
await page.click('.btn-primary');      // 通过 class
await page.click('form > button');     // 通过层级关系

2. Селекторы XPath

Поиск элементов с помощью выражений XPath.

await page.click('//button[text()="登录"]');
await page.click('//input[@name="username"]');

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

3. Поиск по текстовому содержимому

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

await page.click('text=登录');
await page.click('button:has-text("提交")');

4. Поиск по атрибуту

Используйте атрибуты напрямую для выбора.

await page.fill('input[name="email"]', '[email protected]');
await page.click('[data-test="submit-button"]');

5. Лучшие практики для стратегий поиска

  • Предпочитайте уникальные и стабильные селекторы(например,data-testid、data-testатрибут)
  • Избегайте использования динамических id или имён классов
  • Используйтеpage.getByRole、page.getByTextи других более читаемых методов (рекомендуется в Playwright 5.x)

Пример


await page.getByRole('button', { name: 'Submit' }).click();
await page.getByPlaceholder('Please enter username').fill('admin');

Основные взаимодействия

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

1. Операции клика (page.click）

await page.click('#submit');

Необязательные параметры:

  • button：'left' | 'right' | 'middle'(левая кнопка по умолчанию)
  • clickCount: количество кликов (установите 2 для двойного клика)
  • modifiers: клавиши-модификаторы клавиатуры (например,['Control']）

Пример

await page.click('#submit', { button: 'right' }); // Правый клик
await page.dblclick('#submit'); // Двойной клик

2. Ввод текста (fill против type）

  • fill(selector, value): очищает поле ввода и вводит новое значение (рекомендуется, используется в большинстве случаев)
  • type(selector, text): имитировать посимвольный ввод (с задержкой, ближе к поведению реального пользователя)

Пример

await page.fill('input[name="username"]', 'test_user');
await page.type('input[name="search"]', 'playwright', { delay: 200 });

3. Операции с клавиатурой

  • press: имитировать нажатия клавиш
  • keyboard.type: непрерывно вводить текст
  • keyboard.press: нажать клавишу (может включать клавиши-модификаторы)

Пример

await page.press('input[name="username"]', 'Enter');
await page.keyboard.type('Hello World!');
await page.keyboard.press('Control+A'); // Выбрать все
await page.keyboard.press('Backspace'); // Удалить

4. Операции с мышью

Playwright обеспечивает полный контроль мышью:

  • hover: наведение мыши
  • mouse.move(x, y): перемещение к координатам
  • mouse.click(x, y): клик по координатам
  • mouse.down / mouse.up: нажать/отпустить кнопку мыши
  • dragAndDrop: перетаскивание элемента (Playwright 1.18+)

Пример

await page.hover('#menu'); // Наведение
await page.mouse.move(100, 200); // Перемещение к координатам
await page.mouse.click(120, 220); // Клик по координатам
await page.dragAndDrop('#item1', '#dropzone'); // Перетаскивание в целевую область

Полный пример: имитация входа и создание скриншота

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

Пример

const { chromium } = require('playwright');

(async () => {
  // 1. Запустить браузер и создать новую страницу
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  // 2. Перейти на страницу входа
  await page.goto('https://github.com/login');
  console.log(`Текущий заголовок страницы: ${await page.title()}`);

  // 3. Поиск элементов и ввод
  // Найти поле ввода имени пользователя и ввести имя пользователя
  await page.locator('#login_field').fill('your_username');
  // Найти поле ввода пароля и ввести пароль
  await page.locator('#password').fill('your_password');

  // 4. Нажать кнопку входа
  // Использование .getByRole() — более надёжный метод поиска
  await page.getByRole('button', { name: 'Sign in' }).click();

  // 5. Дождитесь завершения навигации по странице, чтобы убедиться в успешном входе
  await page.waitForURL('https://github.com/');

  // 6. Сделайте скриншот и сохраните его, чтобы подтвердить статус входа
  await page.screenshot({ path: 'github_homepage.png' });
  console.log('Вход выполнен, скриншот сделан');

  // 7. Закройте браузер
  await browser.close();
})();

Как запустить:

  • Сохраните код в каталоге проекта какgithub_login.js。
  • Выполните в терминалеnode github_login.js。

Сводная таблица общих API

Категория Метод / Свойство Описание
Навигация по страницам page.goto(url[, options]) Открыть страницу
page.reload([options]) Обновить страницу
page.goBack([options]) Назад
page.goForward([options]) Вперёд
page.waitForLoadState([state]) Ожидание состояния загрузки страницы
Поиск элементов page.locator(selector) Универсальный локатор
page.getByRole(role, options) Поиск по роли
page.getByText(text) Поиск по тексту
page.getByPlaceholder(text) Поиск по placeholder
page.getByLabel(text) Поиск по label
Основные взаимодействия page.click(selector[, options]) Клик по элементу
page.dblclick(selector) Двойной клик
page.fill(selector, value) Ввод текста (очистить, затем заполнить)
page.type(selector, text[, options]) Имитация посимвольного ввода
page.press(selector, key) Нажатие клавиши на элементе
page.keyboard.type(text) Ввод с клавиатуры
page.keyboard.press(key) Нажатие клавиши клавиатуры (включая комбинации с модификаторами)
page.hover(selector) Наведение
page.mouse.move(x, y) Перемещение мыши
page.mouse.click(x, y[, options]) Щёлкнуть по координатам
page.dragAndDrop(src, dest) Перетаскивание элемента
Другие расширения