Katalon Recorder安装配置与自动化录制回放避坑指南

简介Katalon Recorder 脚本录制工具包面向需要快速上手 Web 自动化测试的开发者与测试人员尤其适合刚接触 Selenium、希望降低脚本编写门槛的初中级使用者。它能把浏览器操作直接转化为可执行的自动化脚本缓解手工回归测试重复劳动多、录制与回放流程搭建慢的问题。压缩包共 4 个文件含 2 个 crx 扩展与 2 个 html 说明文档整体约 3.95MBcrx 为可直接拖入 Chrome 扩展管理页安装的录制插件html 承载安装指引与使用说明便于对照完成环境准备。目前已有 1522 人学习下载。读者可获得一套完整的浏览器端录制—回放工作流录制时自动识别页面元素并生成测试步骤录制后可在内置编辑器中调整脚本、补充断言与循环等逻辑以覆盖更复杂的场景遇到元素定位或回放异常时也能借助说明文档与社区教程找到排错方向。1. 装前先对齐版本Katalon Recorder 扩展版和桌面版别混着来Katalon Recorder 这类脚本录制工具很多人的第一印象是「一个浏览器插件装上点红点就能录」真到动手那天才发现完全不是这么回事。做自动化回归的团队几乎绕不开它手工用例攒了几百条想低成本转成可重复执行的脚本录制是不写代码的唯一入口。可装错了版本形态扩展在浏览器工具栏里是灰的录制按钮点下去没反应导出的脚本一行都跑不通排查两小时才发现装的是旧架构的包。这套东西适合两类人刚接手自动化、想先把一条流程跑通的新手和要把手工用例批量转成脚本、还得塞进持续集成流水线的熟手。第 1 章不讲命令先把「装哪种」这件事定下来后面所有步骤才有意义。2. 环境先列清Katalon Recorder 装前要对的浏览器、JDK 和驱动版本2.1 三样东西的版本关系先记录再动手接手一台新机器我一般不会先解压而是先跑四条命令把宿主环境记录下来。原因很实际Katalon Recorder 的坑十有八九不是它自己的而是浏览器主版本、驱动主版本、运行时版本这三者对不上。扩展跑在浏览器里浏览器主版本决定了三件事——能不能加载这个扩展清单版本、录制用的页面事件接口是否还在、导出的 WebDriver 代码该配哪个驱动。这三件事任意一件出偏差表现都是「录得到、放不出来」或者「放得出来、导出跑不了」。组件在本方案里的作用版本取舍不匹配的典型症状Chrome / Edge扩展宿主录制与回放的运行环境用稳定版把主版本号记下来扩展卡片显示「已停用」扩展清单版本决定浏览器是否还允许加载新包一般是 3旧包是 2加载时提示清单不可读或被策略拦截JDK导出 Katalon Studio 工程、Robot Framework 用例、流水线执行8、11、17 都有人跑新环境优先 17导出的 groovy 打不开工程浏览器驱动导出 WebDriver 代码后脱离录制器独立执行主版本号必须等于浏览器主版本Session not createdPython 3.9导出 Python 脚本的运行时3.9 以上用虚拟环境隔离模块导入失败、selenium 版本太老# 把宿主环境的版本一次性打出来存进自己的部署笔记备查 # 1) 浏览器主版本也可以在地址栏打开 chrome://version 直接看 export CHROME_BIN/usr/bin/chromium # 按自己机器上的实际路径改macOS 指向 .app 内部的可执行文件 $CHROME_BIN --version # 2) JDK只导出 Katalon Studio 工程和 Robot Framework 用例时才需要 java -version 21 | head -n 1 # 3) 驱动主版本号要跟上面的浏览器主版本完全一致 chromedriver --version 2/dev/null || echo chromedriver 尚未安装 # 4) Python 运行时导出 Python 脚本才用得上 python3 -V这段命令没有任何副作用纯粹是为了留证据。后面任何一步翻车第一步都是拿这几行输出跟报错信息对一遍比盲目重装快得多。参数上唯一要注意的是CHROME_BIN这个变量它只是个普通环境变量名改成BROWSER_PATH之类也行关键是别在脚本里写死平台路径——同一套脚本要在一台 Linux 构建机和一台 macOS 开发机上跑路径写死是必踩的坑。java -version的输出走的是标准错误所以要21才能被head接住这个细节很多人第一次写检查脚本时会漏掉导致检查永远显示「未安装 JDK」。chromedriver --version后面跟了||兜底是因为很多机器上驱动不是全局安装的而是随项目放在drivers/目录里没装就该老实打印「尚未安装」而不是让整段脚本中断。有一点要提前说清楚Katalon Recorder 的浏览器扩展形态本身不需要 JDK。很多人看到教程里让装 Java 就顺手装了其实只有在你要把录制的用例导出成 Katalon Studio 工程、导出 Robot Framework 用例、或者在流水线里跑这几种场景下JDK 才是硬依赖。纯录制加导出 Selenium WebDriver 代码的路径Python 加 Selenium 就够了。2.2 三种安装路径的取舍商店装、离线目录装、桌面版装同一个工具落地方式有三种选错了后面全是麻烦。安装方式耗时版本可控性适用场景主要代价浏览器扩展商店安装最低低跟着商店走个人临时试用、外网环境团队内版本不一致回放行为有差异离线已解压目录加载中高包是什么版本就是什么版本内网、构建机、需要长期复现的环境每次启动可能提示开发者模式扩展桌面版独立安装中高长时间回放、不想依赖浏览器面板多一份运行时导出选项略有差异团队协作场景我基本只推第二种。原因很直白录制出来的用例要进版本库要给别人复现如果 A 的扩展是商店自动更新到的新版、B 的是三个月前的旧版同一份.side文件在两个人机器上回放结果不一致这种事查起来非常消耗精力。离线目录加载把版本钉死在一个固定路径下包跟着项目走谁拉下来都是同一份。商店安装适合快速验证「这东西能不能解决我的问题」但别把它当成长期方案。桌面版适合回放时间长的场景——录制器挂在浏览器面板里浏览器一关回放就断了桌面版是独立进程稳定得多代价是多一套安装包而且要单独确认它内置的驱动版本。2.3 安装前的清理和目录规约在解压之前先做两件清理。第一禁用机器上其它同类录制扩展比如老版本的同类录制器。多个录制器同时监听页面事件表现是点击一次在用例表里冒出两三条重复命令或者干脆一条都没有——这不是玄学就是事件被抢了。第二如果之前装过旧版 Katalon Recorder先在扩展管理页面移除别直接覆盖加载残留的旧配置会让新版本的默认超时、定位器顺序全是上一版的。目录我统一按下面这个结构放好处是后面所有命令都能用固定路径不用每次cd到解压目录里找半天# 建立统一的工具目录扩展、桌面版安装包、驱动、导出的工程分开放 mkdir -p $HOME/tools/katalon-recorder/{extension,desktop,drivers,projects} # 解压到临时目录再挑避免压缩包内多套一层同名文件夹时路径写错 unzip -q Katalon Recorder-脚本录制工具.zip -d $HOME/tools/katalon-recorder/_unpack # 确认解压结果的层级重点看 extension 目录下是不是直接躺着 manifest.json find $HOME/tools/katalon-recorder/_unpack -maxdepth 3 -name manifest.json-q是安静模式解压几十上百个文件时不会刷屏-d指定目标目录这个参数一定要写否则压缩包会散落在当前工作目录里。压缩包名字带空格和中文所以必须用引号包住这一步在 Windows 的 Git Bash 里尤其容易出问题。find那行的作用是提前定位manifest.json的位置——浏览器加载未打包扩展时你选中的目录必须直接包含 manifest.json多套一层父目录就会报清单文件缺失这是新手最常卡住的地方放到第 5 章还会细说。另外提醒一句Windows 上用系统自带解压工具处理含中文文件名的压缩包偶尔会出现文件名乱码导致后续路径对不上。遇到这种情况换 7-Zip 或者命令行unzip重新解一遍别在乱码目录上硬改。3. 安装实操Katalon Recorder 离线包解压、扩展加载与首次启动3.1 解压后的目录结构核对包解出来之后先别急着往浏览器里加载花一分钟把目录用途对一遍。这类离线包通常按安装方式分了子目录扩展目录是给浏览器加载用的桌面版目录里放的是各平台的安装程序驱动目录里放的是对应版本的浏览器驱动另外还有一份快速上手说明。不同版本的分法可能略有出入但manifest.json一定在扩展目录的最外层。# 用一行 Python 把扩展清单的关键字段读出来确认版本形态对不对 python3 - PY import json, pathlib p pathlib.Path.home() / tools/katalon-recorder/extension/manifest.json m json.loads(p.read_text(encodingutf-8)) print(name :, m.get(name)) print(version :, m.get(version)) print(manifest_version:, m.get(manifest_version)) print(permissions :, ,.join(m.get(permissions, []))[:120]) PY这段脚本读的是扩展清单本身输出里最该盯的是manifest_version这一项。它决定了当前浏览器还认不认这个扩展老版本清单在新版浏览器上会被直接拒绝加载卡片变灰、开关打不开报错通常只说「此扩展程序可能已损坏」之类不会明说版本问题。把这一行先记下来后面出问题能省一大圈。permissions那行做截断输出是为了快速确认扩展有没有拿到页面读写、标签页访问这类权限。少了某个权限表现是能打开面板但录不到页面动作跟装错版本的症状很像容易误判。3.2 浏览器开发者模式加载离线扩展标准流程走一遍五步每一步都有个容易漏的点。地址栏进扩展管理页打开右上角「开发者模式」开关。不开这个开关加载按钮根本不出现。点「加载已解压的扩展程序」在文件选择框里选中extension目录——注意是包含 manifest.json 的那一层不是它的父目录。加载成功后卡片上会出现扩展 ID 和一串版本号把这两个值抄进部署笔记。点工具栏的拼图图标把这个扩展固定到工具栏否则录制入口藏得太深每次都要翻两层菜单。关掉开发者模式开关前先想一下关掉之后用「加载已解压」方式装进来的扩展可能会被停用。日常开发建议保持开启。企业环境里如果加载按钮是灰的、提示「由贵组织管理」那是浏览器策略在生效个人层面改不动需要找管策略的人把扩展 ID 加进白名单。这种情况不用反复重装装十遍也是一样的结果。3.3 用命令行带扩展起一个独立实例日常浏览器上装一堆扩展录制时最怕的就是别的扩展往页面里注入脚本干扰定位。我的做法是给录制器单独开一个浏览器配置目录启动时只加载这一个扩展# 独立 profile 只加载录制扩展避免其它扩展干扰页面事件 PROFILE_DIR$HOME/.katalon-recorder-profile EXT_DIR$HOME/tools/katalon-recorder/extension $CHROME_BIN \ --user-data-dir$PROFILE_DIR \ --load-extension$EXT_DIR \ --disable-extensions-except$EXT_DIR \ --no-first-run \ --no-default-browser-check \ about:blank--user-data-dir指定独立的用户配置目录登录态、书签、扩展配置全在这个目录里跟日常浏览器完全隔离删掉这个目录就等于重置录制环境。--load-extension加载未打包扩展--disable-extensions-except反过来屏蔽其它所有扩展只留指定的这一个——这两个参数配合使用才能做到「干净实例」。后两个--no-*是跳过首次运行引导和默认浏览器检查在构建机上跑的时候不加会被弹窗卡住。注意浏览器版本迭代过程中命令行加载未打包扩展的能力被收紧过部分版本上--load-extension会被静默忽略扩展没加载但没有任何报错。遇到这种情况别死磕命令行退回 3.2 的手动加载流程操作一次配置目录会记住这个扩展之后用同一个--user-data-dir启动就能带上它。3.4 首次启动后的基础设置扩展面板第一次打开是空的先调四项再录第一条。设置项建议值说明默认超时30000 ms单条命令等待元素出现的上限内网慢系统可以到 45000回放速度中速调太快会掩盖真实的时序问题调到最快只能骗自己默认导出格式与团队技术栈一致Python 栈导 pytest已有 Katalon 工程导 groovy高亮/滚动开启回放时能肉眼看到执行到哪一步排错成本直接减半这四项里最容易被忽略的是回放速度。很多人为了让用例跑得快把速度拉到最高本地全绿一上流水线就大片超时。录制回放的价值在于稳定复现不在于快速度留在中速把不稳的等待改成显式等待比调速度有用得多。4. 录制配置定位器、超时和导出格式三个参数怎么定4.1 定位器优先级把易变的排到后面录制器生成的每条命令都带一个定位表达式写进表格的 target 列。默认情况下它会同时尝试多种定位策略按顺序挑第一个能唯一命中的。问题在于很多页面的 id 是框架自动生成的带一串随机字符今天录的明天就变了有些列表页的 XPath 带位置下标页面上多一条数据整个表达式就错位。我的做法是进设置面板把定位器构建顺序调成下面这样并且把带位置下标的 XPath 和 DOM 路径这两项直接取消勾选优先级定位类型稳定性说明1id高前提是 id 是人工命名、不含随机串2name高表单元素上很常见3CSS 选择器中高语义化 class 稳定纯样式 class 不稳4链接文本中只适用于可点击的链接改文案就失效5XPath属性中用属性定位可以别带下标关XPath位置低页面结构一变全废关DOM 路径低同上且可读性极差调完顺序不代表就完事了。录制结束后一定要把用例表从头到尾扫一遍凡是 target 列里出现连续数字、哈希串、div[3]/div[2]这种结构的当场改成稳定定位。这一步花五分钟能省掉后面反复回放失败的两小时。表格里的 target 是可以直接双击编辑的改完记得保存用例。4.2 三个时间参数别混着用录制器里跟时间相关的参数不止一个混用是回放不稳定的主因。参数作用范围调大的后果默认超时每条等待类命令查找元素的上限失败用例整体变慢问题被掩盖页面加载超时打开新页面时等待加载完成的上限单页应用上意义不大反而拖时间命令间隔两条命令之间的固定停顿用例总时长线性变长治标不治本真正有效的做法不是全局调大而是在关键节点插显式等待。下面是一段录制后整理过的命令序列能看出等待该加在哪commandtargetvalueopen/loginwaitForElementVisibleidusername15000typeidusernamedemo_usertypeidpassworddemo_passclickidsubmitwaitForElementVisiblecss.dashboard-title20000assertTextcss.dashboard-title控制台waitForElementVisible的 value 是该条命令自己的等待上限跟全局默认超时是两回事。加在open之后是因为单页应用路由切换时 DOM 是异步渲染的页面加载完成不代表元素已经在了加在click之后是因为登录请求有网络往返跳转时间不可控。这两处加上显式等待全局默认超时才有条件调回 30000整体反而更快。assertText放在最后是用来做结果校验的。只录制操作不录制断言回放永远是绿的这种用例没有任何价值——它只能证明流程能点通证明不了结果对不对。4.3 导出格式与目标工程对接录制只是中间产物最终要落到能进版本库、能进流水线的代码上。导出选项一般有这几类导出目标产出前置依赖适用场景Katalon Studio 工程groovy 脚本 工程结构安装 Katalon StudioJDK团队已有该工程体系.side 文件JSON 格式的用例存档无跨工具复用、长期归档Pythonunittest / pytest 用例Python selenium纯 Python 技术栈JavaJUnit / TestNG 用例JDK Maven 或 GradleJava 后端团队Robot Frameworkrobot 用例robotframework selenium 库已有 RF 关键字体系C#NUnit / MSTest 用例.NET SDK.NET 团队选择的判断标准只有一条这套用例最终跑在哪个流水线里。别为了导出方便选一个团队根本不维护的技术栈导出来的代码没人接等于白录。没有流水线、只想先把手工用例存档的导.side就够它结构简单将来换工具也迁得动。4.4 用 .side 文件做用例版本管理.side本质是个 JSON 文件用 git 管理它diff 出来的内容是可读的。这一点比导出成脚本更有优势——脚本里混着大量框架代码改一个定位器 diff 出一大片评审时根本看不出改了什么。# 统计一个 .side 文件里的用例条数和命令条数方便衡量改动规模 jq .tests | length projects/login.side jq [.tests[].commands[]] | length projects/login.side # 对比两次提交之间到底改了哪些定位器比看脚本 diff 清爽得多 git diff HEAD~1 -- projects/login.side | grep -E ^\.*(target|command)jq这两个表达式分别取用例数组长度和所有命令的扁平长度第一个数字是用例数第二个是命令总数。用例改动评审时看这两个数就能判断规模涨了几十条命令的提交值得细看。第二条命令过滤出新增行里的命令和定位表达式定位器被批量替换这类改动一眼就能发现。文件命名建议按「模块_场景_序号」来比如login_正常登录_01.side、order_取消订单_02.side。别用日期命名用例是长期资产日期只反映录制时间跟内容无关检索时反而碍事。同一目录下再放一份 README 写清楚每条用例的前置数据半年后来接手的人会省很多事。5. 排查避坑Katalon Recorder 装不上、录不到、回放全红的 5 个坑5.1 加载扩展报「清单文件缺失或不可读」现象在扩展管理页选中目录后弹窗提示清单文件缺失或不可读卡片加载不出来。原因选中的目录不是包含 manifest.json 的那一层。压缩包解压后常常多套一层同名文件夹或者清单文件在extension/子目录里用户顺手选了最外层。另一种可能是解压不完整清单文件被截断成零字节。解决先find定位清单文件的确切路径再回到文件选择框选它所在的目录。如果是零字节删掉重解压。这个问题跟浏览器版本无关也不涉及权限纯粹是路径选错但报错文案完全看不出来所以排第一位。5.2 扩展装上了卡片显示「已停用」现象加载过程没报错但卡片是灰的开关打不开提示可能已损坏或被策略停用。原因三种可能。扩展清单版本过旧当前浏览器已经不再加载这个版本浏览器处于无痕模式或某个受限配置下企业策略把未打包扩展统一禁用了。解决先看 3.1 打出来的manifest_version太旧就换新版安装包再换正常窗口试一次最后进策略页确认有没有管理员策略在管。前两种自己能解决第三种只能走白名单流程别浪费时间反复重装。5.3 点了录制页面操作一条都记不下来现象录制按钮是开着的页面上点输入框、点按钮用例表里一条命令都不新增。原因最常见的是录制开关只开了面板、没绑定到目标标签页——录制器只对当前激活的那个标签页生效切到新开的标签页后需要重新点一次录制。其次是页面主体在 iframe 里或者用了 Shadow DOM录制器在外层文档上监听事件进不到内层。第三是另一个同类录制扩展在抢事件。解决确认录制器绑定的是你要操作的那个标签页iframe 场景下先录一个切换框架的命令再录内层操作Shadow DOM 里的元素基本录不到直接手工在表格里补一条 CSS 定位的命令更快最后禁用其它同类扩展再试。5.4 回放报元素不可交互或直接超时现象回放到某一步红掉报元素不可交互、元素找不到、点击被拦截之类。原因定位表达式命中了隐藏元素。响应式页面为了适配不同屏幕会同时渲染桌面版和移动版的节点同名元素有两个一个display:none。按位置生成的 XPath 尤其容易命中隐藏节点。还有一种情况是元素在视口外点击前需要滚动。解决把定位器从位置 XPath 改成稳定的 id 或 CSS去掉名称重复的节点在点击命令前插一条滚动到元素的命令确认等待命令加在了正确的位置。这三步能解决九成以上的回放失败。5.5 导出的 Python 脚本本机跑不起来现象导出的脚本在录制器里能跑脱离录制器执行报驱动版本不匹配、会话创建失败或者提示某个方法不存在。原因驱动主版本和浏览器主版本不一致虚拟环境里装的是旧版 seleniumAPI 名字对不上导出脚本里硬编码了本机路径。解决把 selenium 升到 4.x 系列新版本自带驱动管理不用手工下驱动确实要手工管驱动的用 2.1 里那条chromedriver --version跟浏览器主版本逐位对齐主版本号导出脚本里的绝对路径改成相对路径或环境变量。这五条里前三条属于「装」的阶段后两条属于「用」的阶段。新手最容易在第一条上卡住熟手更容易栽在第五条——本地环境早就配好了换台机器就崩。把这几条抄进部署文档比事后靠回忆强。6. 装完验证一条用例走完录制、回放和脚本独立执行装完不代表能用。我的验收标准是四个动作全绿缺一个都不算装完。验证项通过标准失败先看哪录制能录下输入、点击、断言三类命令录制开关是否绑定当前标签页回放同一份用例连续跑三遍全绿定位器是否命中了隐藏节点导出目标格式文件生成且能被 IDE 打开导出格式与目标工程是否匹配独立执行脱离录制器用命令行跑通驱动版本、selenium 版本、路径第三第四项很多人直接跳过结果交付给流水线时才发现导出的脚本根本跑不起来。独立执行这一步给个最小可复现的做法# 脱离录制器验证用隔离环境 无头模式跑一遍导出的用例 python3 -m venv .venv source .venv/bin/activate pip install selenium4.11 pytest # 无头模式下跑能过说明不依赖图形界面可以直接进流水线 pytest -q tests/test_login.py --tbshort虚拟环境是为了把依赖钉在当前项目里避免污染系统 Python。selenium4.11这个下限是必须要的4.6 之后自带驱动管理选中版本时不用再手工对齐驱动。--tbshort缩短失败堆栈排错时先看最后几行就够了。无头模式一定要试很多脚本在带界面的浏览器里跑得好好的一进构建机就挂原因通常是无头模式下窗口尺寸不同触发了响应式布局切换到移动版节点之前录制的定位器全落空。真遇到了在启动参数里固定一个窗口尺寸就能绕过去。还有一个容易被忽略的验证点把导出的用例连续跑三遍三遍全绿才算通过。只跑一遍的通过是偶然跑三遍才说明等待策略是真的有效而不是刚好那次网络快。我第一次部署时就是只跑了一遍看着全绿就交付了第二天流水线上一半用例红掉回头查发现全是等待没加够页面渲染慢一点就崩。从那以后我每次装完 Katalon Recorder都会强制走一遍「录一条 → 回放三遍 → 导一条 → 无头跑一条」这个闭环四个动作任何一个红都不算装完。这套流程走下来大概二十分钟比起事后在流水线上排查几十条飘忽不定的失败用例这二十分钟花得值。希望帮到你。本文还有配套的精品资源点击获取