Metadata-Version: 2.1
Name: sanmu
Version: 0.6.0
Summary: 基于pytest实现低代码自动化测试框架，支持web测试、app测试、api测试。只需要编辑xlsx文件或yaml即可完成测试。
Author: dongfangtianyu
Requires-Python: <3.13,>=3.12
Requires-Dist: Pillow~=10.1.0
Requires-Dist: allure-pytest<2.14,>=2.13.5
Requires-Dist: click~=8.1.7
Requires-Dist: email-validator~=2.0
Requires-Dist: genson~=1.2.2
Requires-Dist: httpx~=0.25.0
Requires-Dist: iniconfig~=2.0.0
Requires-Dist: jsonpath~=0.82
Requires-Dist: jsonschema~=4.21.0
Requires-Dist: pydantic-settings~=2.0.2
Requires-Dist: pydantic<3.0,>=2.1.1
Requires-Dist: pyjwt[crypto]>=2.8.0
Requires-Dist: pymysql>=1.1.1
Requires-Dist: pytest-result-log~=1.2.1
Requires-Dist: pytest-yaml-sanmu==1.0.0
Requires-Dist: pytest~=8.2
Requires-Dist: responses-validator>=0.1.6
Requires-Dist: webdriver-helper
Project-URL: Homepage, https://github.com/dongfangtianyu/sanmu
Description-Content-Type: text/markdown

# Sanmu
 sanmu 是一个基于pytest全栈自动化测试框，仅需创建yaml文件或xlsx文件，即可完成：

-   [x] API 自动化测试
-   [x] Web 自动化测试
-   [x] App 自动化测试

借助Sanmu框架，不需要掌握编程语言，即可实现低代码用例生成、修改、执行、报告、通知等一些列自动化测试活动。



如果你了解python语言，可以灵活的进行自定义关键字和二次开发，极具扩展性。



## 功能特点



### 1. 整体特点

- [x] 仅以数据文件（如yaml、excel）描述用例，不需要任何代码
- [x] API自动化测试（基于**httpX**）
- [x] ~~Web自动化测试（基于**Playwright**，维护中，暂不可用）~~
- [x] ~~App自动化测试（基于**Appium**，维护中，暂不可用）~~
- [x] 支持pytest语法、参数、及其插件生态
- [x] 支持基于pytest.ini 的框架配置
- [x] 支持通过用例名称、目录、或标记，实现**用例筛选**
- [x] 变量类型：支持变量进行**类型转换**
- [x] 增加逻辑控制关键字：for、if 、else、sleep等
- [x] 调用python**自定义函数**
- [x] 支持docker run，开箱即用
- [x] 测试报告：基于Allure生成精美HTML测报告，内附接口报文、UI截图
- [x] 结果通知：测试执行完毕后，自动通知到相关人员，支持**Email、钉钉、企业微信等**



### 2. API测试

- [x] 用例：纯Yaml文件创建用例，**不需要编写任何代码**
- [x] 自动补全：一键生成yaml格式校验，对yaml内容格式检查和自动补全提示
- [x] 接口关联：支持jsonpath、re、xpath可以提取响应内容，完成**精确断言**或**关联至其他接口**
- [x] 参数化测试：支持参数化测试、数据驱动测试，测试用例完美兼容各种测试报告插件
- [x] 接口格式验证：接口测试时可断言响应的**字段名和字段值类型**
- [x] 自定义断言：支持指定Python函数作为自定义断言



### 3. UI测试（维护中，暂不可用）

- [x] 用例：纯Excel文件创建用例，**不需要编写任何代码**
- [x] 自动补全：一键生成关键字文档、用例模板，excel中自动补全关键字
- [x] 定位：内置可配置的等待策略+XPath智能补全功能，实现元素**智能定位**
- [x] 弹窗：**自动alert处理弹窗**，避免用例阻塞、定位失败等问题
- [x] 关键字驱动：内置常用关键字，实现**关键字驱动测试**，提供了接口可以**扩展自定义关键字**
- [x] 变量：使用`save`关键字**创建变量**，使用`${vars}`标签**使用变量**
- [x] 截图：元素交互时自动聚焦，交互后**自动截图**记录
- [x] 回放：生成动态，在测试报告中自动回放UI测试过程







## 安装

sanmu可以通过pip进行安装

