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

После того как вы получили управление над браузером Mbbrowser, самая важная задача — направлять Selenium для манипуляции страницами в соответствии с вашими намерениями. В этой главе простым языком объясняются основные API, которые вы будете использовать в 80% случаев.

---

1. Навигация и управление страницей

Открыть URL

driver.get("https://www.amazon.com")

• Простым языком: Скажите браузеру «перейди по этому адресу».
• Скрипт будет заблокирован здесь до тех пор, пока страница не завершит загрузку (сработает событие onload), прежде чем продолжить.

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

Скорость сети варьируется. Если последующий код выполнится до того, как страница завершит отрисовку, скрипт завершится ошибкой, так как не сможет найти элементы. Самый надежный метод — использовать «умные ожидания» (см. раздел 3).

Получение информации о странице

title = driver.title                  # Получить заголовок страницы
url   = driver.current_url           # Получить текущий URL
html  = driver.page_source           # Получить полный HTML-код страницы

Назад, Вперед, Обновить

driver.back()     # Назад (эквивалент стрелки назад)
driver.forward()  # Вперед
driver.refresh()  # Обновить страницу (F5)

---

2. Поиск элементов страницы

IMPORTANT

Поиск элемента является предварительным условием для всех операций. Нет найденного элемента = нет точки входа = невозможно выполнить никакие действия.

Шпаргалка по типам локаторов

В Selenium 4 позиционирование стандартизировано с помощью класса By:

from selenium.webdriver.common.by import By

Метод позиционирования	Пример кода	Когда использовать
ID	By.ID, "username"	Самый быстрый и стабильный; приоритетный выбор.
CSS Selector	By.CSS_SELECTOR, "#username"	Гибкий; самый универсальный инструмент.
XPath	By.XPATH, "//input[@name='user']"	Необходим для сложных структур; сложен в написании.
Class Name	By.CLASS_NAME, "btn-primary"	Полезен для простых случаев; осторожно с дубликатами имен.
Tag Name	By.TAG_NAME, "input"	Редко используется сам по себе.
Link Text	By.LINK_TEXT, "Log In"	Удобен для кликов по ссылкам.
Name Attribute	By.NAME, "password"	Часто встречается у элементов форм.

Поиск одного элемента

# Найти элемент с id="username" (вызывает NoSuchElementException, если не найден)
element = driver.find_element(By.ID, "username")

# Найти первый элемент, соответствующий CSS-селектору
btn = driver.find_element(By.CSS_SELECTOR, ".login-form button[type='submit']")

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

# Найти все элементы списка товаров
items = driver.find_elements(By.CSS_SELECTOR, ".product-item")
print(f"Всего найдено {len(items)} товаров")

# Итерация по каждому элементу
for item in items:
    print(item.text)

Как найти селекторы в браузере? (Практический совет)

1. Откройте целевую веб-страницу в Mbbrowser.
2. Нажмите правой кнопкой на кнопку или поле, которым хотите манипулировать → Просмотреть код (Inspect).
3. В HTML-коде DevTools нажмите правой кнопкой → Copy → Copy selector (CSS-селектор) или Copy XPath.
4. Вставьте его в свой код Selenium.

---

3. Механизмы ожидания (Инструмент против сбоев)

CAUTION

time.sleep(N) — худший способ ожидания. Он тратит время впустую при быстрой сети и все равно приводит к сбоям при медленной. Используйте механизм «умного ожидания» Selenium.

Явное ожидание (Настоятельно рекомендуется)

Продолжать только при выполнении определенного условия, ожидая до N секунд и выдавая ошибку при превышении времени:

from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.common.by import By

# Ждать до 15 секунд, пока элемент с id="username" не станет видимым
wait = WebDriverWait(driver, 15)
username_input = wait.until(
    EC.visibility_of_element_located((By.ID, "username"))
)

Общие условия ожидания EC.xxx:

Условие ожидания	Описание
EC.presence_of_element_located	Элемент присутствует в DOM (не обязательно видим).
EC.visibility_of_element_located	Элемент присутствует и видим (Рекомендуется).
EC.element_to_be_clickable	Элемент видим и доступен для клика.
EC.text_to_be_present_in_element	Конкретный элемент содержит указанный текст.
EC.url_contains	Текущий URL содержит указанную строку.
EC.alert_is_present	Появилось всплывающее окно.

Пример: Ждать перенаправления после входа

# Нажать кнопку входа
driver.find_element(By.ID, "loginBtn").click()

