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

def wait_for_element(driver, locator, timeout=10):  
    """  
    通用元素等待函數(shù)  
    :param driver: WebDriver實(shí)例  
    :param locator: 定位元組(By策略, 表達(dá)式)  
    :param timeout: 超時(shí)時(shí)間（秒）  
    :return: WebElement對象  
    """  
    try:  
        return WebDriverWait(driver, timeout).until(  
            EC.presence_of_element_located(locator)  
        )  
    except TimeoutException:  
        raise Exception(f"元素未在{timeout}秒內(nèi)出現(xiàn): {locator}")  

# 使用示例  
username = wait_for_element(driver, (By.ID, "username"))  
username.send_keys("testuser")

# 元素存在（DOM中）  
EC.presence_of_element_located((By.ID, "element_id"))  

# 元素可見且可點(diǎn)擊  
EC.element_to_be_clickable((By.CSS_SELECTOR, "button.submit"))  

# 元素包含特定文本  
EC.text_to_be_present_in_element((By.XPATH, "http://div[@class='status']"), "完成")  

# 多個(gè)元素同時(shí)存在  
EC.presence_of_all_elements_located((By.CLASS_NAME, "item"))  

# 元素屬性包含特定值  
EC.element_attribute_to_include((By.ID, "progress"), "data-value", "100")  

# 等待元素消失  
EC.invisibility_of_element_located((By.ID, "loading-spinner"))

# 自定義等待函數(shù)：元素具有特定CSS類  
def element_has_class(driver, locator, class_name):  
    def predicate(driver):  
        element = driver.find_element(*locator)  
        if class_name in element.get_attribute("class").split():  
            return element  
        return False  
    return predicate  

# 使用自定義條件  
element = WebDriverWait(driver, 10).until(  
    element_has_class((By.ID, "status-indicator"), "active")  
)

// 測試XPath表達(dá)式  
$x("http://input[@name='email']")  

// 測試CSS選擇器  
document.querySelectorAll("input.form-control")

# 使用部分匹配代替精確匹配  
# 原選擇器：driver.find_element(By.ID, "submit-button-12345")  
driver.find_element(By.CSS_SELECTOR, "[id^='submit-button-']")  
driver.find_element(By.XPATH, "http://*[contains(@id, 'submit-button')]")

# 使用相對路徑而非絕對路徑  
# 避免：/html/body/div[1]/div[2]/form/div[3]/input  
# 推薦：//form[@id='login-form']//input[@name='username']

# 查找多個(gè)匹配元素時(shí)處理  
elements = driver.find_elements(By.CSS_SELECTOR, "button.submit")  
if elements:  
    # 選擇第一個(gè)或根據(jù)條件篩選  
    target_element = elements[0]  
else:  
    raise Exception("未找到匹配元素")  

# 使用更精確的選擇器避免多匹配  
# 不精確：button  
# 精確：button.primary[data-action='submit']

# 檢查元素是否可交互  
def is_element_interactable(element):  
    return element.is_displayed() and element.is_enabled()  

# 等待元素可交互  
def wait_for_interactable(driver, locator, timeout=10):  
    element = WebDriverWait(driver, timeout).until(  
        EC.element_to_be_clickable(locator)  
    )  
    if not (element.is_displayed() and element.is_enabled()):  
        raise Exception("元素不可交互")  
    return element

# 滾動(dòng)元素到視圖中心  
def scroll_to_element(driver, element):  
    driver.execute_script("arguments[0].scrollIntoView({block: 'center'});", element)  

# 使用ActionChains處理復(fù)雜交互  
from selenium.webdriver.common.action_chains import ActionChains  

element = driver.find_element(By.ID, "menu-item")  
ActionChains(driver).move_to_element(element).click().perform()

# 重試機(jī)制處理過時(shí)元素  
def safe_interact(element_locator, interaction_func, retries=3):  
    for attempt in range(retries):  
        try:  
            element = driver.find_element(*element_locator)  
            interaction_func(element)  
            return  
        except StaleElementReferenceException:  
            if attempt == retries - 1:  
                raise  
            time.sleep(1)  # 短暫等待后重試  

# 使用示例  
def input_text(element):  
    element.clear()  
    element.send_keys("text")  

safe_interact((By.ID, "input-field"), input_text)

# 安全切換iframe  
def switch_to_iframe_safe(iframe_locator, timeout=10):  
    """  
    安全切換到指定iframe  
    """  
    iframe = WebDriverWait(driver, timeout).until(  
        EC.frame_to_be_available_and_switch_to_it(iframe_locator)  
    )  
    return iframe  

# 使用示例  
switch_to_iframe_safe((By.ID, "content-iframe"))  
# 操作iframe內(nèi)元素  
driver.find_element(By.ID, "iframe-button").click()  
# 切換回主文檔  
driver.switch_to.default_content()

# 安全處理多窗口  
def switch_to_window_by_title(title_pattern, timeout=10):  
    """  
    切換到包含特定標(biāo)題模式的窗口  
    """  
    original_window = driver.current_window_handle  
    WebDriverWait(driver, timeout).until(  
        lambda d: len(d.window_handles) > 1  
    )  
    
    for window_handle in driver.window_handles:  
        driver.switch_to.window(window_handle)  
        if title_pattern in driver.title:  
            return window_handle  
    
    driver.switch_to.window(original_window)  
    raise Exception(f"未找到標(biāo)題包含'{title_pattern}'的窗口")

# 等待頁面完全加載  
def wait_for_page_loaded(driver, timeout=30):  
    """  
    等待頁面完全加載完成  
    """  
    WebDriverWait(driver, timeout).until(  
        lambda d: d.execute_script("return document.readyState") == "complete"  
    )  
    
    # 可選：等待jQuery或特定框架加載完成  
    try:  
        WebDriverWait(driver, timeout).until(  
            lambda d: d.execute_script("return jQuery.active == 0")  
        )  
    except:  
        pass  # 頁面可能不使用jQuery

# 增強(qiáng)的錯(cuò)誤處理函數(shù)  
def find_element_enhanced(driver, by, value, context=""):  
    """  
    增強(qiáng)的元素查找函數(shù)，提供詳細(xì)錯(cuò)誤信息  
    """  
    try:  
        return driver.find_element(by, value)  
    except Exception as e:  
        # 記錄詳細(xì)上下文信息  
        page_source = driver.page_source[:1000]  # 前1000字符  
        current_url = driver.current_url  
        screenshot_path = f"error_{int(time.time())}.png"  
        driver.save_screenshot(screenshot_path)  
        
        error_msg = f"""  
元素定位失?。? 
上下文: {context}  
定位器: {by}={value}  
當(dāng)前URL: {current_url}  
頁面源碼片段: {page_source}  
截圖已保存: {screenshot_path}  
原始錯(cuò)誤: {str(e)}  
        """  
        raise Exception(error_msg) from e

# 帶重試的元素操作裝飾器  
def retry_on_failure(max_retries=3, delay=1):  
    def decorator(func):  
        def wrapper(*args, **kwargs):  
            for attempt in range(max_retries):  
                try:  
                    return func(*args, **kwargs)  
                except Exception as e:  
                    if attempt == max_retries - 1:  
                        raise  
                    time.sleep(delay)  
                    print(f"重試 {attempt + 1}/{max_retries}: {func.__name__}")  
        return wrapper  
    return decorator  

# 使用示例  
@retry_on_failure(max_retries=3, delay=2)  
def click_submit_button():  
    button = driver.find_element(By.ID, "submit-btn")  
    button.click()