```bash
pip install sanmu -U
```



## 使用

### 1. 查看帮助

在控制台输入 `sanmu --help` 后可以看到帮助信息

```bash
>sanmu --help 
Usage: sanmu [OPTIONS] COMMAND [ARGS]...           
                                                   
  sanmu 是一个基于pytest全栈自动化测试框，仅需创建yaml文件或xlsx文件，即可完成：

  ▣ API 自动化测试
  ▣ Web 自动化测试
  ▣ App 自动化测试

  可以完美兼容pytest生态及插件，自动记录接口报文、页面截图、框架允许过程，自动生成Html测试报告，
  并通过钉钉、企业微信、Email等渠道，发送测试框架的执行结果

Options:
  --help  Show this message and exit.             

Commands:
  report        调用allure，生成HTML报告
  run    		启动框架执行用例
  docs          查看关键字文档
  start         创建demo文件，并命名为 test_{name}.xlsx

```



### 2. 生成用例







### 3. 编辑用例

通过excel文件编写用例：

- 每个sheet视为一个TestSuite，
- 数据行，视为测试用例的“步骤”
- 如果步骤为“0”，视为一个新的用例

基本关系：

- 每个excel中有**多个 sheet**
- 每个sheet中有**多个 用例**
- 每个用例中有**多个 步骤**
- 每个步骤中有**说明、关键字、参数**

示例：

![基于Excel的测试用例](images/case_by_excel.jpg)



### 4. 查看关键字

可通过`docs`子命令查看内置关键字的说明和参数

```bash
>sanmu docs
关键字及其参数
====================
关键字：activity
        启动新会话 （适用于Appium）

        :param activity_name: Activity名
        :param package_name:  包名，默认为当前包
...

```



### 5. 执行用例

可通过`run`·子命令，启动框架开始执行用例

```bash
>sanmu run
========================== test session starts ==========================
platform win32 -- Python 3.10.1, pytest-6.2.5, py-1.11.0, pluggy-1.0.0
rootdir: D:\Users\Tianyu\PycharmProjects\UI_by_Excel, configfile: pytest.ini
plugins: allure-pytest-2.9.45, html-3.1.1, metadata-1.11.0, rerunfailures-10.2, sanmu-0.0.6
collected 2 items

test_电商项目.xlsx ..                                         [100%]           
========================== 2 passed in 15.22s ===========================
```



### 6. 生成报告

可通过`report`·子命令，启动框架开始执行用例

```bash
>sanmu report
执行命令:  allure generate ./.allure_results  -o report --clean
Report successfully generated to report
```

