Sanmu

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

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

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

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

功能特点

1. 整体特点

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

2. API测试

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

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

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

安装

sanmu可以通过pip进行安装

pip install sanmu -U

使用

1. 查看帮助

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

>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中有多个 用例
• 每个用例中有多个 步骤
• 每个步骤中有说明、关键字、参数

示例：

4. 查看关键字

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

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

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

5. 执行用例

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

>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·子命令，启动框架开始执行用例

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

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

报告截图：

7. 结果通知

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

• 执行用例
• 生成报告

1. 企业微信

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

配置内容：

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

消息预览：

2. 钉钉

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

配置内容：

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

消息预览：

3. 飞书（todo）

敬请期待...

todo

4. Emal

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

配置内容:

; 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项来传递参数

[pytest]
addopts = -n 4

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

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

2. 自定义关键字（todo）

敬请期待...

todo

3. 断言表达式

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

基本格式

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

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

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

4. 配置文件

可配置项：

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

如果项目中未包含pytest.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 重构

• 接口数据解析

  • jsonpath
  • xpath
  • re

• 关键字使用新格式：A.B.C

联系作者

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

• WeiXin: python_sanmu