接手过一个项目仓库里躺着两百多个 Selenium 脚本全塞在一个文件里从登录一路 if-else 写到下单。跑一遍四十分钟失败三十多条点进去看一半元素找不到另一半找到了但点不动。那天下午我干的第一件事不是修脚本而是把整个目录拖进回收站——那套东西已经不是自动化是负担。所以我想聊“工具集”。Selenium 本身是一套成熟的浏览器自动化协议API、生态、语言绑定都很稳但它从来不是开箱即用的测试框架。它更像一箱散装零件螺丝、垫片、扳手都有可你要做的是把零件拼成一台能长期运转的机器。同样一套 Selenium有人写出来的东西跑半年不用管有人写出来的三天就烂掉差别不在 API 熟练度而在有没有把它当“工具集”来设计。下面这份内容适合三类人刚学完 Selenium 基本操作、脚本一多就管不住的新手手里有一堆历史脚本想重构的中年项目以及准备把 UI 自动化接进流水线的工程师。我会从环境搭建一路讲到页面元素枚举、定位元数据存储、分层封装、稳定性排查和并行执行重点是讲清楚每个选择背后的理由以及我踩过的那些坑。1. 想清楚再动手Selenium 工具集到底在解决什么问题1.1 Selenium 不是框架它只是一组协议加一堆零件多数人第一次接触 Selenium是照着教程写driver.find_element(By.ID, kw).send_keys(xxx)跑通了就以为学会了。实际上你用的是WebDriver它只是 Selenium 家族里负责“驱动浏览器”的那一块。完整的家族至少包含这几个成员组件定位什么场景用WebDriver核心按 W3C 标准协议操作浏览器写自动化脚本、测试、爬取动态页面Selenium Grid分布式调度多机器、多浏览器并行执行Selenium IDE浏览器录制回放插件快速验证定位、生成雏形脚本Selenium Manager驱动自动管理免去手动下载 driver 的麻烦语言绑定Python / Java / C# / JS 等用你团队熟悉的语言写逻辑关键认知是WebDriver 只保证“能操作浏览器”不保证“好维护”。定位怎么写、等待怎么加、公共操作放哪、失败怎么记录这些全是使用者自己定的规矩。工具集的价值就藏在这些规矩里。1.2 判断一套工具集好坏看三个指标而不是跑通率新手评估自己的自动化习惯看“今天跑通了几个”。这个指标意义不大因为跑通可能只是运气好页面没改。我判断一套 Selenium 工具集是否合格主要看三条定位稳定性页面结构小改一次需要动几行代码如果换个样式类名就要改二十个文件那是灾难。代码复用率登录流程是每个用例都重写一遍还是调一个公共方法三段式的重复代码是维护成本的主要来源。失败可读性一条用例挂了看报告能不能直接判断是“定位错了”还是“业务错了”还是“环境错了”如果只能看到一句TimeoutException那排查时间会翻好几倍。这三条本质上对应工具集的三个模块元素管理层、页面操作层、观测层。后面的章节基本就是围绕这三块展开。1.3 什么规模的项目才值得搭工具集说实话如果你只有十几个用例、页面基本不变、跑一跑图个心安那直接写线性脚本完全没问题硬上分层反而是过度设计。我的经验阈值大致是这样的用例数少于 30、页面一个月内不变线性脚本足够怎么快怎么来。用例数 30 到 100、页面有迭代至少要做元素统一管理和公共方法抽取。用例数过百、要接 CI、多人协作必须完整分层否则维护成本会指数级上升。这不是玄学。脚本数量一多重复代码的维护成本是超线性增长的——改一个登录按钮的定位可能要翻十个文件。工具集的意义就是把这种“N 处修改”压缩成“1 处修改”。2. 环境搭建selenium 安装里最容易被教程带偏的几步2.1 语言选型别纠结技术优劣先看团队会什么网上关于“Python 还是 Java 写 Selenium”的争论从没停过。我的看法很直接看团队现有技术栈。Python 的优势是语法短、写起来快、和数据处理生态衔接自然Java 的优势是工程化成熟、IDE 支持强、和大厂后端测试体系融合好。两者在 Selenium 层面的能力几乎没有差距四天能学会的东西不值得纠结四年。如果实在没倾向我推荐 Python理由是入门曲线平缓且pytest生态对测试组织非常友好。安装本体只有一行pip install selenium但这里有个坑别装完就立刻去pip install webdriver-manager。老教程里几乎都会教你手动装驱动管理器那是 Selenium 4.6 之前的历史包袱现在没必要了下一节细说。2.2 驱动管理从手动下载到 Selenium Manager 的演进驱动chromedriver、geckodriver 之类是 Selenium 最容易劝退新人的部分。浏览器一升级驱动版本对不上就会报SessionNotCreatedException。这个问题的处理方式经历过三代阶段做法痛点第一代手动下载对应版本驱动放进 PATH浏览器一更新就得重下团队各人版本还不一样第二代用 webdriver-manager 自动下载多一个依赖网络不通时会卡住第三代Selenium 4.6 内置 Selenium Manager自动匹配下载基本零配置现在的正确姿势是这样的from selenium import webdriver driver webdriver.Chrome() # 什么都不用传驱动自动就位 driver.get(https://example.com) driver.quit()Selenium Manager 会自动检测本机浏览器版本、去拉匹配的驱动、缓存在本地。实测下来在 4.15 之后的版本相当稳。只有在离线环境或者公司内网限制外网访问时才需要回退到手动指定驱动路径from selenium.webdriver.chrome.service import Service service Service(executable_path/opt/drivers/chromedriver) driver webdriver.Chrome(serviceservice)提示如果公司内网拉不到驱动把驱动文件统一放在一个共享目录用环境变量指定路径比每个人本地各放一份要可靠得多。2.3 浏览器版本对齐与无头模式的取舍无头模式headless是跑 CI 的标配但新手常犯的错误是本地调试也开无头出了问题看不到页面排查全靠猜。我的习惯是本地开发一律带头跑出问题的用例可以肉眼盯着复现只有进了流水线才切无头。切换方式很简单from selenium import webdriver from selenium.webdriver.chrome.options import Options options Options() options.add_argument(--headlessnew) # 新版无头兼容性更好 options.add_argument(--window-size1920,1080) # 无头模式默认视口很小必须显式设 options.add_argument(--disable-gpu) options.add_argument(--no-sandbox) # 容器里跑通常需要 options.add_argument(--disable-dev-shm-usage) driver webdriver.Chrome(optionsoptions)这里有两个真实踩过的坑。第一无头模式默认视口是 800x600很多响应式页面在这个宽度下会渲染成移动端布局元素位置全变定位自然失败所以一定要显式设 window-size。第二--no-sandbox和--disable-dev-shm-usage在容器里几乎是必须的尤其是 Docker 的/dev/shm默认只有 64MB页面复杂时浏览器会莫名其妙崩溃。2.4 IDE 插件和辅助工具怎么选“怎么安装 selenium 插件”这个搜索词经常出现但要先分清你想装的是哪一类录制回放类Selenium IDE浏览器扩展市场直接搜就能装。它的价值不是生成脚本而是快速验证一条 XPath 到底能不能命中元素。我调试定位经常靠它。编辑器支持类VS Code 的 Python / Java 扩展提供补全和跳转属于基础设施。调试增强类Chrome DevTools 本身就是最好的定位工具CtrlF在 Elements 面板里可以直接试 XPath 和选择器比装任何插件都管用。如果你用 PyCharm建议把 Selenium 的源码关联上find_element报错时能直接跳进源码看它到底抛了什么异常对理解问题帮助极大。3. 页面元素枚举把定位元数据和元素实例彻底分开3.1 把 WebElement 存成类属性是新手最大的陷阱先看一段很常见的写法class LoginPage: def __init__(self, driver): self.driver driver self.username driver.find_element(By.ID, username) self.password driver.find_element(By.ID, password)这段代码在页面静态时能跑一旦页面刷新、跳转、局部渲染self.username就变成了“过期引用”再调用它就会抛StaleElementReferenceException。原因得从机制上讲。Selenium 里的WebElement不是一个真实的 DOM 节点它只是一张“凭据”——里面存着一个内部元素 ID每次操作时拿着这个 ID 去浏览器那边找对应节点。页面一旦重新渲染原来的节点被销毁重建旧 ID 就指向了空。很多人以为“元素还在页面上啊为什么说过期了”问题就在这儿元素还在但它的身份变了。所以正确的做法是类里只存定位元数据怎么找不存元素实例找到的东西。每次要用的时候现场去找用完即弃。这个原则听起来反直觉但它是解决绝大多数 stale 问题的根。3.2 定位元数据应该长什么样既然只存“怎么找”那数据结构就很清楚了一个“定位方式 定位值”的组合。用 dataclass 定义是最稳妥的from dataclasses import dataclass from selenium.webdriver.common.by import By dataclass(frozenTrue) class Locator: by: str value: strfrozenTrue让它不可变避免运行期被误改。然后按页面组织元素枚举from enum import Enum class LoginPageElements(Enum): USERNAME Locator(By.ID, username) PASSWORD Locator(By.CSS_SELECTOR, input[typepassword]) SUBMIT Locator(By.XPATH, //button[normalize-space()登录]) ERROR_MSG Locator(By.CSS_SELECTOR, .el-form-item__error)这就是“页面元素枚举 仅存储定位元数据”的落地形态。它带来三个直接好处页面改版只改一处按钮换 ID只改LoginPageElements.SUBMIT这一行所有引用它的地方自动生效。元素清单可读可 review新人接手时看一眼枚举类就知道这个页面有哪些元素、怎么定位的不用满仓库搜索。避免了实例长期持有枚举值是元数据天然不存在 stale 问题。3.3 枚举式管理在多人协作下的真实收益有人会问直接写字符串常量不就行了为什么要用 Enum我的体会是Enum 带来的不是技术能力是约束力。字符串常量可以被随手拼错可以在任意地方新造一个而 Enum 定死了可选范围IDE 能补全写错了直接报错。团队成员多的时候这个约束特别值钱。我在一个六人协作的项目里推过这套写法前后对比很明显维度字符串散落写法枚举元数据写法新增元素各写各的同一元素多个版本在枚举里加一行定位变更全仓库搜索替换易漏改一行代码 review靠肉眼找硬编码定位集中在一处一眼看完新人上手需要读大量脚本读枚举即懂页面结构当然枚举不是万能药。如果某个元素只在一条用例里用一次、且完全不会变硬塞进公共枚举反而增加噪音。我的判断标准是会被两条以上用例引用的元素才进公共枚举一次性的临时定位写在用例内部即可。3.4 让元数据和动态等待配合起来有了元数据还得有个执行器负责“拿着元数据去找元素”并且把等待逻辑收进去。这是工具集里的核心枢纽from selenium.webdriver.support.ui import WebDriverWait from selenium.webdriver.support import expected_conditions as EC class BasePage: def __init__(self, driver, timeout10): self.driver driver self.wait WebDriverWait(driver, timeout, poll_frequency0.3) def find(self, locator: Locator): return self.wait.until( EC.presence_of_element_located((locator.by, locator.value)) ) def click(self, locator: Locator): el self.wait.until( EC.element_to_be_clickable((locator.by, locator.value)) ) el.click() return self def type(self, locator: Locator, text: str): el self.wait.until( EC.visibility_of_element_located((locator.by, locator.value)) ) el.clear() el.send_keys(text) return self def text_of(self, locator: Locator) - str: return self.find(locator).text这里几个细节值得单独说。poll_frequency0.3比默认的 0.5 秒更灵敏实测在快速响应的页面上能省下不少时间presence_of_element_located和visibility_of_element_located是有区别的前者只要 DOM 里有就算后者要求可见——点按钮之前一定要用可点击或可见条件否则会遇到“元素存在但被遮罩挡住点击无效”的情况而且 Selenium 不一定报错只是静默失败非常难查。4. 把散装脚本拧成工具集分层不只是为了好看4.1 从一把梭脚本到分层的演进路径新手脚本通常是这样的打开浏览器、登录、点菜单、填表单、断言、关闭全部写在一个函数里。这种脚本单看没问题复制十份之后登录逻辑就有了十个版本。哪天登录页加了个验证码你要改十次。分层的目的不是“显得专业”而是把变化隔离在最小范围内。我通常分四层元素层XxxPageElements枚举只管定位元数据。页面对象层XxxPage类封装这个页面的业务动作比如login(user, pwd)。业务流层把多个页面串成完整场景比如“下单流程”。用例层只写断言和参数不碰任何定位。看一个页面对象层的例子class LoginPage(BasePage): URL https://example.com/login def open(self): self.driver.get(self.URL) return self def login(self, username: str, password: str): self.type(LoginPageElements.USERNAME, username) self.type(LoginPageElements.PASSWORD, password) self.click(LoginPageElements.SUBMIT) return self def error_message(self) - str: return self.text_of(LoginPageElements.ERROR_MSG)用例层就变得非常干净def test_login_with_wrong_password(driver): page LoginPage(driver).open() page.login(demo, wrong_pwd) assert 密码 in page.error_message()改定位只动枚举改业务动作只动页面类用例层基本不受影响。这就是分层带来的隔离效果。4.2 通用操作层要抽象到什么程度分层的度很难把握。抽象太少重复代码满天飞抽象太多一层套一层出问题要跳五层调用栈反而更难查。我的经验是只抽象真正被复用两次以上的操作。比较值得抽进BasePage的查找、点击、输入、取文本这类基础动作几乎所有页面都用。等待条件封装比如“等某个元素消失”“等列表加载出 N 条”。滚动到元素、处理弹窗、切 iframe 这类容易写错的操作。不建议抽的只在一个页面用的业务动作直接写在对应页面类里。参数超过五个、还带一堆布尔开关的“万能方法”这种早晚变成灾难。提示判断一个方法该不该抽象最简单的问法是“除我之外还有谁会用”。如果答案只有自己就留在原地。4.3 配置和测试数据一定要跟代码分开把 URL、账号、超时时间硬编码在脚本里是另一个高频坑。用例要在测试环境和预发环境都跑硬编码意味着你要维护两份代码。配置我一般分三块类型内容存放方式环境配置base_url、超时、浏览器类型环境变量或 config 文件测试数据账号、商品、订单参数外部文件yaml/json/csv敏感信息密码、token环境变量绝不进代码仓库超时时间建议做成可配的因为不同环境网速差异很大。本地可能 3 秒就加载完了流水线机器上 10 秒都不够写死一个值必然两头不讨好。4.4 日志、截图、报告观测层三件套用例挂了你手里有什么证据决定了排查要花五分钟还是两小时。我的观测层至少包含结构化日志每一步操作都记一行带上时间戳和当前页面 URL。挂了之后能倒推是哪一步出的问题。失败自动截图用 fixture 或监听器在用例失败时截全屏命名带上用例名和时间。这一条救过我无数次。HTML 报告pytest 环境下pytest-html或allure都能生成前者轻量够用后者信息更全。失败截图的实现大致是这样import pytest pytest.fixture def driver(): d webdriver.Chrome(optionsbuild_options()) yield d d.quit() pytest.hookimpl(tryfirstTrue, hookwrapperTrue) def pytest_runtest_makereport(item, call): outcome yield report outcome.get_result() if report.when call and report.failed: d item.funcargs.get(driver) if d: d.save_screenshot(freports/{item.name}.png)要注意的是截图一定要在driver.quit()之前执行否则会拿到一张空图。这个顺序问题我第一次写的时候踩过排查了半天才反应过来。5. 定位失败排查从报错到根因的完整链路5.1 定位不到元素先分类再动手元素找不到是最常见的失败类型但原因五花八门。我习惯先按下面的清单分类能过滤掉一大半误判现象可能原因快速验证完全找不到报 NoSuchElement定位表达式写错 / 元素在 iframe 里DevTools 里跑一遍 XPath一开始能找后来找不到页面跳转或局部刷新元素过期看看是否发生了导航能找到但点不动被遮罩盖住 / 未完全渲染改成 element_to_be_clickable时好时坏时机问题等待不够或太快加固定延迟观察是否改善只有 CI 上失败视口大小 / 无头渲染差异显式设 window-size定位表达式命中多个选择器不唯一检查是否返回列表5.2 排查顺序我固定的四步法遇到定位问题我不建议东改西改按固定顺序来效率最高先在 DEVTOOLS 里验证表达式。打开 Elements 面板CtrlF粘贴选择器看能不能高亮到目标元素、是不是唯一的。这一步能排除掉 60% 的问题。再看是不是 iframe 或 Shadow DOM。如果 DevTools 能选中但脚本找不到八成是元素在 iframe 里。切进去再找self.driver.switch_to.frame(self.find(IFRAME_LOCATOR)) # 操作完记得切回来 self.driver.switch_to.default_content()然后看等待条件是否匹配真实状态。元素存在但不可见、可点击但被遮挡都会导致操作失败。把presence换成visibility或clickable试试。最后才怀疑页面本身。前三步都没问题那就是页面真的变了或者后端接口挂了导致元素没渲染出来。按这个顺序走基本不会在无关方向上浪费时间。5.3 iframe、动态 ID 和 Shadow DOM 的应对方式iframe是最容易被忽视的。切进去、切出来必须成对漏一次后面的操作全废。建议包成一个上下文管理器from contextlib import contextmanager contextmanager def frame(self, locator: Locator): self.driver.switch_to.frame(self.find(locator)) try: yield finally: self.driver.switch_to.default_content()动态 ID也很常见比如idbutton-1a2b3c每次刷新都变。这种一定要换成相对稳定的属性比如>FROM selenium/standalone-chrome:latest COPY requirements.txt . RUN pip install -r requirements.txt COPY . /app WORKDIR /app CMD [pytest, -n, 4, --htmlreports/result.html]用官方镜像的好处是浏览器、驱动、字体、依赖全配好不用自己折腾。实测踩过的坑是中文乱码容器里默认没有中文字体页面截图全是方块。解决办法是镜像里装上fonts-noto-cjk一行RUN apt-get install -y fonts-noto-cjk就能解决。6.3 报告聚合和失败重试要怎么用并行执行如果还按单进程方式出报告会互相覆盖。用pytest-xdist的话可以配合pytest-html的合并模式或者直接用 Allure 生成分布式结果再汇总。失败重试是把双刃剑。pytest-rerunfailures能对不稳定用例自动重跑短期内能让流水线变绿但它也会掩盖真实的时序问题。我的做法是重试次数设成 1同时统计重试率如果某个用例长期靠重试才过那就不是重试能解决的得回到第 5 节去排查根因。把所有失败都用重试盖住本质上是在骗自己。7. 用了几年之后我总结的几条实在经验等待策略上显式等待永远优先于time.sleep。睡眠看似简单但它既浪费时间又不解决问题——页面慢了照样挂。WebDriverWait配合合理的条件既快又稳。唯一的例外是极少数无法用条件判断的动画场景那种情况用短睡眠加注释说明也算可接受。元素定位能不用 XPath 就不用。XPath 表达力强但脆弱且慢。id、name、>
从散装脚本到可维护工具集：Selenium UI自动化工程化实践
接手过一个项目仓库里躺着两百多个 Selenium 脚本全塞在一个文件里从登录一路 if-else 写到下单。跑一遍四十分钟失败三十多条点进去看一半元素找不到另一半找到了但点不动。那天下午我干的第一件事不是修脚本而是把整个目录拖进回收站——那套东西已经不是自动化是负担。所以我想聊“工具集”。Selenium 本身是一套成熟的浏览器自动化协议API、生态、语言绑定都很稳但它从来不是开箱即用的测试框架。它更像一箱散装零件螺丝、垫片、扳手都有可你要做的是把零件拼成一台能长期运转的机器。同样一套 Selenium有人写出来的东西跑半年不用管有人写出来的三天就烂掉差别不在 API 熟练度而在有没有把它当“工具集”来设计。下面这份内容适合三类人刚学完 Selenium 基本操作、脚本一多就管不住的新手手里有一堆历史脚本想重构的中年项目以及准备把 UI 自动化接进流水线的工程师。我会从环境搭建一路讲到页面元素枚举、定位元数据存储、分层封装、稳定性排查和并行执行重点是讲清楚每个选择背后的理由以及我踩过的那些坑。1. 想清楚再动手Selenium 工具集到底在解决什么问题1.1 Selenium 不是框架它只是一组协议加一堆零件多数人第一次接触 Selenium是照着教程写driver.find_element(By.ID, kw).send_keys(xxx)跑通了就以为学会了。实际上你用的是WebDriver它只是 Selenium 家族里负责“驱动浏览器”的那一块。完整的家族至少包含这几个成员组件定位什么场景用WebDriver核心按 W3C 标准协议操作浏览器写自动化脚本、测试、爬取动态页面Selenium Grid分布式调度多机器、多浏览器并行执行Selenium IDE浏览器录制回放插件快速验证定位、生成雏形脚本Selenium Manager驱动自动管理免去手动下载 driver 的麻烦语言绑定Python / Java / C# / JS 等用你团队熟悉的语言写逻辑关键认知是WebDriver 只保证“能操作浏览器”不保证“好维护”。定位怎么写、等待怎么加、公共操作放哪、失败怎么记录这些全是使用者自己定的规矩。工具集的价值就藏在这些规矩里。1.2 判断一套工具集好坏看三个指标而不是跑通率新手评估自己的自动化习惯看“今天跑通了几个”。这个指标意义不大因为跑通可能只是运气好页面没改。我判断一套 Selenium 工具集是否合格主要看三条定位稳定性页面结构小改一次需要动几行代码如果换个样式类名就要改二十个文件那是灾难。代码复用率登录流程是每个用例都重写一遍还是调一个公共方法三段式的重复代码是维护成本的主要来源。失败可读性一条用例挂了看报告能不能直接判断是“定位错了”还是“业务错了”还是“环境错了”如果只能看到一句TimeoutException那排查时间会翻好几倍。这三条本质上对应工具集的三个模块元素管理层、页面操作层、观测层。后面的章节基本就是围绕这三块展开。1.3 什么规模的项目才值得搭工具集说实话如果你只有十几个用例、页面基本不变、跑一跑图个心安那直接写线性脚本完全没问题硬上分层反而是过度设计。我的经验阈值大致是这样的用例数少于 30、页面一个月内不变线性脚本足够怎么快怎么来。用例数 30 到 100、页面有迭代至少要做元素统一管理和公共方法抽取。用例数过百、要接 CI、多人协作必须完整分层否则维护成本会指数级上升。这不是玄学。脚本数量一多重复代码的维护成本是超线性增长的——改一个登录按钮的定位可能要翻十个文件。工具集的意义就是把这种“N 处修改”压缩成“1 处修改”。2. 环境搭建selenium 安装里最容易被教程带偏的几步2.1 语言选型别纠结技术优劣先看团队会什么网上关于“Python 还是 Java 写 Selenium”的争论从没停过。我的看法很直接看团队现有技术栈。Python 的优势是语法短、写起来快、和数据处理生态衔接自然Java 的优势是工程化成熟、IDE 支持强、和大厂后端测试体系融合好。两者在 Selenium 层面的能力几乎没有差距四天能学会的东西不值得纠结四年。如果实在没倾向我推荐 Python理由是入门曲线平缓且pytest生态对测试组织非常友好。安装本体只有一行pip install selenium但这里有个坑别装完就立刻去pip install webdriver-manager。老教程里几乎都会教你手动装驱动管理器那是 Selenium 4.6 之前的历史包袱现在没必要了下一节细说。2.2 驱动管理从手动下载到 Selenium Manager 的演进驱动chromedriver、geckodriver 之类是 Selenium 最容易劝退新人的部分。浏览器一升级驱动版本对不上就会报SessionNotCreatedException。这个问题的处理方式经历过三代阶段做法痛点第一代手动下载对应版本驱动放进 PATH浏览器一更新就得重下团队各人版本还不一样第二代用 webdriver-manager 自动下载多一个依赖网络不通时会卡住第三代Selenium 4.6 内置 Selenium Manager自动匹配下载基本零配置现在的正确姿势是这样的from selenium import webdriver driver webdriver.Chrome() # 什么都不用传驱动自动就位 driver.get(https://example.com) driver.quit()Selenium Manager 会自动检测本机浏览器版本、去拉匹配的驱动、缓存在本地。实测下来在 4.15 之后的版本相当稳。只有在离线环境或者公司内网限制外网访问时才需要回退到手动指定驱动路径from selenium.webdriver.chrome.service import Service service Service(executable_path/opt/drivers/chromedriver) driver webdriver.Chrome(serviceservice)提示如果公司内网拉不到驱动把驱动文件统一放在一个共享目录用环境变量指定路径比每个人本地各放一份要可靠得多。2.3 浏览器版本对齐与无头模式的取舍无头模式headless是跑 CI 的标配但新手常犯的错误是本地调试也开无头出了问题看不到页面排查全靠猜。我的习惯是本地开发一律带头跑出问题的用例可以肉眼盯着复现只有进了流水线才切无头。切换方式很简单from selenium import webdriver from selenium.webdriver.chrome.options import Options options Options() options.add_argument(--headlessnew) # 新版无头兼容性更好 options.add_argument(--window-size1920,1080) # 无头模式默认视口很小必须显式设 options.add_argument(--disable-gpu) options.add_argument(--no-sandbox) # 容器里跑通常需要 options.add_argument(--disable-dev-shm-usage) driver webdriver.Chrome(optionsoptions)这里有两个真实踩过的坑。第一无头模式默认视口是 800x600很多响应式页面在这个宽度下会渲染成移动端布局元素位置全变定位自然失败所以一定要显式设 window-size。第二--no-sandbox和--disable-dev-shm-usage在容器里几乎是必须的尤其是 Docker 的/dev/shm默认只有 64MB页面复杂时浏览器会莫名其妙崩溃。2.4 IDE 插件和辅助工具怎么选“怎么安装 selenium 插件”这个搜索词经常出现但要先分清你想装的是哪一类录制回放类Selenium IDE浏览器扩展市场直接搜就能装。它的价值不是生成脚本而是快速验证一条 XPath 到底能不能命中元素。我调试定位经常靠它。编辑器支持类VS Code 的 Python / Java 扩展提供补全和跳转属于基础设施。调试增强类Chrome DevTools 本身就是最好的定位工具CtrlF在 Elements 面板里可以直接试 XPath 和选择器比装任何插件都管用。如果你用 PyCharm建议把 Selenium 的源码关联上find_element报错时能直接跳进源码看它到底抛了什么异常对理解问题帮助极大。3. 页面元素枚举把定位元数据和元素实例彻底分开3.1 把 WebElement 存成类属性是新手最大的陷阱先看一段很常见的写法class LoginPage: def __init__(self, driver): self.driver driver self.username driver.find_element(By.ID, username) self.password driver.find_element(By.ID, password)这段代码在页面静态时能跑一旦页面刷新、跳转、局部渲染self.username就变成了“过期引用”再调用它就会抛StaleElementReferenceException。原因得从机制上讲。Selenium 里的WebElement不是一个真实的 DOM 节点它只是一张“凭据”——里面存着一个内部元素 ID每次操作时拿着这个 ID 去浏览器那边找对应节点。页面一旦重新渲染原来的节点被销毁重建旧 ID 就指向了空。很多人以为“元素还在页面上啊为什么说过期了”问题就在这儿元素还在但它的身份变了。所以正确的做法是类里只存定位元数据怎么找不存元素实例找到的东西。每次要用的时候现场去找用完即弃。这个原则听起来反直觉但它是解决绝大多数 stale 问题的根。3.2 定位元数据应该长什么样既然只存“怎么找”那数据结构就很清楚了一个“定位方式 定位值”的组合。用 dataclass 定义是最稳妥的from dataclasses import dataclass from selenium.webdriver.common.by import By dataclass(frozenTrue) class Locator: by: str value: strfrozenTrue让它不可变避免运行期被误改。然后按页面组织元素枚举from enum import Enum class LoginPageElements(Enum): USERNAME Locator(By.ID, username) PASSWORD Locator(By.CSS_SELECTOR, input[typepassword]) SUBMIT Locator(By.XPATH, //button[normalize-space()登录]) ERROR_MSG Locator(By.CSS_SELECTOR, .el-form-item__error)这就是“页面元素枚举 仅存储定位元数据”的落地形态。它带来三个直接好处页面改版只改一处按钮换 ID只改LoginPageElements.SUBMIT这一行所有引用它的地方自动生效。元素清单可读可 review新人接手时看一眼枚举类就知道这个页面有哪些元素、怎么定位的不用满仓库搜索。避免了实例长期持有枚举值是元数据天然不存在 stale 问题。3.3 枚举式管理在多人协作下的真实收益有人会问直接写字符串常量不就行了为什么要用 Enum我的体会是Enum 带来的不是技术能力是约束力。字符串常量可以被随手拼错可以在任意地方新造一个而 Enum 定死了可选范围IDE 能补全写错了直接报错。团队成员多的时候这个约束特别值钱。我在一个六人协作的项目里推过这套写法前后对比很明显维度字符串散落写法枚举元数据写法新增元素各写各的同一元素多个版本在枚举里加一行定位变更全仓库搜索替换易漏改一行代码 review靠肉眼找硬编码定位集中在一处一眼看完新人上手需要读大量脚本读枚举即懂页面结构当然枚举不是万能药。如果某个元素只在一条用例里用一次、且完全不会变硬塞进公共枚举反而增加噪音。我的判断标准是会被两条以上用例引用的元素才进公共枚举一次性的临时定位写在用例内部即可。3.4 让元数据和动态等待配合起来有了元数据还得有个执行器负责“拿着元数据去找元素”并且把等待逻辑收进去。这是工具集里的核心枢纽from selenium.webdriver.support.ui import WebDriverWait from selenium.webdriver.support import expected_conditions as EC class BasePage: def __init__(self, driver, timeout10): self.driver driver self.wait WebDriverWait(driver, timeout, poll_frequency0.3) def find(self, locator: Locator): return self.wait.until( EC.presence_of_element_located((locator.by, locator.value)) ) def click(self, locator: Locator): el self.wait.until( EC.element_to_be_clickable((locator.by, locator.value)) ) el.click() return self def type(self, locator: Locator, text: str): el self.wait.until( EC.visibility_of_element_located((locator.by, locator.value)) ) el.clear() el.send_keys(text) return self def text_of(self, locator: Locator) - str: return self.find(locator).text这里几个细节值得单独说。poll_frequency0.3比默认的 0.5 秒更灵敏实测在快速响应的页面上能省下不少时间presence_of_element_located和visibility_of_element_located是有区别的前者只要 DOM 里有就算后者要求可见——点按钮之前一定要用可点击或可见条件否则会遇到“元素存在但被遮罩挡住点击无效”的情况而且 Selenium 不一定报错只是静默失败非常难查。4. 把散装脚本拧成工具集分层不只是为了好看4.1 从一把梭脚本到分层的演进路径新手脚本通常是这样的打开浏览器、登录、点菜单、填表单、断言、关闭全部写在一个函数里。这种脚本单看没问题复制十份之后登录逻辑就有了十个版本。哪天登录页加了个验证码你要改十次。分层的目的不是“显得专业”而是把变化隔离在最小范围内。我通常分四层元素层XxxPageElements枚举只管定位元数据。页面对象层XxxPage类封装这个页面的业务动作比如login(user, pwd)。业务流层把多个页面串成完整场景比如“下单流程”。用例层只写断言和参数不碰任何定位。看一个页面对象层的例子class LoginPage(BasePage): URL https://example.com/login def open(self): self.driver.get(self.URL) return self def login(self, username: str, password: str): self.type(LoginPageElements.USERNAME, username) self.type(LoginPageElements.PASSWORD, password) self.click(LoginPageElements.SUBMIT) return self def error_message(self) - str: return self.text_of(LoginPageElements.ERROR_MSG)用例层就变得非常干净def test_login_with_wrong_password(driver): page LoginPage(driver).open() page.login(demo, wrong_pwd) assert 密码 in page.error_message()改定位只动枚举改业务动作只动页面类用例层基本不受影响。这就是分层带来的隔离效果。4.2 通用操作层要抽象到什么程度分层的度很难把握。抽象太少重复代码满天飞抽象太多一层套一层出问题要跳五层调用栈反而更难查。我的经验是只抽象真正被复用两次以上的操作。比较值得抽进BasePage的查找、点击、输入、取文本这类基础动作几乎所有页面都用。等待条件封装比如“等某个元素消失”“等列表加载出 N 条”。滚动到元素、处理弹窗、切 iframe 这类容易写错的操作。不建议抽的只在一个页面用的业务动作直接写在对应页面类里。参数超过五个、还带一堆布尔开关的“万能方法”这种早晚变成灾难。提示判断一个方法该不该抽象最简单的问法是“除我之外还有谁会用”。如果答案只有自己就留在原地。4.3 配置和测试数据一定要跟代码分开把 URL、账号、超时时间硬编码在脚本里是另一个高频坑。用例要在测试环境和预发环境都跑硬编码意味着你要维护两份代码。配置我一般分三块类型内容存放方式环境配置base_url、超时、浏览器类型环境变量或 config 文件测试数据账号、商品、订单参数外部文件yaml/json/csv敏感信息密码、token环境变量绝不进代码仓库超时时间建议做成可配的因为不同环境网速差异很大。本地可能 3 秒就加载完了流水线机器上 10 秒都不够写死一个值必然两头不讨好。4.4 日志、截图、报告观测层三件套用例挂了你手里有什么证据决定了排查要花五分钟还是两小时。我的观测层至少包含结构化日志每一步操作都记一行带上时间戳和当前页面 URL。挂了之后能倒推是哪一步出的问题。失败自动截图用 fixture 或监听器在用例失败时截全屏命名带上用例名和时间。这一条救过我无数次。HTML 报告pytest 环境下pytest-html或allure都能生成前者轻量够用后者信息更全。失败截图的实现大致是这样import pytest pytest.fixture def driver(): d webdriver.Chrome(optionsbuild_options()) yield d d.quit() pytest.hookimpl(tryfirstTrue, hookwrapperTrue) def pytest_runtest_makereport(item, call): outcome yield report outcome.get_result() if report.when call and report.failed: d item.funcargs.get(driver) if d: d.save_screenshot(freports/{item.name}.png)要注意的是截图一定要在driver.quit()之前执行否则会拿到一张空图。这个顺序问题我第一次写的时候踩过排查了半天才反应过来。5. 定位失败排查从报错到根因的完整链路5.1 定位不到元素先分类再动手元素找不到是最常见的失败类型但原因五花八门。我习惯先按下面的清单分类能过滤掉一大半误判现象可能原因快速验证完全找不到报 NoSuchElement定位表达式写错 / 元素在 iframe 里DevTools 里跑一遍 XPath一开始能找后来找不到页面跳转或局部刷新元素过期看看是否发生了导航能找到但点不动被遮罩盖住 / 未完全渲染改成 element_to_be_clickable时好时坏时机问题等待不够或太快加固定延迟观察是否改善只有 CI 上失败视口大小 / 无头渲染差异显式设 window-size定位表达式命中多个选择器不唯一检查是否返回列表5.2 排查顺序我固定的四步法遇到定位问题我不建议东改西改按固定顺序来效率最高先在 DEVTOOLS 里验证表达式。打开 Elements 面板CtrlF粘贴选择器看能不能高亮到目标元素、是不是唯一的。这一步能排除掉 60% 的问题。再看是不是 iframe 或 Shadow DOM。如果 DevTools 能选中但脚本找不到八成是元素在 iframe 里。切进去再找self.driver.switch_to.frame(self.find(IFRAME_LOCATOR)) # 操作完记得切回来 self.driver.switch_to.default_content()然后看等待条件是否匹配真实状态。元素存在但不可见、可点击但被遮挡都会导致操作失败。把presence换成visibility或clickable试试。最后才怀疑页面本身。前三步都没问题那就是页面真的变了或者后端接口挂了导致元素没渲染出来。按这个顺序走基本不会在无关方向上浪费时间。5.3 iframe、动态 ID 和 Shadow DOM 的应对方式iframe是最容易被忽视的。切进去、切出来必须成对漏一次后面的操作全废。建议包成一个上下文管理器from contextlib import contextmanager contextmanager def frame(self, locator: Locator): self.driver.switch_to.frame(self.find(locator)) try: yield finally: self.driver.switch_to.default_content()动态 ID也很常见比如idbutton-1a2b3c每次刷新都变。这种一定要换成相对稳定的属性比如>FROM selenium/standalone-chrome:latest COPY requirements.txt . RUN pip install -r requirements.txt COPY . /app WORKDIR /app CMD [pytest, -n, 4, --htmlreports/result.html]用官方镜像的好处是浏览器、驱动、字体、依赖全配好不用自己折腾。实测踩过的坑是中文乱码容器里默认没有中文字体页面截图全是方块。解决办法是镜像里装上fonts-noto-cjk一行RUN apt-get install -y fonts-noto-cjk就能解决。6.3 报告聚合和失败重试要怎么用并行执行如果还按单进程方式出报告会互相覆盖。用pytest-xdist的话可以配合pytest-html的合并模式或者直接用 Allure 生成分布式结果再汇总。失败重试是把双刃剑。pytest-rerunfailures能对不稳定用例自动重跑短期内能让流水线变绿但它也会掩盖真实的时序问题。我的做法是重试次数设成 1同时统计重试率如果某个用例长期靠重试才过那就不是重试能解决的得回到第 5 节去排查根因。把所有失败都用重试盖住本质上是在骗自己。7. 用了几年之后我总结的几条实在经验等待策略上显式等待永远优先于time.sleep。睡眠看似简单但它既浪费时间又不解决问题——页面慢了照样挂。WebDriverWait配合合理的条件既快又稳。唯一的例外是极少数无法用条件判断的动画场景那种情况用短睡眠加注释说明也算可接受。元素定位能不用 XPath 就不用。XPath 表达力强但脆弱且慢。id、name、>