报告默认保存在当前路径下的`report`文件夹，也可通过配置文件文件进行修改，详见[配置](#配置)

报告截图：

![](images/report_by_allure.jpg)



### 7. 结果通知

框架在以下操作之后，会自动按照配置文件中的方式进行结果通知

-   执行用例
-   生成报告



#### 1. 企业微信

在配置文件中填写钉钉通知设置，在测试结束后会自动通知测试结果



配置内容：

```ini
[sanmu]
qywx_url = https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=2c253bf4-6412-4f0e-bc7e-5e0f3216bc24
```

消息预览：

![企业微信通知消息](images/msg_to_qywx.jpg)

#### 2. 钉钉

在配置文件中填写钉钉通知设置，在测试结束后会自动通知测试结果



配置内容：

```ini
[sanmu]
dingding_url = https://oapi.dingtalk.com/robot/send?access_token=3905a29983f849fc3c6e9728eb1996cfadfefe7e1cab511c506edd3ee89f5200
dingding_secret = SEC51f562f1c05967c13d40907fd495585132fa180af76fb6ef0a61f4f682cd87c2
```

消息预览：

![钉钉消息通知](images/msg_to_dingding.jpg)



#### 3. 飞书（todo）

敬请期待...

>   todo





#### 4. Emal

在配置文件中填写SMTP信息及收件人地址，在测试结束后会自动通知测试结果



配置内容:

```ini
; SMTP服务器
email_server = smtp.office365.com   
; SMTP端口
email_port = 587
; SMTP 加密方式 ，若无加密则删除本行
email_encryption = tls
; 发件账号地址
email_account = sender@tianyuongh.onmicrosoft.com
; 发件账号密码
email_password = Toq57763
; 收件账号地址
email_to = tianyu@tianyuongh.onmicrosoft.com
```





## 进阶话题



### 1. 并发执行

sanmu框架支持为excel用例进行并发执行测试，使用并发执行时，为sanmu 添加参数即可

```
sanmu -n 4
```

也可修改pytest.ini中的adopts项来传递参数

```ini
[pytest]
addopts = -n 4
```

其中`4 `为并发进程数， 如果改为`auto` 则根据CPU数量自动配置并发进程数

**注意：** 并发模式下，每个进程会创建单独的日志文件





### 2. 自定义关键字（todo）

敬请期待...

>   todo






### 3. 断言表达式

在测试用中使用断言关键字时，需要“断言表达式”进行配合，以准确的表达断言方式



基本格式

| 步骤ID | 步骤名称 | 关键字 | 参数     |            |          |
| ------ | -------- | ------ | -------- | ---------- | -------- |
| 9      | 断言     | assert | 预期结果 | 断言表达式 | 实际结果 |
|        |          |        |          |            |          |



断言表达式描述了**预期结果**和**实际结果**的比较方式，内置的表达式如下：

| 断言表达式 | 比较方式                                           |
| ---------- | -------------------------------------------------- |
| in         | 预期结果  **在**  实际结果中                       |
| contains   | 预期结果  **包含** 实际结果                        |
| equal      | 预期结果  **等于** 实际结果                        |
| re         | 预期结果是正则表达式，可以**匹配**实际结果         |
| scheme     | 预期结果和实际结果均是json字符串，**json格式一致** |




### 4. 配置文件

可配置项：

- [x] 日志等级
- [x] 日志路径
- [x] 聚焦颜色
- [x] 报告路径
- [x] 等待时长
- [x] 等待频率
- [x] 默认使用强制点击
- [x] Selenium Grid
- [x] 默认浏览器类型
- [x] 默认浏览器启动参数



如果项目中未包含`pytest.ini`，则框架会自动生成，其包含了各项配置的默认值

```ini
[pytest] # pytest原生设置
addopts =
	# allure结果目录
    --alluredir=./.allure_results
    # 执行前自动清空allure结果
    --clean-alluredir
    # 并发执行用例
    -n auto

log_cli = 0 
# 日志文件路径
log_file = pytest.txt
# 日志文件等级
log_file_level = info
# 日志文件格式
log_file_format = %(levelname)-8s %(asctime)s [%(name)s:%(lineno)s]  : %(message)s

[sanmu] # sanmu框架扩展设置

# Allure的绝对路径
allure_path = allure
# Allure报告的保存目录
allure_report = ./report
# allure生成报告后是否自动打开
allure_show = yes

# 是否记录步骤截图
screenshot_step = yes
# 是否记录错误截图
screenshot_error = yes
# 是否记录回放
screenshot_playback = yes

# 浏览器类型
driver_type= chrome
# 浏览器启动参数
driver_option = 
# grid 地址，留空则使用本地浏览器
selenium_grid = 

# 自动等待的检查频率（秒/次）
wait_poll = 0.1
# 自动等待的最大时长（秒）
wait_max = 5

# 元素聚焦时的CSS样式
touch_css = background: #71b95ea1; border: 2px solid red;

# 使用强制点击
force_clieck = no

# email配置
email_server =
email_from = 
email_password = 
email_to = 

# 企业微信
qywx_url =

# 钉钉
dingding_url =
dingding_secret =

```



## 二次开发



### 1. 开发流程

1. 设置环境变量：pypi_auth=xxxx;pypi_pass=yyyyy
2. 安装pdm: pip install pdm
3. 安装项目依赖： pdm update
4. 启动框架： sanmu   （或者python main.py）

### 2. 发布流程

1. 开发环境执行pytest，确保测试用例全部通过
2. 修改版本号，并创建新的commit和tag
3. push到github后，手动创建新的releases
4. releases会触发CI/CD，自动完成发布





## 后续开发计划

-   [ ] 支持飞书 
-   [ ] 使用jinja2 重构
-   [ ] 接口数据解析
    -   [x] jsonpath
    -   [ ] xpath
    -   [ ] re

-   [ ] 关键字使用新格式：`A.B.C`







## 联系作者

如果在使用过程中遇到什么问题，欢迎通过以下方式联系：

-   **WeiXin**:  python_sanmu

