핵심 API 레퍼런스

Mbbrowser 브라우저의 제어권을 가져온 후 가장 중요한 작업은 사용자의 의도대로 페이지를 조작하도록 Selenium에 명령을 내리는 것입니다. 이 장에서는 실무에서 80% 이상 사용되는 핵심 API들을 쉬운 용어로 설명합니다.

---

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. 페이지 요소 찾기 (Locating Elements)

IMPORTANT

요소를 찾는 것은 모든 조작의 전제 조건입니다. 요소를 찾지 못하면 클릭도, 입력도 할 수 없습니다.

위치 지정 방식 (Locator) 빠른 가이드

Selenium 4는 By 클래스를 사용하여 위치 지정을 표준화합니다.

from selenium.webdriver.common.by import By

위치 지정 방법	코드 예시	최적의 사용 사례
ID	By.ID, "username"	가장 빠르고 안정적입니다. 우선순위 1순위.
CSS 선택자	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, "로그인"	링크를 클릭할 때 편리합니다.
Name 속성	By.NAME, "password"	양식(Form) 요소에서 흔히 사용됩니다.

단일 요소 찾기

# 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)

브라우저에서 선택자(Selector)를 찾는 방법 (꿀팁)

1. Mbbrowser에서 대상 페이지를 엽니다.
2. 조작하려는 버튼이나 입력창에서 **마우스 오른쪽 버튼 클릭 → 검사(Inspect)**를 선택합니다.
3. 개발자 도구의 HTML 코드에서 마우스 오른쪽 버튼 클릭 → Copy → Copy selector (CSS 선택자) 또는 Copy XPath를 선택합니다.
4. 이를 Selenium 코드에 붙여넣습니다.

---

3. 대기 메커니즘 (프로그램 중단 방지 도구)

CAUTION

time.sleep(N)은 가장 비효율적인 대기 방식입니다. 네트워크가 빠를 때는 시간을 낭비하고, 느릴 때는 여전히 오류가 발생할 수 있습니다. Selenium의 스마트 대기 기능을 사용하세요.

명시적 대기 (Explicit Wait - 강력 권장)

특정 조건이 충족될 때까지만 기다리고, 조건이 맞으면 즉시 다음으로 넘어갑니다. 지정된 시간(N초)이 지나도 조건이 충족되지 않으면 오류를 발생시킵니다.

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

# id가 "username"인 요소가 보일 때까지 최대 15초간 대기
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("로그인 후 페이지 이동 성공!")

암시적 대기 (Implicit Wait - 전역 설정, 비권장)

driver.implicitly_wait(10)  # 전역 설정: 모든 find_element 호출 시 최대 10초 대기.

---

4. 사람처럼 조작하기 (Interaction)

텍스트 입력

# 입력창을 지우고 계정 입력
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

# 엔터키 입력 (검색창 등에서 흔히 사용)
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

드롭다운 선택

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")

# 인덱스로 선택 (0부터 시작)
select.select_by_index(2)

호버 (마우스 올리기)

from selenium.webdriver.common.action_chains import ActionChains

menu_item = driver.find_element(By.ID, "topMenu")
ActionChains(driver).move_to_element(menu_item).perform()  # 마우스를 요소 위로 이동

드래그 앤 드롭

source = driver.find_element(By.ID, "drag_item")
target = driver.find_element(By.ID, "drop_zone")
ActionChains(driver).drag_and_drop(source, target).perform()

---

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()    # 체크박스/라디오 버튼이 선택되었는가?

# CSS 속성값 가져오기
color = el.value_of_css_property("color")

---

6. 쿠키 조작

Mbbrowser 환경은 쿠키를 영구 저장하지만, 코드로도 제어할 수 있습니다.

# 모든 쿠키 가져오기
all_cookies = driver.get_cookies()
print(all_cookies)

# 쿠키 추가 (해당 도메인의 URL을 먼저 한 번 열어야 합니다)
driver.get("https://example.com")
driver.add_cookie({
    "name": "session_id",
    "value": "abc123",
    "domain": ".example.com"
})

# 특정 쿠키 삭제
driver.delete_cookie("session_id")

# 모든 쿠키 삭제
driver.delete_all_cookies()

---

7. 알림창(팝업) 처리

# 알림창이 나타날 때까지 대기
wait.until(EC.alert_is_present())

# 알림창 개체로 전환
alert = driver.switch_to.alert

# 알림창의 텍스트 읽기
print(alert.text)

# 확인 클릭 (Accept)
alert.accept()

# 취소 클릭 (Dismiss)
alert.dismiss()

# 프롬프트 창에 텍스트 입력
alert.send_keys("내 입력 내용")
alert.accept()

---

8. 멀티 탭 / 멀티 창 조작

# 새 탭 열기
driver.switch_to.new_window("tab")

# 모든 창 핸들 가져오기
handles = driver.window_handles
print(f"전체 탭 개수: {len(handles)}")

# 특정 탭으로 전환
driver.switch_to.window(handles[-1])   # 마지막에 열린(최신) 탭으로 전환

# 첫 번째 탭으로 전환
driver.switch_to.window(handles[0])

---

9. iframe 전환

로그인 창이나 광고 등은 가끔 iframe 태그 내에 들어있습니다. 이 경우 iframe 안으로 제어권을 먼저 옮겨야 요소를 찾을 수 있습니다.

# CSS 선택자로 iframe을 찾아 그 안으로 전환
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")

# 바이너리 데이터로 직접 가져오기 (DB 저장 등에 유용)
png_bytes = driver.get_screenshot_as_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);")

# 입력창의 값을 강제로 수정 (Read-only 필드 우회 등)
driver.execute_script("arguments[0].value = 'new_value';", input_element)

# JS 실행 결과값 가져오기
title = driver.execute_script("return document.title;")

---

TIP

이 정도 API만 마스터해도 거의 모든 시나리오를 처리할 수 있습니다! 다음 장 실전 사례 가이드에서는 자동 로그인, 데이터 수집, 병렬 처리 등 실무에서 즉시 활용 가능한 4가지 템플릿을 제공합니다.