Справочник по основным API

Главная особенность Playwright — «Умный по умолчанию, минимум шума». Большая часть логики ожидания, которую в Selenium приходилось писать вручную, здесь обрабатывается автоматически. В этой главе простым языком объясняются наиболее часто используемые API с примерами на JS и Python.

---

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

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

# Python
page.goto("https://example.com")
page.goto("https://example.com", wait_until="networkidle")

Описание параметра waitUntil:

Значение	Смысл	Рекомендуемый сценарий
'commit'	Завершено сразу после получения заголовков ответа сервера.	Редко используется.
'domcontentloaded'	Построено дерево DOM.	Быстрая навигация; без зависимости от изображений.
'load'	Все ресурсы (изображения, CSS) загружены.	Средняя сложность (по умолчанию).
'networkidle'	Отсутствие сетевой активности минимум 500 мс.	SPA-сайты; полная загрузка.

Другие методы навигации:

await page.goBack();     // Назад
await page.goForward();  // Вперед
await page.reload();     // Обновить

---

2. Locator: Позиционирование элементов (Ключевое преимущество Playwright)

IMPORTANT

Locator в Playwright — это революционное улучшение по сравнению с устаревшим find_element:

• Авто-ожидание: Автоматически ждет появления элемента, его видимости и возможности клика.
• Авто-повтор: Если операция не удалась (например, элемент перекрыт), выполняется автоматический повтор.
• Семантический поиск: Поиск по роли, метке, тексту или плейсхолдеру; меньше зависимости от хрупких CSS-селекторов.

Общие методы позиционирования

// JavaScript —— Рекомендуемый приоритет от высокого к низкому

// 1. По роли (Настоятельно рекомендуется; четкая семантика)
page.getByRole('button', { name: 'Log In' })
page.getByRole('textbox', { name: 'Account' })
page.getByRole('link', { name: 'Register' })

// 2. По текстовому содержимому
page.getByText('Buy Now')
page.getByText('Buy Now', { exact: true })  // Точное соответствие

// 3. По плейсхолдеру (Текст-подсказка в поле ввода)
page.getByPlaceholder('Enter phone number')

// 4. По тексту метки (Отлично подходит для форм)
page.getByLabel('Email Address')

// 5. По CSS-селектору (Традиционный вариант)
page.locator('#username')
page.locator('.btn-primary')
page.locator('button[type="submit"]')

// 6. По XPath
page.locator('//input[@name="password"]')

# Python (Имена методов идентичны, camelCase → snake_case)
page.get_by_role("button", name="Log In")
page.get_by_text("Buy Now")
page.get_by_placeholder("Enter phone number")
page.get_by_label("Email Address")
page.locator("#username")

Поиск нескольких элементов (Возвращает список Locator)

// Получить все совпадающие элементы
const items = page.locator('.product-item');
const count = await items.count();         // Общее количество
const first = items.first();              // Первый
const last  = items.last();               // Последний
const third = items.nth(2);              // Третий (отсчет от 0)

// Фильтрация (Мощный метод filter)
const buttons = page.getByRole('button');
await buttons.filter({ hasText: 'Buy' }).click();  // Кликнуть только по кнопкам с текстом "Buy"

---

3. Механизм авто-ожидания (Забудьте про sleep)

Операции Locator в Playwright (click, fill, type и т.д.) автоматически ждут, пока элемент не будет соответствовать следующим условиям перед выполнением:

• Элемент присутствует в DOM.
• Элемент видим (не скрыт).
• Элемент стабилен (не двигается во время анимации).
• Элемент доступен для клика (не перекрыт).

// Просто кликаем; Playwright сам дождется возможности клика.
await page.getByRole('button', { name: 'Submit' }).click();
// Эквивалент в Selenium:
// wait.until(EC.element_to_be_clickable(...)); element.click();

Ручное ожидание (Только для особых случаев)

// Ждать появления конкретного селектора
await page.waitForSelector('.success-message');

// Ждать изменения URL
await page.waitForURL('**/dashboard');

// Ждать, пока функция не вернет true
await page.waitForFunction(() => document.querySelector('#result')?.textContent === 'Done');

// Ждать сетевого ответа (Часто используется после клика по кнопке, вызывающего API)
const [response] = await Promise.all([
  page.waitForResponse(resp => resp.url().includes('/api/login')),
  page.getByRole('button', { name: 'Log In' }).click()
]);
const data = await response.json();