# Ждать, пока URL не будет содержать "/dashboard" (признак успешного входа)
wait = WebDriverWait(driver, 20)
wait.until(EC.url_contains("/dashboard"))
print("Перенаправление после входа успешно!")

---

4. Симуляция человеческого взаимодействия

Ввод текста

# Очистить поле ввода и ввести данные
import time

input_box = driver.find_element(By.ID, "username")
input_box.clear()           # Очистить текущее содержимое
input_box.send_keys("mbbrowser_user")  # Ввести текст

# Симуляция человеческого набора (посимвольный ввод с задержкой)
def human_type(element, text, delay=0.08):
    """Имитирует скорость набора текста человеком с паузами между символами."""
    for char in text:
        element.send_keys(char)
        time.sleep(delay)

Клики по элементам

btn = driver.find_element(By.CSS_SELECTOR, "button[type='submit']")
btn.click()

Симуляция клавиш клавиатуры

from selenium.webdriver.common.keys import Keys

# Нажать Enter (часто используется для отправки поиска)
search_box = driver.find_element(By.NAME, "q")
search_box.send_keys("Mbbrowser")
search_box.send_keys(Keys.RETURN)

# Выделить все + Удалить
input_box.send_keys(Keys.CONTROL + "a")  # Ctrl+A
input_box.send_keys(Keys.DELETE)          # Del

Выбор в выпадающем списке (Dropdown)

from selenium.webdriver.support.ui import Select

# Выбор по видимому тексту
select = Select(driver.find_element(By.ID, "country"))
select.select_by_visible_text("USA")

# Выбор по атрибуту value
select.select_by_value("US")

---

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

el = driver.find_element(By.ID, "user-info")

# Получить видимый текст
text = el.text

# Получить значение конкретного атрибута
href  = el.get_attribute("href")
value = el.get_attribute("value")
cls   = el.get_attribute("class")

# Определение статуса
el.is_displayed()   # Видим ли он?
el.is_enabled()     # Доступен ли для взаимодействия?
el.is_selected()    # Выбран ли чекбокс/радиокнопка?

---

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

Среды Mbbrowser сохраняют Cookies постоянно, но вы также можете манипулировать ими через код:

# Получить все Cookies
all_cookies = driver.get_cookies()
print(all_cookies)

# Добавить Cookie (Нужно сначала открыть URL этого домена)
driver.get("https://example.com")
driver.add_cookie({
    "name": "session_id",
    "value": "abc123",
    "domain": ".example.com"
})

# Удалить все Cookies
driver.delete_all_cookies()

---

7. Обработка всплывающих окон (Alerts)

# Ждать появления алерта
wait.until(EC.alert_is_present())

# Переключиться на объект алерта
alert = driver.switch_to.alert

# Прочитать текст алерта
print(alert.text)

# Принять (ОК)
alert.accept()

# Отклонить (Отмена)
alert.dismiss()

---

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

# Открыть новую вкладку
driver.switch_to.new_window("tab")

# Получить дескрипторы всех окон
handles = driver.window_handles
print(f"Всего вкладок: {len(handles)}")

# Переключиться на указанную вкладку
driver.switch_to.window(handles[-1])   # Перейти к последней (новой)

---

9. Переключение iframe

Окна входа или реклама иногда размещаются внутри тегов iframe. Вы должны переключиться в iframe перед поиском элементов внутри него:

# Переключиться в iframe по CSS-селектору
iframe = driver.find_element(By.CSS_SELECTOR, "iframe#loginFrame")
driver.switch_to.frame(iframe)

# Теперь взаимодействуем с элементами внутри iframe
driver.find_element(By.ID, "username").send_keys("my_user")

# Вернуться к основной странице по завершении
driver.switch_to.default_content()

---

10. Скриншоты

# Скриншот всей страницы
driver.save_screenshot("screenshot.png")

# Скриншот одного элемента
element = driver.find_element(By.ID, "product-image")
element.screenshot("product.png")

---

11. Инъекция JavaScript (Расширенный уровень)

Если элементы «не кликаются» (заблокированы или перехвачены JS), вы можете внедрить JS для обхода:

# Принудительный клик через JS
driver.execute_script("arguments[0].click();", element)

# Прокрутка к элементу
driver.execute_script("arguments[0].scrollIntoView();", element)

# Прокрутка в самый низ страницы
driver.execute_script("window.scrollTo(0, document.body.scrollHeight);")

# Получить результат выполнения JS
title = driver.execute_script("return document.title;")

---

TIP

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