seliky — 极简、稳定的 UI 自动化测试库

seliky 致力于做好 UI 自动化及爬虫中与页面交互的那部分逻辑。它自带一套基于 Chrome DevTools Protocol（CDP） 的内核，不需要下载 chromedriver，装完即可驱动本机 Chrome；在此之上再提供中文自然语言驱动、飞书表格用例管理、操作录制回放与单文件 HTML 报告。

pip install seliky

---

它由什么组成

组成	说明
seliky.core	自研 Chromium 内核（CDP 协议），免 driver 直接驱动本机 Chrome，提供 BrowserPage / BrowserElement 等底层能力
seliky.core.seliky_dri	构建在 core 之上的类 selenium 封装 WebDriver，get / click / send_keys 几个方法即可上手
recorder Chrome 扩展	点选页面拿稳定 XPath、把操作录成中文脚本；配合 bridge 引擎接管你当前已打开的浏览器
seliky.core.natural_langurage	规则（正则）解析的中文自然语言驱动，离线、免费、执行快
seliky.core.autoreport	单文件 HTML 测试报告（饼图 + 日志 + 失败截图）

---

核心特性

1. 免驱动，装完即用🔥🔥🔥🔥🔥
   • 基于自研 CDP 内核直接驱动本机 Chrome / Chromium，不需要下载、配置 chromedriver。
2. 极致简约，学习简单🔥🔥🔥🔥🔥
   • 大量复杂、冗余的操作被封装好，只需记住 get、click、send_keys、is_visible 等少数几个方法即可上手，无需了解底层协议，甚至可以用中文自然语言直接驱动。
3. 交互稳定🔥🔥🔥🔥🔥
   • 原生驱动的通病是"元素明明在页面上却找不到"。seliky 通过最大耗时的精确计算与多轮轮询解决了这一问题；click、send_keys 等核心方法均有多重保障机制（真实点击 → 鼠标事件 → JS 点击逐级回退）。
4. 统一 xpath 定位，也支持文字定位🔥🔥🔥🔥
   • 统一采用 xpath 这种万能定位，管理方便；seliky_dri 还支持直接复制元素上的文字来定位（如 page.click('Link Test')），程序会按 文本 → placeholder → data-placeholder 组合匹配。
5. 元素高亮🔥🔥🔥
   • 元素交互时默认高亮闪烁，方便执行时观察页面；无界面（headless）模式下自动关闭。
6. 无侵入式封装🔥🔥🔥
   • 封装不吞掉原生方法，WebDriver.driver 就是底层 BrowserPage，交互中随时可以调用内核原生能力。
7. 可接管已打开的浏览器🔥🔥🔥🔥
   • 一个 take_over_port（CLI 为 --port 9222）即可接管已登录的 Chrome，省去登录态维护；bridge 引擎则直接通过扩展接管当前标签页，连调试端口都不用开。
8. 抓包能力🔥🔥🔥
   • WebDriver(performance=True) 开启网络监听，network_get_response_body() 抓接口响应、network_get_event_stream() 抓 SSE 事件流，可以一边走 UI 一边取数。
9. 中文自然语言驱动🔥🔥🔥🔥
   • 用规则解析把一句中文变成一串浏览器操作，不调用大模型、无 token 费用、结果可复现，离线可用。
10. 飞书表格即用例🔥🔥🔥
    • 用例写在飞书电子表格里，seliky -l '<表格链接>' 一行命令读取执行，结果与截图自动写回表格。
11. 操作录制回放🔥🔥🔥
    • 配套 Chrome 扩展点选即得稳定 XPath，录制出来的中文脚本可以直接用 CLI 回放。
12. 自动报告 + Robot Framework🔥🔥
    • 自动从 xpath 提取关键词作为报告说明；autoreport 生成开箱即用的单文件 HTML 报告。ROBOT_LIBRARY_SCOPE = 'GLOBAL'，可直接作为 RF 关键字库使用。

---

快速开始

方式一：命令行 + 中文指令（最省事）

seliky -l '打开百度，在搜索框输入 seliky，按回车，等待 2 秒，验证出现 seliky'

默认使用 bridge 引擎：通过 recorder 扩展接管你当前已打开的浏览器（登录态、已打开的标签页都能直接用）。扩展随 pip install seliky 一起安装：

seliky --recorder-path      # 打印扩展所在目录

然后打开 Chrome → chrome://extensions/ → 开启「开发者模式」→「加载已解压的扩展程序」→ 选择上面输出的目录，并在扩展里开启桥接模式。

不想装扩展、希望 seliky 自己拉起浏览器时，用 seliky_dri 引擎：

