1. 项目概述与核心需求解析1.1 LuckyFrameClient 是什么LuckyFrameClient 是 LuckyFrame 开源自动化测试平台中的客户端执行引擎。很多刚接触这个平台的人会把它理解成一个“测试工具”但实际上它的定位更准确地说是一个任务执行器——你通过 LuckyFrameWeb 服务端编排测试计划、维护用例和业务关键字而真正把自动化脚本拉起来跑、把用例执行完、把日志和结果回传给服务端的是部署在测试环境里的 LuckyFrameClient。我最早接触它是在团队需要统一管理多个项目的接口自动化用例时。当时对比过 Jenkins 加自研脚本的方案也看过 RobotFramework 那一套但选 LuckyFrame 的原因很简单它把用例管理、任务调度、客户端执行、报告展示都整合在一个平台里而 Client 就是连接调度端和执行环境的“最后一公里”。你把它装在一台能访问被测系统的机器上它就会按计划去执行任务跑完把报告推到服务端。1.2 这个组件解决什么问题自动化测试落到实际工程里最头疼的往往不是写脚本而是三件事多项目多环境怎么统一调度A 项目在测试环境跑B 项目在预发环境跑C 项目可能还要连不同的数据库一套执行环境很难通吃。脚本和用例怎么管理散落在各人本地的脚本版本混乱、谁来更新都不知道。执行结果怎么沉淀跑完就完事没有历史记录没有趋势分析回归测试到底有没有效果说不清楚。LuckyFrameClient 解决的就是第一个和第三个问题的落地部分。它允许你在不同的机器上部署多个客户端每个客户端配置不同的执行环境数据库连接、被测系统地址等由服务端统一调度。执行完成后客户端会把日志、截图、断言结果全部回传形成一个可追溯的执行记录。换句话说它是自动化平台的“手和脚”——平台负责思考用例设计、计划编排Client 负责干活。1.3 适合谁来读这篇手册如果你属于下面几类人这篇手册的内容会比较对口测试开发工程师正要给团队搭建自动化测试平台需要了解客户端如何部署和接入。已经在用 LuckyFrame 服务端但客户端一直配置不顺畅、任务跑不起来的人。想在本地快速跑通一个客户端实例验证平台能力的技术负责人。我不会把 LuckyFrameWeb 服务端的所有功能都讲一遍那属于平台使用范畴。本手册核心是Client 端的部署、配置、接入、执行、排障所有内容都以我实际踩过坑之后留下的可复现方案为准。2. 环境准备与部署核心细解2.1 部署前先搞清楚 Client 的外部行为在动手安装之前有必要先建立一个整体认识LuckyFrameClient 不是一个独立运行的测试程序它天生就是在“被服务端调用”的场景下设计的。客户端通过与服务端的 WebSocket 长连接保持在线状态服务端下发任务时客户端接收任务指令加载对应的测试用例执行完毕后把结果推回服务端。这个设计带来的实际影响是客户端必须能连通服务端。不光是 HTTP 端口WebSocket 端口也要放通。很多人部署完发现客户端一直离线十有八九是 WebSocket 端口没通。客户端的系统时间要准。任务调度依赖时间判断如果客户端机器时间与服务端偏差太大会出现“任务已到执行时间但客户端不动作”的现象。执行机的资源不要太小。客户端本身很轻但跑 Web UI 自动化时要拉起浏览器跑接口自动化时要发请求执行机的 CPU 和内存太差会拖慢整个任务。2.2 安装包与版本匹配LuckyFrame 的服务端和客户端版本要保持大版本一致。早期我犯过一个错误服务端是 2.x客户端却用了 1.x 的包结果 WebSocket 连接一直握手失败日志里报一堆类加载异常。后来养成了一个习惯每次部署都到官方发行页面同时下载对应版本的 Server 包和 Client 包绝不混用。客户端本身是一个典型的 Spring Boot 应用打成一个可执行 JAR 包。你可以把它部署在 Linux 服务器、Windows 服务器甚至一台普通的 PC 上。Windows 上跑 Web UI 自动化比较方便因为浏览器环境直观调试时看得见。生产环境中建议用 Windows Server 单独跑 UI 任务接口任务则可以放 Linux。2.3 客户端目录结构认识将 JAR 包放好之后第一次启动前需要手动创建或确认以下几个关键位置LuckyFrameClient/ ├── LuckyFrameClient.jar # 客户端主程序 ├── application.yml # 核心配置文件 ├── logs/ # 客户端自身日志 ├── download/ # 测试过程中下载的文件归档 └── screenshot/ # UI 自动化失败截图一个比较容易忽略的点是客户端执行用例时产生的临时文件比如导入的测试数据、下载的附件都会落在安装目录下所以安装路径尽量不要用带空格或中文的目录。我之前在一台 Windows 机器上装到C:\Program Files下结果某些命令执行时因路径空格导致文件找不到排查了很长时间。后来统一改到D:\AutoTest\LuckyFrameClient这类纯英文路径问题消失。在 Linux 上部署时要确保运行客户端的系统用户对安装目录有读写权限。曾经因为使用root部署后切换到普通用户启动导致日志目录无法创建客户端启动后没有日志输出排查起来非常痛苦。3. 核心配置文件逐项解析3.1 application.yml 里的关键配置项LuckyFrameClient 的配置集中在application.yml中。第一次打开这个文件时里面配置项看起来不少但真正决定客户端能不能连上服务端的就是以下这几项server: port: 8081 client: name: my-client-01 updateServerUrl: http://192.168.1.100:8080/LuckyFrameWeb wsServerUrl: ws://192.168.1.100:8080/LuckyFrameWeb/websocket token: your-token-here autoRegister: true各字段的含义与注意事项如下配置项作用注意事项server.port客户端本地暴露的端口一般不需要对外保持默认即可client.name客户端在服务端显示的名称建议用环境-用途-序号的命名方式如test-api-01updateServerUrl服务端的 HTTP 地址用于拉取用例包、上传执行记录wsServerUrl服务端 WebSocket 地址用于维持长连接、接收实时任务指令client.token客户端接入凭证必须在服务端注册后生成的 token不能乱填client.autoRegister是否自动注册客户端首次部署建议开启之后可关闭3.2 服务端地址与 Websocket 路径的坑updateServerUrl相对好配置就是服务端的访问地址。但wsServerUrl的路径很多人容易写错。它不是简单地把 HTTP 改成 WebSocket 就行后面一定要带上webSocket这个上下文路径这是 LuckyFrame 服务端约定的 WebSocket Endpoint。我第一次接的时候没注意直接写了ws://192.168.1.100:8080/LuckyFrameWeb结果客户端日志不停提示连接失败我还以为是防火墙没开。后来仔细看源码才发现服务端的WebSocketConfig里注册的 Endpoint 是/webSocket结尾。所以这个路径必须补全。另外如果服务端是 HTTPS 部署的那么HTTP 地址要用https://开头WebSocket 地址要用wss://开头这块要注意因为很多人只把第一处改了第二处忘了结果 WebSocket 握手时因为协议不一致被服务端拒绝。3.3 Token 的获取与权限范围Token 是客户端与服务端通信的凭证不是随便填一个字符串就能用的。你需要在 LuckyFrameWeb 后端管理界面中进入客户端管理或系统管理相关菜单新增一个客户端记录然后系统会生成对应的 token。这个 token 的权限范围实际上对应着该客户端能够拉取哪些测试计划、执行哪些用例集。所以不同用途的客户端最好申请不同的 token不要全部共用一个。比如API 测试客户端只跑接口用例UI 自动化客户端只跑浏览器用例预发环境专用客户端只跑预发环境的用例我之前在一个项目里偷懒让所有客户端共用同一个 token后面发现任务分发时服务端根本没法灵活控制——给 A 客户端下发的任务B 客户端也能拉到。虽然影响不大但如果你有严格的权限隔离需求一客户端一 token 是必须的。3.4 日志级别与执行参数调整在配置文件中还可以调整客户端自身的日志级别logging: level: root: INFO com.luckyframe: DEBUG日常使用中我会将root保持为INFO只把com.luckyframe调成DEBUG这样出现问题时能拿到比较详细的内部执行日志又不至于被无关日志淹没。客户端执行接口测试时如果涉及大量数据驱动建议适当调大 JVM 的堆内存。在启动命令中直接指定java -Xms512m -Xmx1024m -jar LuckyFrameClient.jar实测跑 500 条以上数据驱动用例时256MB 默认堆会有较大概率触发 Full GC 导致执行变慢调大到 1GB 后明显改善。4. 部署流程与启动实操4.1 第一次启动前的检查清单在正式启动前我每次都会按下面的顺序检查一遍可以省掉后面不少麻烦服务端已启动且能通过浏览器正常访问。客户端机器ping服务端 IP 能通。客户端机器telnet 服务端IP 服务端端口能通确认 HTTP 端口放行。客户端机器telnet 服务端IP WebSocket端口能通确认 WebSocket 端口放行。客户端安装目录是纯英文路径且有读写权限。application.yml中服务端地址和 token 已正确填写。这个检查清单看起来基础但能覆盖 80% 的“客户端起不来”问题。很多时候不是配置写错了而是环境不通、日志没看全。4.2 Windows 环境部署步骤Windows 下部署的关键就一句话确保有 JDK 环境然后用命令行启动看日志。推荐先装 JDK 8 或 JDK 11LuckyFrameClient 2.x 版本基于 JDK 8 开发高版本 JDK 可能存在兼容问题。安装后配置好JAVA_HOME环境变量在命令行验证java -version接下来进入客户端目录执行java -jar LuckyFrameClient.jar建议第一次启动不要用后台方式运行直接在前台启动这样可以看到完整的控制台日志。如果启动成功会出现 Spring Boot 的启动横幅并出现类似WebSocket connected的日志说明已接入服务端。确认没问题后再改用后台运行方式。后台运行时Windows 下可以用start /b java -jar LuckyFrameClient.jar但这种方式关闭命令行窗口时客户端也会退出。建议用javaw或者做成 Windows 服务javaw -jar LuckyFrameClient.jar也可以用WinSW这类工具把 JAR 注册成 Windows 服务实现开机自启。这个细节在生产环境很重要——测试执行机如果重启了客户端不能自动恢复测试计划就会漏跑。4.3 Linux 环境部署步骤Linux 下的部署更加简单但要留意进程守护的问题。我的标准做法是# 1. 创建专有用户 useradd luckyframe # 2. 创建目录并赋予权限 mkdir -p /opt/luckyframe-client chown -R luckyframe:luckyframe /opt/luckyframe-client # 3. 上传 jar 包和配置文件 # 4. 使用 nohup 启动 cd /opt/luckyframe-client nohup java -Xms256m -Xmx512m -jar LuckyFrameClient.jar logs/console.log 21 启动后检查日志tail -f logs/console.log如果看到WebSocket connected to server这类关键字说明连接成功。为了让它开机自启我通常写一个 systemd 服务文件[Unit] DescriptionLuckyFrameClient Afternetwork.target [Service] Typesimple Userluckyframe WorkingDirectory/opt/luckyframe-client ExecStart/usr/bin/java -Xms256m -Xmx512m -jar /opt/luckyframe-client/LuckyFrameClient.jar Restarton-failure RestartSec10 [Install] WantedBymulti-user.target然后执行systemctl daemon-reload systemctl enable luckyframe-client systemctl start luckyframe-client。用 systemd 托管的好处是进程挂了能自动拉起省心。4.4 验证客户端是否接入成功客户端启动后不急着去看日志输出最直接的确认方式有两个服务端界面查看客户端状态进入 LuckyFrameWeb 的客户端管理页面如果列表中出现你配置的client.name且状态为在线说明接入成功。客户端日志确认日志中出现send heartbeat或heartbeat相关字样说明客户端正在与服务端保持心跳。如果客户端状态一直显示离线先看客户端日志中有没有报错信息。常见的是连接超时、token 错误、路径错误。这三类问题的排查方法后面在常见问题章节详细展开。5. 在客户端上执行自动化任务的完整流程5.1 客户端如何接收并执行测试计划当你在 LuckyFrameWeb 上创建了一个测试计划并指定了执行客户端后计划到时间触发时服务端会通过 WebSocket 下发任务给对应客户端。客户端收到任务后执行流程大体如下解析任务ID向服务端请求该任务关联的用例集。下载或同步最新的测试用例脚本如果配置了Git远程仓库客户端会拉取最新代码。按照用例顺序逐条执行调用对应的业务关键字。执行过程中的日志、断言结果、截图实时回传给服务端。所有用例执行完毕客户端汇总结果向服务端上报本次任务的状态。这个过程的关键点在于客户端执行的是服务端下发的用例而不是它本地的代码。所以你更新用例后不需要去客户端机器上做任何操作只要服务端用例变了客户端下次执行时拉到的就是最新版本。这正好解决了脚本分发的大难题。5.2 接口自动化用例的握执细节在接口自动化场景下LuckyFrameClient 的优势在于它并不强制自己发 HTTP 请求而是支持 HTTP、HTTPS、WebService、Dubbo 等多种协议。常用的 HTTP 接口用例需要在用例中配置请求方式、URL、请求头、请求体、断言内容。实际执行时客户端会为每个用例生成一份独立的执行上下文。这意味着不同用例之间的变量默认是不共享的。如果你想让上一个接口返回的 token 传给下一个接口使用需要用平台提供的“参数关联”功能——例如在第一个用例中提取响应体里的某个字段值存入全局变量然后在第二个用例中通过${变量名}来引用。用得多了之后我总结出一个经验接口用例一定要养成写断言的习惯断言的粒度宁细勿粗。不要只断言 HTTP 200要断言业务状态码、核心字段值。比如创建一个用户后断言创建接口返回的code 0再用这个用户ID去查询一次断言能查到数据。这样执行通过才说明业务链条真的通了。5.3 Web UI 自动化用例在客户端上的运行LuckyFrameClient 跑 Web UI 自动化时依赖 Selenium 相关组件。在 Windows 执行机上跑 UI 用例需要安装对应的浏览器驱动比如 Chrome 需要chromedriver.exe且驱动版本要和浏览器大版本一致。一个常见的坑是浏览器自动更新到了新版本驱动没更新结果脚本一运行就报session not created或unknown error: cannot find Chrome binary。解决方案有两个任选其一关闭浏览器的自动更新锁定版本驱动与版本严格匹配。每次浏览器更新后同步更新驱动。我推荐前者因为测试执行机的浏览器没必要频繁更新稳定压倒一切。另外跑 UI 用例的执行机不能锁屏、不能休眠。Windows 在锁屏状态下Selenium 虽然能执行但某些点击和下拉操作会偶发失败。早期我们在 CI 机器上跑 UI 回归经常莫名其妙失败后来发现是 Windows 自动锁屏导致的。把电源策略改成“从不休眠”“从不锁屏”后成功率大幅提升。5.4 数据驱动与多环境切换的经验LuckyFrame 平台本身支持测试数据的参数化。在用例中可以使用数据池来维护测试数据比如一组账号密码、一组商品 ID。执行时客户端会逐行读取数据每行数据执行一遍用例。我经常用这个特性来做批量数据验证比如 100 个订单号逐一查询状态。不过有一点要提醒数据量大的时候要充分评估执行时间。客户端是串行执行用例的一个 5 秒的接口用例跑 1000 行数据就是 5000 秒将近一个半小时。所以大数据量场景要做好任务拆分或者调整服务端的并发策略避免单个客户端长时间被占用。多环境切换方面要么为每个环境单独部署一个客户端在客户端上配置对应的服务地址要么把环境配置抽成变量在计划执行时动态指定。第一种方案更稳定我用得最多。6. 常见问题与排查技巧实录6.1 客户端一直显示离线这是接入阶段最常遇到的问题。排查顺序固定为看客户端日志是否有 WebSocket 连接报错。如果报Connection refused或者connect timed out请优先检查服务端地址是否能通。在客户端机器上执行telnet 服务端IP 8080如果端口不通就是网络或防火墙问题。确认wsServerUrl路径是否正确。路径必须是/LuckyFrameWeb/webSocket结尾少了这一段就会连接失败。确认 token 是否有效。如果服务端界面中客户端状态是“离线”且日志中提示认证失败去重新生成一个 token换掉旧 token。从我接触过的案例来看九成以上的离线问题都出在 WebSocket 端口不通和 token 配错这两类原因上。6.2 客户端偶尔掉线日志中出现重连记录客户端正常情况下是会一直保持 WebSocket 连接的。如果日志中出现周期性断开再重连常见原因有两个网络不稳定客户端与服务端之间有丢包或超时WebSocket 连接被中断。这种需要在网络层面解决比如检查是否有防火墙策略导致长连接空闲时被回收。服务端重启服务端重启后旧的 WebSocket 连接会失效客户端虽然会自动重连但重连周期内任务可能无法下发。如果掉线频率不高比如一天一两次且服务端重启后能自动重连影响不大。如果频繁掉线建议检查客户端与服务端所在机器之间的 TCP 长连接设置必要时在中间网络设备的会话保持策略中放行。6.3 UI 用例执行时浏览器报错浏览器相关报错最典型的是以下几类报错信息原因解决方法SessionNotCreatedException浏览器驱动与浏览器版本不匹配下载匹配版本的驱动Cannot find Chrome binary找不到浏览器可执行文件系统环境变量中配置浏览器安装路径ElementClickInterceptedException元素被遮挡无法点击改为 JS 点击或先滚动到元素可见区域TimeoutException元素加载超时调整隐式等待/显式等待时长这里我给一个很实用的建议如果 UI 用例执行中报错第一步务必先把失败截图找出来看看。LuckyFrameClient 在用例失败时会自动截图这些截图回传到服务端后可以在任务执行记录里查看。从截图能直接看出是元素没加载出来、弹窗遮挡还是页面跳转不对。很多时候不需要看日志截图比日志更直观。6.4 任务执行成功但用例结果全部“未执行”这个问题的典型表现是任务已经跑完了状态是成功但点开详情所有用例都是“未执行”或“跳过”。出现这种问题多半是测试计划中关联的用例集没有实际绑定用例或者绑定的用例被停用了。客户端拿到任务后发现没有可执行的用例就直接结束了。处理方式很简单去测试计划里确认关联的用例集配置看看用例集内是否选择了具体的用例用例状态是否处于启用。还有一种情况就是计划绑定了错误的环境。比如计划指定了只能在 Windows 客户端执行但你用的执行机是 Linux客户端判断环境不匹配后跳过。这种要在计划中正确配置执行环境。6.5 执行结果中的日志链路怎么看LuckyFrameClient 在执行用例时会在客户端本地 logs 目录下留下完整的执行记录同时回传给服务端。当你需要排查问题时善用日志链路非常高效服务端任务记录先看服务端中该次任务的执行状态、总用例数、通过数、失败数。服务端用例日志点开失败用例查看平台记录的断言失败原因这一步基本能定位 90% 的问题。客户端本地日志如果平台记录不够详细再到客户端机器的日志目录中按任务ID或时间点过滤日志看 JVM 层面是否有报错。这样的排查顺序不会让你一上来就陷入海量日志中能快速缩小范围。6.6 常见问题速查总表我把平时运维 LuckyFrameClient 过程中遇到频率最高的十几个问题汇总成了一张速查表供你直接对照排障症状可能原因排查方向客户端启动后立即退出端口被占用/JDK版本不兼容换端口确认JDK版本客户端在线但任务不执行计划时间未到/客户端未绑定计划检查计划配置接口用例全部超时被测系统网络不通客户端机器直接curl被测接口UI用例启动浏览器太慢执行机配置低/浏览器插件多清理浏览器插件升级执行机数据驱动用例执行极慢JVM堆内存不足调大-Xmx上传的报告不显示截图磁盘权限不足检查报告目录的写入权限日志中文乱码Windows编码导致启动时加-Dfile.encodingutf-8执行机重启后客户端失联未配置开机自启使用 systemd 或 WinSW 托管这张表不是排障的终点但它能帮你快速确定大概方向少走弯路。6.7 独家避坑技巧最后分享几个写进团队手册里的实战技巧都是踩过坑换来的经验。定时检查客户端心跳。LuckyFrameClient 在线状态很关键但如果你没有配置告警就不会知道它什么时候掉线了。我一般会在服务端写一个定时任务每天检查客户端列表如果有离线客户端就推送消息到群。宁可被误报打扰也不能让执行机静默失联。保持客户端安装目录简洁。客户端运行过程中会产生日志、截图、下载文件时间久了目录会变得很乱。我建议对logs/和screenshot/目录做定期清理比如每天凌晨清理 7 天前的文件。这个清理不影响任何历史记录因为截图和日志都会回传服务端。升级前先备份配置。无论升级 Client 还是 Server都要先备份application.yml和数据库。不要觉得“只是小版本升级应该没事”自动化平台的版本兼容问题往往隐藏很深一次大版本升级可能导致旧客户端无法接入。备份配置能让你在升级失败后秒级回滚不至于影响测试进度。7. 从接入到稳定的实操总结7.1 一套稳妥的接入节奏如果你是从零开始部署 LuckyFrameClient我建议你别急于一次把几十台机器全部接进来。更稳妥的节奏是先在一台机器上手动部署前台启动确认日志和在线状态跑通一个最简单的接口用例。确认没问题后再配置开机自启模拟一次机器重启验证客户端能自动恢复。接入第二个不同类型的客户端比如一台专跑 UI 用例的 Windows 机器验证 UI 用例能正常执行并能回传截图。将接入过程固化成文档/脚本之后批量部署時直接复制避免每台机器都手工操作。这种从小到大的接入方式能在早期就把环境问题暴露出来不会在批量部署后才发现某个共性问题导致全线瘫痪。7.2 客户端日常运维的核心建议客户端上线之后日常运维的重点其实不是“跑用例”而是“保证它能稳定地跑用例”。我最深的体会是要把客户端当成一个有生命周期的服务来对待而不是一个“启动后就忘掉”的测试工具。分享几条核心建议日志是第一手资料。无论是启动失败、任务失败还是连接不稳定客户端本地日志永远是最详细的。不要嫌日志多养成tail -f logs/console.log的习惯客户端状态你心里就有底。配置变更要做好记录。application.yml的一次改动可能影响所有任务的执行行为。我强烈建议把配置文件的变更历史记录下来哪怕只是加了一个日志级别的调整。否则几个月后发现客户端行为异常你却想不起来改过什么配置排查成本会很高。版本升级要同步更新。服务端升级后客户端不一定要立即升级但一定要关注两者版本的兼容性说明。我在前面提到过版本混用会带来连接失败这类隐蔽问题。我的做法是升级前先在测试环境验证确认无兼容性问题后再分批升级生产环境的客户端。7.3 最后再分享一个小技巧实际使用中很多人不知道 LuckyFrameClient 可以同时部署多套实例指向同一个服务端各自承担不同角色的任务。比如你可以在同一台 Windows 机器上部署两个客户端目录一个专门跑接口测试一个专门跑 UI 测试两个实例使用不同的client.name和 token。这样即使一个实例因为任务繁重卡住了另一个实例仍然可以正常接收任务互不影响。要注意的是两个实例监听的本地端口不能相同。启动第二个实例时需要修改server.port的配置同时注意两个实例的工作目录最好分开避免日志和临时文件互相干扰。我在团队内部一直强调一个观点自动化测试平台的价值不在于它有多少炫酷的功能而在于它能不能稳定可靠地替你执行那些重复的工作。LuckyFrameClient 作为执行端的载体部署得稳、配置得对、排障得快整个平台的可靠性才真正落地。希望这篇围绕客户端的实操手册能帮你少踩一些我当年踩过的坑把更多精力放到用例设计本身去。