Python Selenium 操作 dropdown 时出现 timeout error

2026-10-24支付阿杰

结论

先打开对应的 dropdown，在它自己的搜索框中输入筛选文本，再把查找范围限制在同一个 dropdown 容器内，用完整文本定位选项，并等待选项达到可点击状态。

原代码出现 timeout，主要有以下原因：

在调用 send_keys() 前就开始等待目标选项，此时筛选还没有发生。
//following:: 会在整个页面中查找，可能匹配其他 dropdown，甚至隐藏节点。
XPath 中的文本与页面实际文本不一致，而且 XPath 文本匹配默认区分大小写。
contains(text(), ...) 容易受换行、缩进和嵌套标签影响。
visibility_of_element_located 只能确认元素可见，不能保证它可以点击。

推荐写法

先找到当前 dropdown 的根容器，后续操作都限制在这个容器内。

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

wait = WebDriverWait(self.driver, 10)

search_field = self.get_search_field()

# 根据实际 HTML 替换为 dropdown 最外层容器的稳定定位条件
dropdown = search_field.find_element(
    By.XPATH,
    "./ancestor::*[contains(@class, 'multi-select')][1]"
)

# 点击真正负责展开 dropdown 的按钮
toggle_button = dropdown.find_element(
    By.XPATH,
    ".//button[@aria-haspopup='listbox']"
)
toggle_button.click()

# 先输入筛选条件
search_field.clear()
search_field.send_keys("Unscheduled Principal Payment")

option_text = "Unscheduled Principal Payment (USD)"

# 只在当前 dropdown 中查找，并规范化空白字符
option = wait.until(
    lambda driver: dropdown.find_element(
        By.XPATH,
        f".//*[@role='option' and normalize-space(.)='{option_text}']"
    )
)

wait.until(EC.element_to_be_clickable(option)).click()

示例中的 multi-select、aria-haspopup 和 role="option" 都要根据页面的真实 HTML 调整。如果组件没有这些属性，应改用实际存在且稳定的 class、data-* 属性或父子结构。

如果选项文本位于 `span` 中

有些组件会把文本放在 span 中，但真正可点击的是外层 li。这时不要只点击 span，可以从文本节点向上查找选项元素：

option_text = "Unscheduled Principal Payment (USD)"

option = wait.until(
    lambda driver: dropdown.find_element(
        By.XPATH,
        f"""
        .//*[normalize-space(.)='{option_text}']
          /ancestor-or-self::*[@role='option' or self::li][1]
        """
    )
)

wait.until(EC.element_to_be_clickable(option)).click()

如果已经确定选项标签是 li，可以直接定位：

option = wait.until(
    lambda driver: dropdown.find_element(
        By.XPATH,
        ".//li[normalize-space(.)='Unscheduled Principal Payment (USD)']"
    )
)

wait.until(EC.element_to_be_clickable(option)).click()

没有稳定容器 class 时

如果无法通过 class 找到 dropdown 根节点，可以从搜索框向上查找最近一个包含选项列表的祖先节点。下面的 selectList 仍需替换为页面中的真实 class：

dropdown = search_field.find_element(
    By.XPATH,
    "./ancestor::*[.//*[contains(@class, 'selectList')]][1]"
)

找到容器后，继续在 dropdown 下使用以 . 开头的相对 XPath：

option = wait.until(
    lambda driver: dropdown.find_element(
        By.XPATH,
        ".//*[normalize-space(.)='Unscheduled Principal Payment (USD)']"
    )
)

开头的 . 表示从当前 dropdown 容器开始查找。如果写成 //，Selenium 会回到整个文档中查找，容器范围限制也就失效了。

原 XPath 的问题

原来的表达式是：

xpath = f"//following::span//{tag}[contains(text(),'{value}')]"

这个表达式有以下问题：

following:: 是 XPath 的 following 轴，会搜索当前节点之后的大量节点，并不等于搜索“当前 dropdown 中的选项”。
前面的 // 又扩大了搜索范围。
span//{tag} 要求目标 {tag} 是某个 span 的后代，这可能与实际 DOM 结构不符。
text() 只检查直接文本节点。如果元素中有子标签，可能无法匹配完整的可见文本。
contains() 可能同时匹配 Scheduled Principal Payment (USD) 和 Unscheduled Principal Payment (USD)。
"Unscheduled principal payment" 与页面中的 "Unscheduled Principal Payment (USD)" 在大小写和内容上都不完全一致。

选项名称明确时，优先使用：

normalize-space(.)='Unscheduled Principal Payment (USD)'

normalize-space(.) 会合并换行、缩进和多余空格。这里的 . 还能读取元素及其所有后代节点组成的文本。

调整操作顺序

原代码先等待选项，再输入搜索内容：

self.wait.until(...)
search_field.send_keys(value)

如果 dropdown 只有在输入后才会渲染或过滤选项，这段等待就会超时。操作顺序应改为：

# 1. 展开 dropdown
toggle_button.click()

# 2. 输入筛选文本
search_field.clear()
search_field.send_keys("Unscheduled Principal Payment")

# 3. 等待并点击目标选项
option = wait.until(...)
option.click()

另外，从命名来看，multi-select-clear 更像用于清除已选内容的按钮，不一定是展开按钮。需要检查它的 aria-label、aria-expanded 或事件行为，确认点击的确实是 dropdown 的展开控件。

注意事项

如果页面中有多个相同的 dropdown，最可靠的做法是先根据表单标签、字段名称、name、id 或 data-* 属性找到目标搜索框，再向上查找它所属的 dropdown 容器。不要依赖它是页面中的第几个同类元素。

如果页面保留了一份隐藏的选项列表，全局 XPath 可能会先找到隐藏节点。把查找范围限制在当前展开的容器内，并使用 element_to_be_clickable，可以避开大多数此类 timeout。

如果前端使用虚拟列表，目标选项可能要滚动到附近后才会进入 DOM。此时需要在当前列表中滚动，或者使用组件自带的搜索框进行筛选。仅仅延长等待时间解决不了这个问题。