seliky -l '打开百度，搜索 seliky，截图' --engine seliky_dri

接管已以调试端口启动的 Chrome：

seliky -l '点击我的学员' --engine seliky_dri --port 9222

常用命令行参数：

参数	说明
-l, --language	中文指令或飞书表格链接（必填）
--engine	驱动引擎：bridge（默认，走扩展）或 seliky_dri（自启浏览器）
--port 9222	接管已启用远程调试的 Chrome
--bridge-port 8765	桥接服务端口，默认 8765
-p, --priority	飞书表格优先级筛选，如 2,3-5；-p 0 执行全部（默认 1）
--dry-run	只显示飞书表格将执行的行，不启动浏览器、不回写
--report	在当前目录生成 report.html
--screenshot-on-error	某一步失败时额外截图留证
--no-final-screenshot	执行结束时不保存最终截图
--keep-screenshots	飞书表格执行后保留本地截图
--json	以 JSON 输出执行摘要
--recorder-path	打印 recorder 扩展目录

seliky --help 可查看全部选项；python -m seliky -l '...' 等价于 seliky -l '...'。

方式二：Python 调用（seliky_dri）

案例：访问百度，依次搜索 3 组关键词并校验结果。你只需记住几个关键方法：请求 get、点击 click、输入 send_keys、是否可见 is_visible：

from seliky import WebDriver        # 等价于 from seliky.core.seliky_dri import WebDriver

page = WebDriver()                  # 无需传 driver 路径
page.open_browser()
page.get("https://www.baidu.com")

for word in ["小张", "小李", "小刘"]:
    page.send_keys('//input[@id="kw"]', word)   # 输入值
    page.click('//input[@id="su"]')             # 点击搜索
    if page.is_visible('//img[@class="index-logo-src"]'):
        print('百度 logo 已正确加载')

page.quit()

也可以直接用元素上的文字定位：

page.get('https://sahitest.com/demo')
page.click('Link Test', bac_sleep=3)

WebDriver 的常用初始化参数：

参数	说明
display=False	无界面模式（同时自动关闭元素高亮）
logger=	传入日志对象（如 pytest-loguru），不传则 print
log_locator=True	日志中额外打印定位表达式
options=[...]	浏览器启动参数，如 '--start-maximized'
experimental_option	特殊设置项，如不加载图片、设置下载路径
use_user_path=True	使用本机用户数据目录（保留登录态）
take_over_port=9222	接管已用调试端口启动的 Chrome
performance=True	开启网络监听/抓包，配合 network_get_response_body()、network_get_event_stream()

常用方法（与其它主流封装库的公共 API 基本对齐）：

• 页面：get、current_url、title、page_source、refresh、back、forward、new_tab、switch_to_window、close、quit、save_screenshot、window_scroll、run_js
• 元素：find_element、find_elements、click、click_if_visible、js_click、double_click、right_click、hover、move_to_element、ac_click、offset_click、progress_click、drag_and_drop、drag_and_drop_by_offset
• 输入：send_keys（支持 enter=True）、clear、upload、upload_by_win32、enter、press、select_all、copy、cut、paste、backspace、delete、tab、space、esc
• 取值/状态：text、get_attribute、get_property、get_css_property、set_attribute、is_visible、is_displayed、is_selected、is_enable
• 弹窗/其它：switch_to_alert、dismiss_alert、stretch、maximize_window

方式三：录制成中文脚本再回放

用 recorder 扩展点选页面元素拿到最稳定的 XPath，或直接开始录制、按你的测试路径正常操作页面，停止后得到一段中文脚本：

打开https://example.com/,点击学员管理,点击我的学员,向下滚动1200像素,点击(//button[contains(.,'立即发布')])[last()]

扩展里开启桥接模式后，一行命令回放：

seliky -l "上面录制的整段语言"

详见 recorder 扩展文档。

可能用到的场景

• 元素定位不进去？用扩展点选，实时校验出更短、更稳的 XPath。
• 不想维护自动化工程？录制 → 回放，或者把脚本贴进飞书表格交给业务同学维护。

---

指令怎么写（自然语言）

因为背后是正则规则匹配（不是大模型），句式要按套路写。下面是常用写法，照着写就不会错：

