Metadata-Version: 2.4
Name: seliky
Version: 26.10.2
Summary: a better ui autotest lib, compatible with robot framework
Home-page: https://gitee.com/teark/seliky.git
Author: TEARK
Author-email: 913355434@qq.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lxml
Requires-Dist: requests
Requires-Dist: websocket-client
Requires-Dist: tldextract>=3.4.4
Requires-Dist: psutil
Requires-Dist: websockets>=12.0
Requires-Dist: pywin32; platform_system == "Windows"
Provides-Extra: report
Requires-Dist: py; extra == "report"
Requires-Dist: pyecharts; extra == "report"
Requires-Dist: ansi2html; extra == "report"
Requires-Dist: Pillow; extra == "report"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

![img](seliky/core/seliky.jpg)

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

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

```bash
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 关键字库使用。

***

## 快速开始

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

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

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

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

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

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

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

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

```bash
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`：

```python
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()
```

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

```python
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，或直接开始录制、按你的测试路径正常操作页面，停止后得到一段中文脚本：

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

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

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

详见 [recorder 扩展文档](seliky/doc/recorder.md)。

**可能用到的场景**

- 元素定位不进去？用扩展点选，实时校验出更短、更稳的 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` 执行全部。
- **操作步骤**（必填）：中文指令，一行可写多步。
- **结果**、**截图**（可选）：执行后自动写回。

执行：

```bash
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 里定义可复用变量（列名以"自定义变量"开头，单元格写 `变量名=值`，用例里用 `${变量名}` 引用）：

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

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

完整说明、常见问题与更多指令见 [公共表格 + seliky 使用文档](seliky/doc/结合飞书用.md)。

***

## 自动报告：单文件 HTML

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

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

```python
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/doc/recorder.md)
- [公共表格 + seliky 使用文档](seliky/doc/结合飞书用.md)
- [如何写出高稳定性的 xpath](https://teark.github.io/UI-Automation-Tutorial/2.%E5%A6%82%E4%BD%95%E5%86%99%E5%87%BA%E9%AB%98%E7%A8%B3%E5%AE%9A%E6%80%A7%E7%9A%84xpath%EF%BC%9F/)

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