Core API Reference

After taking control of the Mbbrowser browser, the most important task is directing Selenium to manipulate pages according to your intent. This chapter explains the core APIs you'll use 80% of the time in plain language.

---

1. Navigation and Page Control

Open a URL

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

• Plain Language: Tell the browser to "go to this URL."
• The script will block here until the page finishes loading (the onload event triggers) before proceeding.

Wait for Page Load

Network speeds vary. If subsequent code executes before the page finishes rendering, the script will fail because it can't find elements. The most robust method is to use smart waits (see Section 3).

Retrieve Page Info

title = driver.title                  # Get page title
url   = driver.current_url           # Get current URL
html  = driver.page_source           # Get full page HTML

Back, Forward, Refresh

driver.back()     # Go back (equivalent to the back arrow)
driver.forward()  # Go forward
driver.refresh()  # Refresh the page (F5)

---

2. Finding Page Elements

IMPORTANT

Finding an element is the prerequisite for all operations. No element found = no entry point = cannot perform any actions.

Locator Type Quick Lookup

Selenium 4 standardizes positioning using the By class:

from selenium.webdriver.common.by import By

Positioning Method	Code Example	Best Use Case
ID	By.ID, "username"	Fastest and most stable; priority choice.
CSS Selector	By.CSS_SELECTOR, "#username"	Flexible; highest general-purpose utility.
XPath	By.XPATH, "//input[@name='user']"	Essential for complex structures; complex to write.
Class Name	By.CLASS_NAME, "btn-primary"	Useful for simple cases; use caution with duplicate names.
Tag Name	By.TAG_NAME, "input"	Rarely used alone.
Link Text	By.LINK_TEXT, "Log In"	Convenient for clicking links.
Name Attribute	By.NAME, "password"	Common for form elements.

Find a Single Element

# Find an element with id="username" (raises NoSuchElementException if not found)
element = driver.find_element(By.ID, "username")

# Find the first item matching the CSS selector
btn = driver.find_element(By.CSS_SELECTOR, ".login-form button[type='submit']")

Find Multiple Elements (Returns a List)

# Find all product list items
items = driver.find_elements(By.CSS_SELECTOR, ".product-item")
print(f"Found {len(items)} products total")

# Iterate through each element
for item in items:
    print(item.text)

How to find Selectors in the Browser? (Practical Tip)

1. Open the target webpage in Mbbrowser.
2. Right-click the button or field you want to manipulate → Inspect.
3. In the DevTools HTML code, right-click → Copy → Copy selector (CSS Selector) or Copy XPath.
4. Paste it into your Selenium code.

---

3. Waiting Mechanisms (The Crash-Prevention Tool)

CAUTION

time.sleep(N) is the worst way to wait—it wastes time when the network is fast and still crashes when it's slow. Use Selenium's smart waiting mechanism.

Explicit Wait (Highly Recommended)

Continue only when a certain condition is met, waiting up to N seconds, and raising an error if it times out:

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

# Wait up to 15 seconds until the element with id="username" is visible
wait = WebDriverWait(driver, 15)
username_input = wait.until(
    EC.visibility_of_element_located((By.ID, "username"))
)

Common Wait Conditions EC.xxx:

Wait Condition	Description
EC.presence_of_element_located	Element exists in DOM (not necessarily visible).
EC.visibility_of_element_located	Element exists and is visible (Recommended).
EC.element_to_be_clickable	Element is visible and clickable.
EC.text_to_be_present_in_element	A specific element contains the designated text.
EC.url_contains	Current URL contains the specified string.
EC.alert_is_present	A popup appears.

Practical Example: Wait for Redirection After Login

# Click Login button
driver.find_element(By.ID, "loginBtn").click()

# Wait for URL to contain "/dashboard" (indicating successful redirection)
wait = WebDriverWait(driver, 20)
wait.until(EC.url_contains("/dashboard"))
print("Login redirection successful!")

Implicit Wait (Global Setting, Not Recommended)

driver.implicitly_wait(10)  # Global: all find_element calls wait up to 10 seconds.

---

4. Simulating Human Interaction

Typing Text

# Clear input field and type account
import time

input_box = driver.find_element(By.ID, "username")
input_box.clear()           # Clear any existing content
input_box.send_keys("mbbrowser_user")  # Enter text

