Robot Framework安装全攻略：从Python到浏览器驱动一步到位

做自动化测试这几年我见过太多人第一天就把时间耗在装环境上Python装好了发现 pip 用不了框架装上又报“No module named xxx”折腾到晚上浏览器还是打不开。Robot Framework 是目前使用最广的自动化测试框架之一但它本身不是一个“双击安装包”的软件它需要一条完整的工具链Python、pip、核心框架、扩展库、浏览器驱动任何一个环节断了后面全白搭。这篇文章我会从零开始把 Robot Framework 的安装前准备、核心安装、扩展库安装、浏览器驱动配置、第一个可运行用例到最后的常见报错与排查每一步都讲清楚并且告诉你每个关键步骤背后的原因。适合刚接触自动化测试、准备入坑 RF 的测试同学也适合团队里需要搭环境的技术负责人照着操作。1. Robot Framework 是什么为什么安装前要先搞明白1.1 它其实是一个“关键字翻译机”很多人以为 Robot Framework 和 Selenium 是一类东西装上就能直接操作浏览器。不是的RF 的本质是一套基于关键字驱动的自动化测试框架。它在中间扮演“翻译机”的角色你写的用例是自然语言风格的表格框架负责解析这些关键字再调用底层库去真正干活。真正打开浏览器、点击页面的是 SeleniumLibrary真正发 HTTP 请求的是 RequestsLibrary。RF 只负责组织、调度、生成日志和报告。所以安装的时候你至少要装两层东西核心框架负责解析和执行.robot用例文件扩展库提供具体的关键字比如打开浏览器、发送请求这个认知如果没建立起来后面遇到“No module named SeleniumLibrary”这类报错时你根本不知道它到底在说什么很容易卡住。1.2 它适合什么人、什么场景RF 适合的场景非常广Web UI 测试、接口测试、数据库校验、SSH 远程操作、RPA 流程自动化都能通过不同的扩展库实现。它的优势在于用例可读性极高几乎不用写代码测试团队成员哪怕不会 Python也能通过看用例理解业务逻辑。如果你所在的团队有业务人员参与测试或者你希望测试用例能“给人看”而不是“只给机器看”RF 会是比 pytest 更合适的选择。反过来说如果你们团队全是程序员项目又主要是纯后端接口测试那 pytest 可能更轻量。这两个并不冲突很多团队是两者都用的。装上 RF 之后对比着用你会更清楚它擅长什么。2. 安装前的环境准备Python、pip 和编辑器2.1 Python 版本为什么是关键Robot Framework 是基于 Python 的所以装 RF 之前必须先装 Python。RF 7.x 系列要求 Python 3.8 以上目前看下来 Python 3.10 和 3.11 是最稳的选择。3.12、3.13 也能用但某些扩展库对最新 Python 的适配偶尔慢半拍新手没必要冒这个险。在 Windows 上装 Python 时最容易踩的坑是安装时没勾选“Add Python to PATH”。别看这个复选框不起眼一旦漏了后面python命令、pip命令全部找不到RF 装完也会提示“robot 不是内部或外部命令”。我自己装环境时遇到过好几次这种现场最后都出在这一个勾上。装完之后打开命令行分别执行python --version python -m pip --version能正常输出版本号说明 Python 和 pip 都可用。注意这里我用的是python -m pip而不是直接pip。这能避免系统里装了多个 Python 版本时pip 装到别的环境里去。这个习惯一定要养成。2.2 给 pip 换个源安装速度立马上来如果你直接执行 pip 安装命令默认会去 PyPI 官方源下载。国内网络访问官方源时快时慢经常一个包下到一半就超时。解决办法是换成国内镜像源推荐清华源或阿里源。在命令行里执行一次就把配置写入到全局pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple再验证一下pip config list看到global.index-url已经指向镜像源就算配置好了。之后所有pip install都会走这个镜像速度肉眼可见地提升。公司内网环境如果要求用内部源把 URL 换成你们自己的 PyPI 镜像地址即可。2.3 编辑器选 VS Code 还是 PyCharm写 RF 用例不一定用 IDE纯文本都能写但想要语法高亮、自动补全、用例调试建议装 VS Code。PyCharm 社区版对 RF 基本没有原生支持专业版虽然可以装插件但要收费性价比不高。VS Code 免费、轻量配合 Robot Framework Language Server 插件写用例体验非常接近 IDE。如果你还没装 VS Code安装时注意勾选“添加到右键菜单”和“将 code 命令添加到 PATH”的选项后面在项目目录打开终端会方便很多。3. 核心安装实操主框架、扩展库和浏览器驱动3.1 三步装好 Robot Framework 主框架第一步用 pip 安装核心包python -m pip install robotframework它会自动把 RF 的最新稳定版拉下来。安装过程中如果出现“Requirement already satisfied”之类的提示说明之前已经装过不需要重复安装。第二步验证是否装好robot --version正常会输出版本信息大概长这样Robot Framework 7.1 (Python 3.11.9 on win32)如果提示robot 不是内部或外部命令多半是 Python 安装时没勾选 PATH导致 Python 的 Scripts 目录没有加入环境变量。你需要手动找到 Python 安装目录下的 Scripts 文件夹比如C:\Users\你的用户名\AppData\Local\Programs\Python\Python311\Scripts把它加到系统环境变量的 Path 里然后重新打开命令行。第三步用 pip 确认包信息python -m pip show robotframework能看到Version、Location等信息说明核心框架已经完成安装。3.2 把常用扩展库一次性装齐核心装完只能运行 RF 自带的内置关键字比如Log、Should Be Equal还达不到“能测 Web、能测接口”的程度。扩展库才是真正干活的。常用的有这么几个库名用途安装命令robotframework-seleniumlibraryWeb 界面自动化python -m pip install robotframework-seleniumlibraryrobotframework-requestsHTTP 接口测试python -m pip install robotframework-requestsrobotframework-appiumlibrary移动端 App 自动化python -m pip install robotframework-appiumlibraryrobotframework-databaselibrary数据库校验python -m pip install robotframework-databaselibraryrobotframework-sshlibrarySSH 远程操作python -m pip install robotframework-sshlibrary如果你刚开始学建议先装前两个一个覆盖 UI一个覆盖接口足够支撑大部分日常工作了。python -m pip install robotframework-seleniumlibrary python -m pip install robotframework-requests安装 SeleniumLibrary 时它会自动把 Selenium 一起装上。要注意的坑是SeleniumLibrary 6.x 需要 Selenium 4.x如果你之前单独装过 Selenium 3.x可能会冲突。遇到问题可以先卸载重装python -m pip uninstall selenium robotframework-seleniumlibrary -y python -m pip install robotframework-seleniumlibrary3.3 浏览器驱动90% 新手会卡在这里装完 SeleniumLibrary 之后如果你直接跑“打开浏览器”用例大概率会报错提示chromedriver executable needs to be in PATH。这里解释一下原因Selenium 本身不会去操作浏览器它要通过浏览器厂商提供的 WebDriver 驱动来控制。Chrome 对应 chromedriverEdge 对应 msedgedriverFirefox 对应 geckodriver。这个驱动必须下载到你本地并且版本要和浏览器版本匹配。检查步骤第一步查看浏览器版本。以 Chrome 为例在地址栏输入chrome://version记下“Google Chrome”那一行的版本号比如120.0.6099.109。第二步下载对应版本的驱动。注意版本不需要一模一样的补丁号大版本一致即可比如 Chrome 是 120.x就下载 chromedriver 120.x。下载地址可以到 Chrome for Testing 的镜像站选择或者搜“chromedriver 120 下载”找到可信的镜像。第三步下载完成后把解压出来的chromedriver.exe放到 Python 的 Scripts 目录里。因为 Scripts 目录通常已经加入了 PATH这样 Selenium 就能自动找到驱动了。如果你用 Edge操作完全一样只是驱动文件名是msedgedriver.exe。放好之后重新打开命令行运行chromedriver --version能看到版本号说明驱动已经就位。这一步过了Selenium 才能打通浏览器后面写用例才有意义。4. 写第一个能跑通的用例并配置 VS Code4.1 从“冒烟用例”开始环境都装好了别急着写复杂业务用例先写一个最简单的“冒烟用例”验证链路是否通畅。新建一个demo.robot文件保存为 UTF-8 编码内容如下*** Settings *** Library SeleniumLibrary *** Test Cases *** 打开网站验证标题 Open Browser https://www.baidu.com Chrome Maximize Browser Window Title Should Be 百度一下你就知道 Close Browser解释一下每一段的作用*** Settings ***声明用例文件使用的库。这里写SeleniumLibraryRF 才会把它提供的关键字加载进来。*** Test Cases ***定义具体的测试用例。Open Browser、Maximize Browser Window、Title Should Be、Close Browser都是 SeleniumLibrary 提供的关键字分别表示打开浏览器、最大化窗口、校验标题、关闭浏览器。在demo.robot所在目录打开命令行执行robot demo.robot如果一切正常命令行会显示用例通过同时目录下会生成三个文件output.xml、log.html、report.html。它们分别用来记录原始输出、日志明细和汇总报告。log.html和report.html直接用浏览器打开就能看非常直观。这一点也是 RF 比纯代码框架更有优势的地方——天生自带报告不用额外搭测试报告平台。4.2 在 VS Code 里享受自动补全命令行能跑通之后建议立刻配置 VS Code否则纯手写关键字还是很痛苦的。第一步打开 VS Code 扩展商店搜索Robot Framework Language Server并安装。这个插件提供语法高亮、智能补全、悬停提示和错误检查。第二步按Ctrl,打开设置搜索python.defaultInterpreterPath把它设置为你的 Python 安装路径。如果不确定在命令行执行where python拿到完整路径后填进去即可。设置好之后再新建.robot文件输入关键字时会自动弹出补全列表写用例效率会高很多。如果遇到插件一直提示找不到解释器的情况在 VS Code 里按CtrlShiftP输入Python: Select Interpreter手动选择你当前用的 Python 环境即可。4.3 关于 RIDE要不要装RIDE 是 RF 官方绑定工具里的图形化编辑器最初由 Robot Framework 核心团队支持很多老项目用到现在。安装命令python -m pip install robotframework-ride它依赖 wxPython在某些 Windows 环境下安装会有一定复杂度偶尔还要装 Visual C 运行库。我的看法是个人学习和日常使用没必要装 RIDEVS Code 的插件体验已经足够好如果团队里有不太熟悉命令行的业务测试人员RIDE 倒可以作为一种降低上手门槛的补充工具。5. 安装和初运行最常见的报错与排查5.1 库导不进来No module named xxxRF 用例最常见的报错就是[ ERROR ] Error in file demo.robot: Importing library SeleniumLibrary failed: ModuleNotFoundError: No module named SeleniumLibrary排错思路按顺序来第一步先确认库到底装没装python -m pip list看看输出里有没有 SeleniumLibrary。第二步确认库名拼写是否正确。比如SeleniumLibrary中间没有空格大小写也有要求。库名写错了RF 找不到肯定会报同样的错。第三步确认是不是装到了别的 Python 环境里。如果你用pip install装的库但跑用例时用的又是另一个 Python就会出现明明装了却找不到的情况。统一用python -m pip系列命令能大概率规避这个问题。5.2 浏览器打不开WebDriverException 和驱动路径问题如果运行到Open Browser这行时报错WebDriverException: Message: chromedriver executable needs to be in PATH.说明驱动位置不对。处理办法我已经在“3.3 浏览器驱动”里写过了核心点就是确认 chromedriver.exe 在 PATH 目录下并且驱动版本和浏览器版本的大版本一致。比如浏览器自动升级到 121 了你的驱动还是 120就会报SessionNotCreatedException: This version of ChromeDriver only supports Chrome version 120遇到这种报错不需要慌下载匹配当前浏览器版本的驱动替换旧文件就行。5.3 控制台中文乱码Windows 命令行默认编码不是 UTF-8RF 用例里的中文输出可能出现乱码用例本身不一定失败但日志没法看。解决办法有两个建议一起做第一设置环境变量PYTHONIOENCODINGutf-8保证 Python 输出以 UTF-8 编码。第二在命令行里执行chcp 65001把控制台代码页切换到 UTF-8。另外还有个容易被忽略的地方.robot文件如果保存成了 GBK 或 ANSI 编码RF 解析时也可能出现中文识别异常。在 VS Code 里新建文件时确认右下角编码显示是 UTF-8 即可。5.4 一条命令也跑不起来按这个顺序排查有时候你会遇到连robot --version都执行不顺畅的情况这种时候不要瞎试按顺序排查python --version python -m pip --version python -m pip show robotframework robot --version第一步如果失败说明 Python 安装或 PATH 有问题第二步如果失败排查 pip 版本和环境变量第三步如果失败说明框架没装好重新执行安装命令第四步如果失败大概率是 Scripts 目录没加入 PATH这套流程看着简单但它能把 80% 的环境问题在几分钟内定位出来比到处搜教程有效得多。5.5 常见问题速查表问题现象可能原因解决办法python 不是内部或外部命令Python 未安装或未加入 PATH重装 Python勾选 Add Python to PATHpip 不是内部或外部命令未正确加入 PATH改用python -m pip安装很慢或超时pip 源在国外配置清华/阿里镜像源robot 不是内部或外部命令Scripts 目录不在 PATH把 Python Scripts 目录加入 PATHNo module named SeleniumLibrary库未安装或装错环境python -m pip list检查后重装chromedriver executable needs to be in PATH驱动不在 PATH把驱动放到 Python Scripts 目录This version of ChromeDriver only supports Chrome version xx驱动与浏览器版本不匹配下载匹配版本的驱动控制台输出中文乱码编码不对设置PYTHONIOENCODINGutf-8执行chcp 65001最后分享一个我自己装机的小习惯装完环境之后先别急着一个一个去试功能我用一条最简用例把链路跑通确认 Python、框架、库、驱动、编辑器五层全部 OK再开始实际工作。这样以后再遇到问题我就知道问题大概率出在新增的代码和配置上而不是环境本身。Robot Framework 的安装其实就这点东西把链路搞清楚、把版本匹配好后面基本不会再被环境折腾。