Python Selenium遇模态弹窗报Timeout异常的解决方法

按优先级逐次验证以下问题点：

• 时序匹配问题：TypeScript实现的前端模态框大多带入场动画（时长通常300-800ms），动画执行期间按钮处于不可交互状态，如果提交登录凭证后立刻查找弹窗元素，会因为元素未就绪触发超时。可以先暂停脚本，手动在开发者工具Elements面板搜索OK按钮的文本、特征属性，确认元素是否真实挂载到DOM树，同时查看元素的CSS状态：是否存在disabled属性、pointer-events: none样式、透明度为0的隐藏状态。
• 交互拦截问题：检查模态框遮罩层（类名通常包含modal-mask、backdrop、overlay关键词）的z-index值是否高于OK按钮，部分组件库的版本bug会导致遮罩层意外覆盖可操作按钮，点击事件被遮罩层拦截；另外无障碍优化的TS模态框默认会开启焦点锁，强制把操作焦点限制在弹窗容器内，如果弹窗弹出后代码还尝试操作弹窗外部的元素，会直接被焦点逻辑阻断。
• 焦点丢失问题：确认Selenium控制的浏览器窗口是否被其他后台程序抢占焦点，窗口失焦状态下部分前端交互逻辑会暂停执行，也会抛出操作超时异常。

按从常规到特殊的顺序尝试：

1. 替换固定等待为高频轮询的显式等待，适配模态框动画渲染时长，不要用硬编码的time.sleep()：

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

# 最长等待10秒，每100毫秒轮询一次元素可点击状态
ok_button = WebDriverWait(driver, 10, poll_frequency=0.1).until(
    EC.element_to_be_clickable((By.XPATH, "//div[contains(@class,'modal')]//button[normalize-space(text())='OK']"))
)

2. 常规点击失效时，用JS触发点击绕过前端交互拦截，该方法可以跳过遮罩层拦截、焦点锁校验、元素位置偏移等导致的点击失败问题：

driver.execute_script("arguments[0].click();", ok_button)

3. 如果JS点击仍不生效，先通过JS清理阻塞交互的页面元素、解除焦点锁定：

# 移除所有遮罩层、解除焦点锁
driver.execute_script("""
// 删除遮罩元素
document.querySelectorAll('[class*="mask"],[class*="backdrop"],[class*="overlay"]').forEach(el => el.remove());
// 解除焦点锁定
if(document.activeElement) document.activeElement.blur();
// 移除body上的滚动锁、交互限制类
document.body.classList.remove('modal-open','lock-scroll');
document.body.style.overflow = 'auto';
""")
# 焦点切回当前测试窗口
driver.switch_to.window(driver.current_window_handle)
# 再执行按钮点击
ok_button.click()

注意：driver.switch_to.alert仅能处理浏览器原生的alert/confirm/prompt弹窗，对自定义HTML模态框完全无效，不要在该场景下调用该接口。

内容的提问来源于stack exchange，提问作者Bijaylaxmi Sahoo