# Better Human Simulation (typing character by character with delay)
def human_type(element, text, delay=0.08):
    """Simulates human typing speed with brief pauses between characters."""
    for char in text:
        element.send_keys(char)
        time.sleep(delay)

Clicking Elements

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

Simulating Keyboard Keys

from selenium.webdriver.common.keys import Keys

# Press Enter (often used for submitting search)
search_box = driver.find_element(By.NAME, "q")
search_box.send_keys("Mbbrowser")
search_box.send_keys(Keys.RETURN)

# Select all + Delete
input_box.send_keys(Keys.CONTROL + "a")  # Ctrl+A
input_box.send_keys(Keys.DELETE)          # Del

Dropdown Selection

from selenium.webdriver.support.ui import Select

# Select by visible text
select = Select(driver.find_element(By.ID, "country"))
select.select_by_visible_text("USA")

# Select by value attribute
select.select_by_value("US")

# Select by index (staring from 0)
select.select_by_index(2)

Hover (Triggering Hover Menus)

from selenium.webdriver.common.action_chains import ActionChains

menu_item = driver.find_element(By.ID, "topMenu")
ActionChains(driver).move_to_element(menu_item).perform()  # Move mouse onto element

Drag and Drop

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. Retrieving Element Info

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

# Get visible text
text = el.text

# Get specific attribute value
href  = el.get_attribute("href")
value = el.get_attribute("value")
cls   = el.get_attribute("class")

# Determine status
el.is_displayed()   # Is it visible?
el.is_enabled()     # Is it interactable? (e.g., button not greyed out)
el.is_selected()    # Is checkbox/radio button selected?

# Get CSS properties
color = el.value_of_css_property("color")

---

6. Cookie Operations

Mbbrowser environments save Cookies persistently, but you can also manipulate them via code:

# Get all Cookies
all_cookies = driver.get_cookies()
print(all_cookies)

# Add a Cookie (Must first open a URL of that domain)
driver.get("https://example.com")
driver.add_cookie({
    "name": "session_id",
    "value": "abc123",
    "domain": ".example.com"
})

# Delete a specific Cookie
driver.delete_cookie("session_id")

# Delete all Cookies
driver.delete_all_cookies()

---

7. Popup Handling

# Wait for alert to appear
wait.until(EC.alert_is_present())

# Switch to alert object
alert = driver.switch_to.alert

# Read alert text
print(alert.text)

# Accept (OK)
alert.accept()

# Dismiss (Cancel)
alert.dismiss()

# Enter text in a prompt dialog
alert.send_keys("My Input")
alert.accept()

---

8. Multi-Tab / Multi-Window Operations

# Open new tab
driver.switch_to.new_window("tab")

# Get all window handles
handles = driver.window_handles
print(f"Total tabs: {len(handles)}")

# Switch to specified tab
driver.switch_to.window(handles[-1])   # Switch to the last (newest) one

# Switch to the first tab
driver.switch_to.window(handles[0])

---

9. iframe Switching

Login boxes or ads are sometimes placed within iframe tags. You must switch into the iframe before finding elements inside it:

# Switch into iframe via CSS selector
iframe = driver.find_element(By.CSS_SELECTOR, "iframe#loginFrame")
driver.switch_to.frame(iframe)

# Now interact with elements inside the iframe
driver.find_element(By.ID, "username").send_keys("my_user")

# Switch back to the main page when done
driver.switch_to.default_content()

---

10. Screenshots

# Screenshot the entire page
driver.save_screenshot("screenshot.png")

# Screenshot a single element
element = driver.find_element(By.ID, "product-image")
element.screenshot("product.png")

# Return binary data directly (useful for databases)
png_bytes = driver.get_screenshot_as_png()

---

11. JavaScript Injection (Advanced)

If elements are "unclickable" (blocked or intercepted by JS), you can inject JS to bypass:

# Force click using JS
driver.execute_script("arguments[0].click();", element)

# Scroll to an element
driver.execute_script("arguments[0].scrollIntoView();", element)

# Scroll to the bottom of the page
driver.execute_script("window.scrollTo(0, document.body.scrollHeight);")

# Modify input value (bypassing read-only fields)
driver.execute_script("arguments[0].value = 'new_value';", input_element)

# Get return value from JS
title = driver.execute_script("return document.title;")

---

TIP

Once you master these APIs, you can handle the vast majority of scenarios! The next chapter Real-world Examples provides four complete, usable business templates.