---

4. Операции с формами

// Ввод текста (Очищает, затем заполняет)
await page.getByLabel('Email').fill('user@example.com');

// Симуляция реального набора текста человеком (Посимвольно)
await page.getByLabel('Password').pressSequentially('MyPassword123', { delay: 80 });

// Очистка поля ввода
await page.getByPlaceholder('Search').clear();

// Чекбоксы
await page.getByRole('checkbox', { name: 'Remember Me' }).check();
await page.getByRole('checkbox', { name: 'Remember Me' }).uncheck();

// Выбор в выпадающем списке
await page.getByRole('combobox', { name: 'Country' }).selectOption('CN');
await page.getByRole('combobox').selectOption({ label: 'China' });   // Выбор по тексту

---

5. Операции с клавиатурой и мышью

// Клавиши клавиатуры (Общие сочетания)
await page.keyboard.press('Enter');
await page.keyboard.press('Control+A');    // Выделить все
await page.keyboard.press('Control+C');    // Копировать
await page.keyboard.press('Escape');

// Операции с мышью
await page.mouse.move(100, 200);           // Переместить мышь
await page.mouse.click(100, 200);         // Клик по координатам
await page.mouse.dblclick(100, 200);      // Двойной клик
await page.mouse.wheel(0, 300);           // Прокрутить вниз на 300px

// Ховер (Вызов всплывающих меню)
await page.getByRole('menuitem', { name: 'More' }).hover();

---

6. Получение информации об элементах

// Получить текстовое содержимое
const text = await page.getByRole('heading').innerText();

// Получить значения атрибутов
const href = await page.locator('a.link').getAttribute('href');
const val  = await page.locator('input#amount').inputValue();  // Значение ввода

// Определение статуса
const isVisible = await page.locator('#modal').isVisible();
const isEnabled = await page.getByRole('button').isEnabled();
const isChecked = await page.getByRole('checkbox').isChecked();

---

7. Перехват сети и мокинг (Уникальное преимущество)

Одна из самых мощных функций Playwright: Перехват и изменение запросов до того, как они покинут браузер.

Перехват и подмена ответов API (Mock)

// Перехватить конкретный запрос к API и вернуть тестовые данные
await page.route('**/api/user/info', async route => {
  await route.fulfill({
    status: 200,
    contentType: 'application/json',
    body: JSON.stringify({ name: 'Mbbrowser Test User', vip: true })
  });
});

Блокировка рекламы и ненужных ресурсов (Ускорение страниц)

await page.route('**/*.{png,jpg,gif,webp,svg}', route => route.abort()); // Блокировать изображения
await page.route('**/{ads,analytics,tracker}**', route => route.abort()); // Блокировать рекламу

---

8. Операции с Cookie

// Получить все Cookies
const cookies = await context.cookies();
console.log(cookies);

// Инъекция Cookies (Лучше всего делать перед открытием веб-страниц)
await context.addCookies([
  { name: 'token', value: 'abc123', domain: '.example.com', path: '/' }
]);

// Очистить все Cookies
await context.clearCookies();

---

9. Работа с несколькими вкладками

// Ожидание открытия новой вкладки
const [newPage] = await Promise.all([
  context.waitForEvent('page'),            // Ждать появления новой вкладки
  page.getByRole('link').click()           // Операция, открывающая новую вкладку
]);
await newPage.waitForLoadState();
console.log('Заголовок новой вкладки:', await newPage.title());

// Получить все открытые вкладки
const allPages = context.pages();
console.log(`Всего вкладок: ${allPages.length}`);

---

10. Скриншоты и PDF

// Скриншот видимой области
await page.screenshot({ path: 'screenshot.png' });

// Скриншот всей страницы (включая прокрутку)
await page.screenshot({ path: 'full-page.png', fullPage: true });

// Скриншот конкретного элемента
await page.locator('#product-card').screenshot({ path: 'product.png' });

---

11. Выполнение JavaScript

// Выполнить JS внутри страницы и получить результат
const title = await page.evaluate(() => document.title);

// Передать параметры в JS на стороне страницы
const itemCount = await page.evaluate(
  selector => document.querySelectorAll(selector).length,
  '.product-item'
);

---

TIP

Освоили API? В следующей главе Библиотека реальных примеров представлены пять готовых шаблонов, которые можно использовать напрямую: вход, парсинг, перехват сети, многопоточность... Копируйте и пользуйтесь!