场景	写法示例	说明
打开网页	打开 https://www.example.com、打开百度	也可用 访问/前往/进入/跳转到；内置别名：百度、必应、谷歌、淘宝、京东、知乎、微博、哔哩哔哩/b站、github
输入	在用户名输入框输入 admin、在搜索框输入 你好、在第2个输入框输入 你好	描述可用输入框旁边的文字、placeholder 或 id；+随机数 会替换为时间戳
点击	点击 登录、点击//*[@class="submit-btn"]、双击 文件名、右键点击 图片	也可用 单击/选择/勾选/取消勾选；非文字按钮直接写 xpath
搜索	搜索 seliky、用百度搜索 seliky	自动在搜索框输入并回车
等待	等待 3 秒、稍等	也可用 暂停/停留/休眠
按键	按回车、在搜索框按回车	支持 回车/Tab/Esc/空格/删除/退格
清空	清空 用户名、清空第2个输入框	清空输入框
上传	上传 D:\a.png 到 附件	文件上传
滚动	滚动到底部、向下滚动 500	支持 顶部/底部/上/下/左/右
条件	如果出现 弹窗 则点击 关闭、如果出现 广告 则等待 2 秒	元素存在才执行
验证	验证 登录成功、验证出现 登录成功	未出现则该行判定失败并停止后续步骤
浏览器	刷新页面、后退、前进、关闭标签页、退出浏览器	收尾与导航
截图	截图、保存截图到 D:\shots	页面截图
位置点击	点击提交按钮右侧10%的位置	以元素中心为原点按比例偏移点击

一句话也可以包含多个步骤，用中文逗号、句号、分号或换行分隔（不要用英文逗号，英文逗号可能出现在 xpath 里）。

元素找不到时的高级技巧：优先用页面上看得见的文字描述元素，seliky 会按 文本 → id → placeholder → 关联 label 等多种方式模糊匹配；实在定位不到的疑难元素，指令里可以直接写 xpath。

---

飞书表格即用例

准备一张飞书电子表格，第一行表头包含这几列（列名要一字不差）：

优先级	操作步骤	结果	截图
1	打开百度，搜索 seliky，截图	（执行完自动写入）	（执行完自动写入）
2	打开 https://www.bilibili.com，等待 2 秒	（执行完自动写入）	（执行完自动写入）

• 优先级（必填）：非负整数。默认只执行 1 的行，可用 -p 2,3-5 指定，-p 0 执行全部。
• 操作步骤（必填）：中文指令，一行可写多步。
• 结果、截图（可选）：执行后自动写回。

执行：

seliky -l 'https://xxx.feishu.cn/sheets/xxxxxx'          # 支持 /sheets/ 与 /wiki/ 链接
seliky -l 'https://xxx.feishu.cn/sheets/xxxxxx' -p 2,3-5
seliky -l 'https://xxx.feishu.cn/sheets/xxxxxx' --dry-run  # 预检将执行的行

还支持在名为 配置 的 Sheet 里定义可复用变量（列名以"自定义变量"开头，单元格写 变量名=值，用例里用 ${变量名} 引用）：

点击${提交按钮}
在${用户名输入框}输入张三

表格读写依赖本机已安装并配置好的 lark-cli（可用 lark-cli sheets +workbook-info --url <表格url> 验证）。

完整说明、常见问题与更多指令见 公共表格 + seliky 使用文档。

---

自动报告：单文件 HTML

使用报告前需安装可选依赖：pip install 'seliky[report]'。

autoreport.Reporter 执行用例并生成单文件 HTML 报告——通过/失败饼图、每步日志、失败自动截图，一个文件即可发出去：

from seliky.core.autoreport import Reporter

class TestDemo:
    def test_search(self):
        ...

Reporter(output="output/report.html", title="冒烟报告", executor="teark").run(TestDemo)

命令行方式加 --report，或在 NaturalLanguage(report=True) 时，执行完自然语言指令同样会生成报告。

---

模块一览

模块	说明	额外依赖
seliky.core	CDP 内核，免 driver 驱动 Chrome，提供 BrowserPage / BrowserElement 等底层能力	—
seliky.core.seliky_dri	类 selenium 的 WebDriver 封装，日常交互用这一层	—
seliky.core.natural_langurage	中文自然语言驱动，支持飞书表格用例	—
seliky.core.autoreport	单文件 HTML 测试报告	pip install 'seliky[report]'
seliky.core.bridge	与 recorder 扩展通信的本地 WebSocket 桥	—
seliky.recorder	Chrome 扩展：XPath 点选 + 操作录制	—

顶层导出：from seliky import WebDriver（seliky_dri 版）、get_driver、g_driver、recorder_path。

---

环境要求

• Python 3.10+
• Chrome / Chromium 系浏览器
• 平台：Windows / macOS（upload_by_win32 仅 Windows）
• 飞书表格模式额外需要本机 lark-cli

更多资料

• recorder 扩展文档
• 公共表格 + seliky 使用文档
• 如何写出高稳定性的 xpath

更多其它好用的特性，尽在 seliky，使用 pip install seliky 来体验吧…