上周三下午前端把结算页的立即支付按钮从button idpay-submit换成了组件库封装的自定义元素渲染出来只剩一个div classbtn-primary带随机后缀的 ID 每次刷新都不一样。那天晚上跑回归三十多条用例挂了二十一条全是NoSuchElementException。我盯着报错日志想了很久最后把定位方式从 ID 改成按文本找立即支付改完一次通过。这件事之后我在项目里逐步把大部分交互元素的定位策略换成了文本定位——也就是 Selenium 通过元素的可见文本找到它再执行点击、输入、读取等操作。这篇文章想聊的就是这套做法它包含哪些可用的定位手段、每种的边界在哪里、拿到元素之后怎么安全地操作、非原生下拉框这种文本在 li 里、状态在 JS 里的场景怎么处理以及我踩过的那些坑。不管你是刚开始学 Selenium 的新手还是已经写了几百条用例想优化维护成本的老手下面这些内容应该都能直接用上。1. 为什么我越来越依赖文本定位从一次改版说起1.1 改版当天挂掉的二十一条用例先说清楚那个下午发生了什么。前端做了一次设计规范对齐把所有按钮、标签页、菜单项换成了统一的组件库实现。组件库内部给每个实例生成的 ID 是自增加时间戳的形式class 是语义化的但会被样式复用。结果就是原来靠idpay-submit定位的用例全挂靠classbtn-primary定位的用例匹配到了页面上一堆元素报ElementNotInteractableException或者干脆点错。这个过程里唯一没变的是立即支付这四个字。因为这是业务语言是产品经理写在需求文档里、运营写在文案规范里的东西前端改组件库不会顺手改它。我当时的判断是一个元素的业务含义比它的技术标识稳定得多。文本定位的本质就是拿业务含义当锚点而不是拿 DOM 属性当锚点。1.2 文本才是业务语言的锚点这个思路其实不新鲜做测试的人都知道要面向业务设计用例。但落到代码层面很多人还是习惯性地打开 F12复制id或者css selector粘贴进find_element。这样写出来的用例能跑但它和页面的耦合点选错了地方——你耦合的是实现细节而不是业务意图。举个更直观的对比。假设页面有个导出报表按钮两种写法的维护成本是这样的定位方式表达式前端换组件库时文案调整时可读性ID 定位By.ID, export-btn-3821直接失效无影响差看不出业务含义CSS 类名By.CSS_SELECTOR, .ant-btn.primary可能失效或误匹配无影响一般XPath 文本By.XPATH, //button[normalize-space()导出报表]基本不受影响需同步更新好一眼看出在干什么相对定位with_text(导出报表)基本不受影响需同步更新好表格里文案调整时需同步更新这一列恰恰是很多团队拒绝文本定位的理由文案一变用例就挂。但我的经验是文案变更通常走的是同一个需求流程用例跟着改是应该的——它本来就是业务变更用例不挂反而说明你没测到点子上。相比之下前端的一万次重构不该影响用例。1.3 文本定位的代价它从来不是免费的我得把话说明白文本定位不是银弹它有几个天然的成本第一是性能。XPath 的文本匹配需要遍历节点并计算文本内容比 ID 查找慢一个数量级。我在一个列表页做过粗测By.ID定位平均 8 毫秒//*[text()xxx]全文档扫描平均 120 毫秒左右差 15 倍。单条用例感觉不出来但如果一个用例里有几十次查找、跑上千条用例累积起来就很可观。第二是唯一性。同一个文本确定可能在弹窗、表单、底部按钮里各有一份。文本匹配不像 ID 天生唯一你必须用结构信息把它约束住。第三是文本本身的不确定性。空格、换行、全角半角、动态拼接的数字、加载中的省略号都会让看起来一样的文本匹配不上。这三条我在后面会用专门的章节拆开讲。2. 四套按文本找元素的武器以及各自的能力边界2.1 linkText 与 partialLinkText只认 a 标签的老实人方案Selenium 原生提供的文本定位方法只有两个By.LINK_TEXT和By.PARTIAL_LINK_TEXT。它们的实现极其朴素——只匹配a标签的可见文本且是精确匹配前者和包含匹配后者。很多人第一次学 Selenium 时被这两个方法误导以为 Selenium 内置了通用的文本定位能力结果拿它去点button怎么都找不到。from selenium import webdriver from selenium.webdriver.common.by import By driver webdriver.Chrome() driver.get(https://example.com) # 只对 a 标签生效 driver.find_element(By.LINK_TEXT, 忘记密码).click() # 包含匹配页面上有多个含密码的链接时会匹配第一个或报错 driver.find_element(By.PARTIAL_LINK_TEXT, 密码)我个人的使用习惯是只在明确知道目标是a且全站唯一时用LINK_TEXT。原因有两个一是它的匹配语义是整个链接文本完全相同文本里多一个空格、多一个图标对应的不可见字符就会失败二是它不支持任何结构约束没有在页脚的链接里找这种表达。相比之下 XPath 能表达的东西多得多所以日常我更倾向统一用 XPath减少心智负担。提示PARTIAL_LINK_TEXT在页面上有多个匹配时不会抛异常它会返回第一个。这在调试阶段很危险容易让你误以为定位正确直到某个版本页面顺序调整后才暴露。2.2 XPath 的 text() 与 contains()主力方案真正的通用方案是 XPath。最基础的两个写法是精确匹配和包含匹配# 精确匹配元素的文本恰好等于提交订单 By.XPATH, //*[text()提交订单] # 包含匹配元素文本中包含提交 By.XPATH, //*[contains(text(), 提交)] # 限定标签类型能显著提速并减少误匹配 By.XPATH, //button[text()提交订单] By.XPATH, //span[contains(text(), 提交)]这里有一个新手最容易踩的细节text()在 XPath 1.0 里是该节点的直接文本子节点不包含后代元素的文本。看下面这段 HTMLdiv classprice span classsymbol/span span classnum199.00/span /div//div[text()199.00]匹配不到因为 div 的直接文本子节点只有空白和199.00分别在两个 span 里。正确的写法是//div[normalize-space()199.00]或者用点号代表整个元素的字符串值//div[normalize-space(.)199.00]。这个区别我在带新人的时候讲过无数次但只要没实际踩过看文档很难建立直觉。另一个高频坑是contains(text(), xx)它的原理是判断第一个文本子节点是否包含 xx。如果元素文本被拆成了多个子节点同样会失效。稳妥写法是contains(., xx)或contains(normalize-space(.), xx)。我现在的习惯是统一用.加normalize-space()不再纠结text()的语义边界。2.3 normalize-space()处理换行、制表符与首尾空白normalize-space()是我在文本定位里用得最多的函数没有之一。它的作用是把字符串首尾空白去掉并把中间的连续空白字符空格、制表符、换行压缩成一个空格。为什么需要它因为现代前端几乎不会把按钮文字写成一行整齐的 HTMLbutton classsubmit 确认 提交 /button这段 HTML 在浏览器里渲染出来是确认 提交视觉上是一行但 DOM 里的文本内容是\n 确认\n 提交\n。如果你用//button[text()确认 提交]去匹配必然失败。而//button[normalize-space()确认 提交]就能正确命中。同样的问题在 Vue 的模板里特别常见因为模板缩进会被保留成文本节点。我现在的做法是只要不是能确保文本纯净的简单场景一律在 XPath 里加normalize-space()。多打十来个字符省下的是半小时的排查时间。2.4 Selenium 4 的 withText 相对定位与文本加结构的组合Selenium 4 引入了相对定位器Relative Locators其中with_text()可以用文本作为过滤条件from selenium.webdriver.support.relative_locator import with_tag_name # 找到文本为用户名的标签右侧的输入框 label driver.find_element(By.XPATH, //label[normalize-space()用户名]) input_box driver.find_element( with_tag_name(input).to_right_of(label) )另外 Selenium 4 在 Python 里没有官方getByText但很多团队会自己封装一个byText工厂函数我在第 6 节会给完整实现。相对定位的价值在于它把文本和空间关系结合起来表达力比纯 XPath 更贴近人的思维方式——收货人后面的那个输入框这句话本身就是一个相对定位。如果需要在 JS 生态里做同样的事testing-library系列的getByText思路值得借鉴它默认忽略大小写、自动归一化空白、并能指定exact参数。这个设计后来被很多自动化框架抄了过去包括我们自己封装的工具函数。3. 写对定位表达式从能跑到不脆3.1 精确匹配还是包含匹配这是个判断题包含匹配在页面上几乎没有独一无二的可能因为按钮文字往往互相包含提交、提交订单、提交并支付。你用contains(., 提交)去找很可能拿到文本框旁边的一个提示或者一个隐藏的 aria-label。我的判断规则很简单待匹配文本是短词或通用词确定、取消、提交、保存一律用精确匹配加标签约束//button[normalize-space()确定]。待匹配文本是长句或唯一性强的短语您的订单已提交成功可以用包含匹配因为撞车的概率低。文本里含动态内容共 128 条记录必须用包含匹配并把动态部分切掉只匹配共和条记录之间的稳定片段。第三种情况有个技术细节值得单独说。XPath 1.0 没有正则所以处理共 N 条记录这种必须靠starts-with()和contains()组合或者干脆用contains(., 条记录)加//div的 class 约束。如果需要更复杂的匹配可以退一步用find_elements拿到一批候选再用 Python 的re在内存里过滤。这个思路在第 5 节会展开。3.2 用祖先锚点把匹配范围收窄假设一个电商页面确定按钮出现在三处地址选择弹窗、优惠券弹窗、删除确认弹窗。三个弹窗可能同时存在于 DOM 里只是隐藏了。这时候//button[normalize-space()确定]会匹配到三个Selenium 抛InvalidSelectorException或者返回第一个行为不可控。解法是用容器把它锚住# 只在优惠券弹窗内找确定按钮 By.XPATH, //div[contains(class,coupon-dialog)]//button[normalize-space()确定] # 用弹窗标题作为兄弟节点锚点 By.XPATH, //div[.//h3[normalize-space()选择优惠券]]//button[normalize-space()确定]第二种写法看起来绕但它其实很实用它表达的是包含选择优惠券标题的那个弹窗容器里的确定按钮完全不依赖容器的 class 名。前端换样式系统、改 class 命名这段表达式都不受影响。我现在写定位时只要元素本身没有强唯一性就一定会往上找一两个有语义的祖先做锚点。注意锚点的层级不要贪多。有些同事为了绝对准确写出六层嵌套的 XPath结果页面加一个 div 就全挂。我的经验是锚点不超过两层且必须选语义稳定的节点。3.3 大小写、全角半角与不可见字符这三个是文本定位里最阴的坑因为它们在页面上看起来完全一样。大小写XPath 1.0 的和contains()都是大小写敏感的。中文界面无所谓但 SaaS 产品里Save和SAVE可能共存。Selenium 4.9 之后的 XPath 仍然不支持lower-case()解决办法是在页面结构约束上做文章或者在 Python 侧过滤。全角半角中文输入法状态下打出的是全角而很多前端组件的文案是由设计稿导出的混用严重。全角空格 U3000 尤其恶劣因为它看起来和普通空格一模一样normalize-space()也不会把它压缩掉它只处理 XML 规范里的空白字符。不可见字符零宽空格 U200B、零宽非连接符 U200C、字节顺序标记 UFEFF这些经常被后端模板或富文本编辑器偷偷塞进来。我遇到过一次最离谱的运营在后台配置按钮文案时从 Word 里复制粘贴带进来一个零宽字符导致按文本定位的用例在那一个环境的预览站上全挂正式环境却正常。处理办法是打印出元素的文本并转成 Unicode 码点看el driver.find_element(By.CSS_SELECTOR, .submit-btn) raw el.get_attribute(textContent) print(repr(raw)) # 直接看到 \\u200b、\\u3000 这类字符 print([hex(ord(c)) for c in raw])只要打印一次问题立刻现形。我建议在项目里准备一个调试用的小脚本专门干这件事比反复猜要快得多。3.4 多语言与文案频繁变更下的写法定型如果项目要做多语言按文本定位有个天然的麻烦同一套用例要在中英文两套页面跑。我的做法是不把文本写进用例而是写进资源文件locators { zh: {submit_order: 提交订单, confirm: 确定}, en: {submit_order: Place Order, confirm: Confirm}, } def by_text(key, langzh): return (By.XPATH, f//*[normalize-space(){locators[lang][key]}])用例里只出现by_text(submit_order)具体文案由配置文件决定。这样一来加一种语言只需要加一个字典不用动任何用例代码。这个小改造在一个做跨境电商的项目里帮我省了大量重复工作。4. 定位之后点击、输入、读取的正确姿势4.1 点击失败的三种形态以及各自的原因定位成功不等于操作成功。Selenium 的click()在内部做的是计算元素中心点坐标然后派发一个鼠标事件到该坐标所以只要坐标上有别的元素挡着事件就落到别人头上。这也是为什么文本定位到的元素经常点不动——你找到的是那个span但真正接收点击的是它的父级或兄弟层。我遇到的点击失败基本分三类现象典型原因处理方式ElementNotInteractableException元素不可见、尺寸为零、被pointer-events:none屏蔽等可见性或点击可交互祖先ElementClickInterceptedException有遮罩、悬浮层、加载动画盖在上面等遮罩消失或用 JS 点击兜底点击无反应、无异常事件绑在父级子元素不接收事件向上找带click的祖先元素第三种最难查因为它不报错。我的排查方法是在浏览器控制台里执行document.elementFromPoint(x, y)看看那个坐标上实际是哪个元素对比一下就清楚了。关于 JS 兜底点击driver.execute_script(arguments[0].click(), el)我的态度是能用但要当成最后手段。它绕过浏览器的真实事件链路可能导致被测代码里的event.target不是预期值掩盖真实 bug。我在项目里给它加了使用标注每次用到都要在代码注释里说明为什么不走原生点击。4.2 输入框写入、清空以及把光标定位到指定文本框输入操作的核心问题是清空。element.clear()在某些前端框架尤其是受控组件里会失效因为框架会在input事件里把值重置回去。我踩过一次React 的受控输入框clear()之后打印get_attribute(value)是空的但下一个字符输入进去原来的内容又回来了。稳妥的清空方式是组合操作from selenium.webdriver.common.keys import Keys def set_text(el, text): el.click() # 先聚焦把光标定位到该输入框 el.send_keys(Keys.CONTROL, a) # 全选 el.send_keys(Keys.DELETE) # 删除 el.send_keys(text) # 触发框架的变更通知 driver.execute_script( arguments[0].dispatchEvent(new Event(input, {bubbles: true}));, el, )el.click()这一步就是把鼠标光标定位到某个文本框中的常见做法。它比el.send_keys()直接写入更可靠因为某些组件把聚焦逻辑绑在mousedown上不聚焦的话输入不会触发校验和联动。如果点击会被遮挡可以用driver.execute_script(arguments[0].focus(), el)替代效果类似但更轻量。另外提醒一句send_keys输入中文在部分驱动版本上会有问题特别是无头模式。我遇到过的现象是中文丢失、只输入了拼音或者干脆没输入。稳妥做法是优先用execute_script直接设值加派发事件或者确保使用最新版驱动。这个坑在 CI 上特别难复现因为本地跑往往正常。4.3 读取文本text 与 textContent 的区别拿到元素之后要读文本做断言这里有两个属性很多人混用element.textSelenium 的实现是读innerText会受 CSS 影响。display:none的元素返回空字符串text-transform:uppercase的元素返回大写后的结果。element.get_attribute(textContent)读原始 DOM 内容不受 CSS 影响隐藏元素也能读到保留换行和空格。element.get_attribute(innerText)介于两者之间受 CSS 影响但不做 Selenium 的额外可见性处理。我的选择规则是做用户视角的断言用text做数据校验用textContent。比如断言按钮显示已提交用text更贴近真实校验表格里某单元格的原始值用textContent更可靠因为隐藏列也能读到。5. 非原生下拉框实战div 加 ul 加 li 的完整操作链路5.1 先枚举所有 li把元素当数据看原生select在 Selenium 里有专门的Select类select_by_visible_text()一行搞定。但现代前端几乎没人用原生 select尤其是组件库基本都是div classselectulli.../li/ul/div这套结构或者干脆把下拉渲染到document.body下的一个浮层里。这种场景的操作逻辑和原生完全不同没有选择这个动作只有点击触发、点击目标、点击确认三步。而点击目标之前你得先知道有哪些选项。我的第一步永远是枚举def dump_options(driver): options driver.find_elements( By.XPATH, //ul[contains(class,dropdown-menu)]/li ) for i, li in enumerate(options): print(i, repr(li.text), li.get_attribute(data-value))把 index、显示文本、>from selenium.webdriver.common.by import By from selenium.webdriver.support.ui import WebDriverWait from selenium.webdriver.support import expected_conditions as EC from selenium.common.exceptions import ElementClickInterceptedException wait WebDriverWait(driver, 10) # 1. 打开下拉点击触发器 trigger wait.until(EC.element_to_be_clickable( (By.XPATH, //div[contains(class,select-trigger)] [.//span[normalize-space()请选择城市]]) )) trigger.click() # 2. 等选项容器出现并可见 panel wait.until(EC.visibility_of_element_located( (By.XPATH, //ul[contains(class,dropdown-menu) and not(contains(style,display: none))]) )) # 3. 在面板内定位目标项必要时先滚动到可见 target panel.find_element(By.XPATH, .//li[normalize-space()杭州市]) driver.execute_script(arguments[0].scrollIntoView({block:center});, target) # 4. 点击并对遮挡做一次重试 try: target.click() except ElementClickInterceptedException: driver.execute_script(arguments[0].click(), target) # 5. 校验等面板收起等触发器文本更新 wait.until(EC.invisibility_of_element(panel)) wait.until(EC.text_to_be_present_in_element( (By.XPATH, //div[contains(class,select-trigger)]), 杭州市 ))这段代码里有几个我想强调的点。第一第 2 步用visibility_of_element_located而不是presence_of_element_located因为下拉面板的 DOM 通常是常驻的用 display 控制显隐presence 会立刻返回然后你点了个隐藏的 li。第二第 3 步的滚动很关键长列表下拉里目标项可能在可视区之外不滚动直接点会点到别的项。scrollIntoView({block:center})里的 center 参数是为了避免滚到边缘后被固定头部遮挡。第三第 5 步的校验才是真正的断言前面的点击只是动作。5.3 选中之后怎么确认真的选上了我见过很多用例止步于点击选项没有任何校验。这样写出来的用例只能发现点不动这类问题发现不了点了但值没存进去这类真正的业务 bug。校验要分两层。第一层是 UI 层触发器上的文本变了、选中项有了高亮 classselected panel.find_element(By.XPATH, .//li[contains(class,is-selected)]) assert selected.text.strip() 杭州市第二层是数据层如果表单是提交型的提交后查接口返回或者列表页的展示值。第二层更重要因为它校验的是端到端的数据一致性而不是组件的自我表演。我一般会把这两层拆成两个用例UI 层的跑得快、反馈快数据层的放在主流程里。还有一种情况是多选下拉点完一个选项面板不关闭可以连续点。这时候校验就要遍历所有带选中 class 的项用集合比较而不是字符串比较。这个细节看着小但多选场景下的顺序是不确定的用列表比较会变成随机失败。5.4 虚拟滚动与远程加载下拉的应对当选项超过几百个时前端往往会做虚拟滚动——只渲染可视区域内的十几个 li滚动时动态替换。这时候find_elements拿到的永远只有那十几个你想找的那一项可能压根不在 DOM 里。处理思路有两种。一种是用搜索框大多数虚拟滚动下拉会带一个可输入的搜索框输入关键词让列表过滤到只剩几条再点击。这种方式最稳因为它绕开了滚动逻辑。另一种是自己模拟滚动。思路是反复执行滚到底部 - 等新数据 - 找目标直到找到或者超过重试上限def scroll_until_found(panel, text, max_rounds20): for _ in range(max_rounds): for li in panel.find_elements(By.XPATH, .//li): if li.text.strip() text: return li driver.execute_script( arguments[0].scrollTop arguments[0].scrollHeight, panel ) time.sleep(0.3) # 等一帧渲染 raise TimeoutError(f滚动 {max_rounds} 轮仍未找到选项: {text})这种写法有点笨但它可靠。我更倾向在后端 API 层做这类数据的校验UI 层只验证能搜到并选中这一条路径把大量数据的遍历交给接口测试。6. 把文本定位封装成团队能用的东西6.1 一个 by_text 工厂函数零散地写 XPath 字符串三个月后没人记得为什么要加那个normalize-space()。我现在的做法是统一走一个工厂函数把常见需求都封进去from selenium.webdriver.common.by import By def xpath_literal(s: str) - str: 安全地把任意字符串转成 XPath 字面量兼容单双引号共存。 if not in s: return f{s} if not in s: return f{s} parts s.split() return concat( , \\, .join(f{p} for p in parts) ) def by_text(text, tag*, exactTrue, containerNone): lit xpath_literal(text.strip()) pred fnormalize-space(){lit} if exact else fcontains(normalize-space(), {lit}) prefix f{container}// if container else // return (By.XPATH, f{prefix}{tag}[{pred}])xpath_literal那个函数值得单独解释一下。XPath 1.0 的字面量不能同时包含单引号和双引号所以当待匹配文本是他说你好这种时直接拼字符串会语法错误。这个 concat 的写法是个老技巧能处理任意组合。这个坑我在匹配一段带引号的产品名时踩过一次报的是InvalidSelectorException日志里没有提示具体原因查了很久。6.2 定位元数据与测试逻辑分开存放仅存储定位元数据这个说法我在一些团队的规范文档里见过我理解它的意思是页面对象里只放定位表达式和操作方法的骨架不放测试数据和业务断言。严格这么做有点教条但方向是对的。我的分层是这样的层内容变更频率定位层元素的 XPath、文本常量、容器锚点低页面改版时改操作层点击、输入、下拉选择的组合动作中交互流程变化时改用例层测试数据、业务断言、流程编排高需求变化时改好处很直接文案调整时你只改定位层的常量字典流程调整时你只改操作层和用例层。如果三者混在一坨任何一处变动都要全文搜索替换出错概率指数上升。我把这个结构在一个两百多条用例的项目里推过一次前期的迁移成本大概两天之后每轮回归的维护时间从平均四小时降到了四十分钟左右。6.3 显式等待与重试的统一封装文本定位的失败里很大一部分是时序问题元素还没渲染完就去找了。sleep当然能解决但那是用总时长换取稳定性代价太大。统一用显式等待def find_by_text(driver, text, tag*, timeout10): wait WebDriverWait( driver, timeout, ignored_exceptions(NoSuchElementException, StaleElementReferenceException), ) return wait.until(EC.element_to_be_clickable(by_text(text, tagtag)))把StaleElementReferenceException加进ignored_exceptions是个小技巧。SPA 页面里元素会被反复重建你前一步拿到的元素引用到下一步就失效了。默认情况下这个异常会直接中断等待加入忽略列表之后等待会继续重试直到超时成功率高很多。但要注意忽略它会让真正的元素失效问题被掩盖更久所以超时时间不要设太长我一般设 10 秒。7. 环境搭建与最小可运行骨架7.1 安装 Selenium 与驱动管理从零开始的话安装本身很简单但驱动管理的细节值得说清楚python -m pip install --upgrade pip pip install selenium从 Selenium 4.6 开始Python 绑定内置了 Selenium Manager会自动检测本地浏览器版本并下载匹配的驱动。这是最省事的方式我新环境基本都靠它。但如果公司网络限制外网、或者 CI 环境需要离线部署就得手动指定驱动路径from selenium import webdriver from selenium.webdriver.chrome.service import Service service Service(executable_path/opt/drivers/chromedriver) options webdriver.ChromeOptions() options.add_argument(--no-sandbox) driver webdriver.Chrome(serviceservice, optionsoptions)--no-sandbox是容器化环境里的常用参数不加的话在某些 Linux 镜像里会启动失败。另外无头模式下我习惯再加--window-size1920,1080因为默认窗口尺寸很小很多响应式页面会渲染成移动端布局导致按文本定位时找到的是移动版文案。7.2 一个能直接跑的最小骨架把前面讲的东西串起来这是一个可以立刻复制用的骨架import time from selenium import webdriver from selenium.webdriver.common.by import By from selenium.webdriver.common.keys import Keys from selenium.webdriver.chrome.options import Options from selenium.webdriver.support.ui import WebDriverWait from selenium.webdriver.support import expected_conditions as EC class TextLocatorDriver: def __init__(self, headlessTrue): opts Options() if headless: opts.add_argument(--headlessnew) opts.add_argument(--window-size1920,1080) opts.add_argument(--no-sandbox) self.driver webdriver.Chrome(optionsopts) self.wait WebDriverWait(self.driver, 10) def find_text(self, text, tag*, exactTrue): pred normalize-space() ( if exact else f*) # 实际使用下面的写法更稳妥 expr ( f//{tag}[normalize-space(){text}] if exact else f//{tag}[contains(normalize-space(), {text})] ) return self.wait.until( EC.element_to_be_clickable((By.XPATH, expr)) ) def click_text(self, text, tag*): self.find_text(text, tag).click() def type_into(self, label_text, value): # 找到 label 右侧或下方的输入框 box self.driver.find_element( By.XPATH, f//label[normalize-space(){label_text}] f/following::input[1], ) box.click() box.send_keys(Keys.CONTROL, a) box.send_keys(Keys.DELETE) box.send_keys(value) def quit(self): self.driver.quit()following::input[1]这个轴表达式做的是标签之后第一个 input常见于表单场景挺好用。但它的前提是 DOM 顺序符合视觉顺序如果前端用了 grid 布局把 label 和 input 拆到两个容器里这个表达式就会找错。稳妥做法是先看 DOM确认是同级相邻还是跨容器。7.3 启动阶段最常见的三个报错第一个是驱动版本不匹配报SessionNotCreatedException信息里会写Chrome version must be between X and Y。升级 selenium 库或让 Selenium Manager 自动处理即可。第二个是WebDriverException: unknown error: cannot find Chrome binary说明容器里没装浏览器。这个跟 Selenium 无关需要在镜像里装浏览器。第三个是权限相关的Permission denied一般出现在 Linux 下驱动文件没有可执行权限。chmod x一下就行。这三个几乎涵盖了新手启动阶段的全部失败场景。我建议第一次搭建时先用最简单的脚本跑通打开页面的动作再往上加业务逻辑别一上来就写完整的页面对象。8. 故障排查手册文本定位最常见的六种翻车8.1 逐条对照的排查表下面这个表是我自己整理的速查表遇到文本定位失败时按顺序排查现象可能原因验证方法处理方式找不到元素但肉眼可见文本含不可见字符或全角空格打印repr(el.textContent)改用包含匹配或清理文本找不到元素元素在 iframe 内在控制台确认所属 documentswitch_to.frame()找到但不唯一报错页面存在多个同文本元素find_elements看数量加容器锚点约束元素存在但不可点击被遮罩或动画覆盖elementFromPoint看坐标元素等遮罩消失或滚动点击无反应事件绑在祖先元素控制台查看事件监听点击祖先文本读出来是空的元素隐藏或 CSS 影响对比text与textContent按需切换读取方式8.2 iframe 与 Shadow DOM 这两个套娃场景iframe 是老问题了但包装得很隐蔽。有个页面的登录按钮在 iframe 里你按文本找永远找不到因为driver的作用域在顶层 document。解决方式是driver.switch_to.frame(...)操作完再driver.switch_to.default_content()切回来。我习惯给切换写一个上下文管理器避免忘记切回from contextlib import contextmanager contextmanager def in_frame(driver, frame_locator): frame driver.find_element(*frame_locator) driver.switch_to.frame(frame) try: yield finally: driver.switch_to.default_content()Shadow DOM 更麻烦因为 XPath 天生无法穿透 shadow root。Web Component 满天飞的页面里document.querySelector都查不到 shadow 内部的节点Selenium 的原生定位自然也不行。目前可行的路径是通过execute_script在页面上下文里逐层进入shadowRoot拿引用再转成 WebElementhost driver.find_element(By.CSS_SELECTOR, my-component) inner driver.execute_script( return arguments[0].shadowRoot.querySelector(button);, host ) inner.click()这段代码能跑但可读性和稳定性都不好。我的建议是如果项目里 Shadow DOM 用得很多认真评估一下换成支持穿透 shadow root 的框架或者在应用侧开放测试专用的属性比如>actual wait.until( EC.visibility_of_element_located( (By.XPATH, //div[normalize-space()订单已提交]) ) ).text assert actual.strip() 订单已提交, ( f提示文案不符期望 订单已提交实际 {actual!r} )用wait.until直接等目标文本出现而不是等元素出现再比较文本这样等待和断言合二为一既稳定又简洁。这个写法是我目前项目里的默认模式。我自己在这套东西上最大的体会是文本定位的难点从来不在怎么写 XPath而在怎么让这段表达式在一百次改版之后还活着。所以真正花时间的部分是选锚点、定常量、写封装、看日志。前面第 6 节那套分层结构我建议你哪怕只做一半——先把文本常量抽到一个文件里——收益就已经很明显了。另外提醒一句每次新写一条按文本定位的表达式顺手在浏览器控制台里用$x()验证一遍再贴进代码这个习惯能省掉大量跑一遍看报错的往返时间。