简介gauge-python 是 Gauge 自动化测试框架的 Python 语言运行器插件面向使用 Python 编写验收测试、行为驱动测试的开发者与测试工程师解决 Gauge 在 Python 环境下执行 specs 规范、解析步骤实现与调度测试用例的问题。资源包共 56 个文件以 34 个 py 源码文件为核心涵盖解析器、执行器、校验器、注册表、静态加载与重构等模块另含 6 个 md 文档、3 个 yml 配置、3 个 sh 脚本及 tmpl、properties、bat、json 等辅助文件压缩包约 70KB结构紧凑、模块划分清晰。已有 372 人学习下载。通过该运行器读者可掌握 gauge install python、gauge init python、gauge run specs 的完整链路了解插件从源码构建、依赖安装到测试覆盖的执行方式并借助内置测试用例与处理器实现理解 Gauge 与 Python 的集成机制适合需要搭建 Python 自动化测试体系或二次开发 Gauge 插件的技术人员参考。1. 当测试脚本开始“说人话”gauge-python 到底解决了什么如果你写过 Selenium 或 Playwright 的 Python 测试大概率经历过这种场面一个登录流程写了 80 行代码产品经理看了一眼说“这测的是什么业务”你只能指着driver.find_element(By.ID, submit-btn).click()一行行解释。gauge-python 就是冲着这个尴尬来的——它是 Gauge 测试框架的 Python 语言运行器让你用 Markdown 写业务步骤用 Python 写底层实现测试用例本身就是可读的规格说明。换句话说它把“测什么”和“怎么测”拆成了两层.spec文件负责描述业务行为.py文件负责驱动浏览器或接口。适合谁适合那些测试用例需要给非技术角色看、又不想放弃 Python 生态的团队。装完之后gauge run specs/一条命令就能跑完整个规格集报告直接生成 HTML。2. 环境搭建与第一个可运行规格从 pip install 到 gauge run2.1 安装 Gauge 核心与 Python 插件Gauge 本身是一个跨语言的测试运行器Python 支持是通过插件挂上去的。很多人第一次翻车就翻在这里只装了gauge-python的 pip 包没装 Gauge 二进制结果gauge命令根本不存在。正确的顺序是先装 Gauge 本体再装 Python 插件。在 macOS 上常用 HomebrewLinux 用 apt 或直接下载二进制Windows 用 scoop 或安装包。这里以最常见的两种方式为例# 方式一通过包管理器安装 Gauge 本体以 macOS 为例 brew install gauge # 方式二如果包管理器没有用官方脚本安装到用户目录 curl -SsL https://downloads.gauge.org/stable | sh # 验证 Gauge 本体是否可用 gauge --version # 输出类似Gauge version: 1.6.7Gauge 本体就位后安装 Python 运行器插件# 安装 gauge-python 插件这是 Gauge 与 Python 之间的桥接层 gauge install python # 查看已安装插件确认 python 插件状态为 Enabled gauge install --list这里有个参数细节gauge install python默认会拉取最新版插件但如果你项目里锁定了某个 Python 版本最好用gauge install python --version 0.3.15这种形式指定版本避免插件与 Gauge 本体版本不匹配导致gauge run时报Plugin connection error。装完之后gauge install --list里应该能看到python (0.3.x)且状态是 Enabled。2.2 初始化项目结构与 spec 文件写法Gauge 项目有固定的目录约定不要自己拍脑袋建目录。用gauge init python生成骨架是最稳的# 在当前目录初始化一个 Python 语言的 Gauge 项目 gauge init python # 生成后的目录结构大致如下 # ├── env/ # │ └── default/ # │ └── default.properties # 环境变量配置 # ├── specs/ # │ └── example.spec # 规格文件用 Markdown 写 # ├── tests/ # │ └── step_impl.py # 步骤实现用 Python 写 # └── manifest.json # 项目元信息specs/example.spec的内容长这样注意它的语法#是规格标题##是场景*是具体步骤。# 用户登录规格 ## 使用正确凭证登录 * 打开登录页面 * 输入用户名 testuser 和密码 Pass1234 * 点击登录按钮 * 验证页面标题包含 Dashboard对应的tests/step_impl.py里每个步骤用step装饰器绑定from getgauge.python import step, before_suite, after_suite from selenium import webdriver driver None before_suite def setup(): 整个测试套件开始前启动浏览器 global driver driver webdriver.Chrome() step(打开登录页面) def open_login_page(): 步骤实现导航到登录页 driver.get(http://localhost:8000/login) step(输入用户名 username 和密码 password) def enter_credentials(username, password): 步骤实现填入用户名和密码参数从 spec 文件传入 driver.find_element(id, username).send_keys(username) driver.find_element(id, password).send_keys(password) step(点击登录按钮) def click_login(): driver.find_element(id, login-btn).click() step(验证页面标题包含 expected_title) def verify_title(expected_title): 步骤实现断言页面标题包含预期文本 assert expected_title in driver.title, f期望标题包含 {expected_title}实际为 {driver.title} after_suite def teardown(): 套件结束后关闭浏览器避免进程残留 if driver: driver.quit()逻辑说明step装饰器里的字符串必须与.spec文件中的步骤文本完全一致包括标点。username这种尖括号是 Gauge 的参数占位符运行时会把 spec 里的实际值传给 Python 函数的对应位置参数。before_suite和after_suite是钩子分别在整个套件前后执行一次适合做浏览器启停。参数说明driver.get()的 URL 建议从env/default/default.properties里读而不是硬编码这样切换测试环境时不用改代码。2.3 运行与报告解读跑起来只需要一条命令# 运行 specs 目录下所有规格文件 gauge run specs/ # 只运行某个特定 spec gauge run specs/example.spec # 带标签过滤只跑 smoke 标签的场景 gauge run --tags smoke specs/运行结束后终端会输出每个场景的通过/失败状态。更实用的是 HTML 报告默认生成在reports/html-report/index.html直接用浏览器打开就能看到每个步骤的耗时和失败截图如果配置了截图钩子。如果某个步骤失败报告里会标红并显示断言错误信息比在终端里翻日志快得多。提示gauge run默认并行执行场景如果测试之间共享浏览器实例会互相干扰。可以在env/default/default.properties里设置gauge_parallel_executionfalse关掉并行或者确保每个场景独立启动浏览器。3. 步骤实现进阶参数化、数据驱动与钩子管理3.1 表格参数与动态数据驱动Gauge 最顺手的功能之一是表格参数。当步骤需要传入一组结构化数据时不用在 Python 里硬编码列表直接在 spec 里写 Markdown 表格## 批量验证用户角色 * 使用以下用户登录系统 |用户名 |密码 |预期角色 | |----------|----------|----------| |admin |Admin123 |管理员 | |editor |Edit456 |编辑 | |viewer |View789 |访客 | * 验证当前角色为 预期角色对应的 Python 实现里表格会以Table对象传入from getgauge.python import step from getgauge.python import data_store step(使用以下用户登录系统 table) def login_with_table(table): 表格参数table 是 getgauge.python.Table 对象 可以通过 table.rows 遍历每一行每行是一个列表 for row in table.rows: username row[0] password row[1] expected_role row[2] # 把预期角色存到 data_store供后续步骤断言使用 data_store.scenario[expected_role] expected_role # 这里调用实际的登录逻辑 perform_login(username, password) step(验证当前角色为 预期角色) def verify_role(expected_role): 从 data_store 读取之前存的预期值也可以直接用参数 actual_role get_current_user_role() assert actual_role expected_role, f角色不匹配期望 {expected_role}实际 {actual_role}逻辑说明table.rows返回的是二维列表第一行是表头从第二行开始是数据行。data_store.scenario是 Gauge 提供的场景级存储生命周期只在当前场景内适合在步骤之间传递中间状态。参数说明如果表格数据量很大建议把数据放到 CSV 文件里用step配合 Python 的csv模块读取而不是把几百行表格塞进 spec 文件那样 spec 会变得不可读。3.2 钩子函数与失败重试策略Gauge 的钩子体系比 pytest 更细除了before_suite/after_suite还有before_spec/after_spec、before_scenario/after_scenario、before_step/after_step。实际项目里最常用的是after_step做失败截图from getgauge.python import after_step from getgauge.python import ExecutionContext after_step def capture_on_failure(context: ExecutionContext): 每个步骤结束后检查是否失败失败则截图 context.current_execution_info 包含当前步骤的执行状态 if context.current_execution_info.get(is_failed): # 截图保存到 reports 目录文件名带时间戳避免覆盖 import time filename freports/failure_{int(time.time())}.png driver.save_screenshot(filename) print(f步骤失败截图已保存{filename})逻辑说明ExecutionContext是 Gauge 注入的上下文对象is_failed为 True 时说明当前步骤抛了异常。截图文件名用时间戳是为了避免并行执行时多个失败步骤互相覆盖。参数说明如果项目里用了 Allure 报告可以把截图路径附加到 Allure 附件里这样报告里能直接看到失败现场不用去翻文件目录。另一个常见需求是失败重试。Gauge 本身不提供重试机制但可以在after_scenario里判断失败后重新执行当前场景。不过更推荐的做法是把不稳定的步骤拆出来用gauge run --retry 2这种命令行参数部分版本支持或者在外层用 CI 的 retry 策略兜底。我一般会在env/default/default.properties里加一行gauge_retry_count1让 Gauge 在场景失败时自动重试一次但只对网络抖动类的失败有效断言失败重试多少次都没意义。3.3 环境配置与多环境切换Gauge 的环境配置放在env/目录下每个子目录是一个环境。默认用default切换环境用--env参数# 使用 staging 环境配置运行 gauge run --env staging specs/ # env/staging/staging.properties 内容示例 # base_urlhttp://staging.example.com # browserchrome # timeout30在 Python 代码里读取这些配置import os from getgauge.python import before_suite before_suite def setup(): 从环境变量读取配置Gauge 会把 properties 文件加载为环境变量 global base_url, browser base_url os.getenv(base_url, http://localhost:8000) browser os.getenv(browser, chrome) # 根据 browser 变量决定启动哪个 WebDriver if browser chrome: driver webdriver.Chrome() elif browser firefox: driver webdriver.Firefox()逻辑说明Gauge 在启动时会自动加载env/环境名/环境名.properties里的键值对到环境变量中Python 侧用os.getenv读取即可。参数说明base_url这种配置不要写死在代码里否则每次换环境都要改代码重新提交很容易漏改导致测试打到生产环境。我习惯在 CI 里用--env参数动态指定本地开发默认走default。4. 避坑与排查那些让我加班到凌晨的 Gauge 问题4.1 步骤匹配失败文本一模一样却报 “Step implementation not found”现象.spec文件里的步骤文本和step装饰器里的字符串看起来完全一样但运行时报Step implementation not found。原因最常见的是不可见字符差异。比如 spec 文件里从网页复制过来的步骤文本带了不换行空格U00A0而 Python 代码里是普通空格U0020。另一个原因是参数占位符不匹配spec 里写的是username代码里写的是user_name下划线和没有下划线在 Gauge 里是两个不同的参数名。解决用gauge run --verbose查看详细的步骤匹配日志它会打印出实际解析到的步骤文本和尝试匹配的装饰器列表。如果怀疑不可见字符用cat -A specs/example.spec查看文件里的空格和换行符。参数名统一用下划线或驼峰不要混用。4.2 并行执行时浏览器实例冲突现象本地跑单个 spec 没问题一跑全量就随机失败报Session not created或Element not found。原因Gauge 默认并行执行场景多个场景共享了同一个全局driver变量导致一个场景在操作浏览器时另一个场景把浏览器关掉了。解决把driver改成场景级变量在before_scenario里启动、after_scenario里关闭。或者直接在env/default/default.properties里加gauge_parallel_executionfalse关掉并行。如果确实需要并行提速用data_store.scenario存 driver 而不是全局变量每个场景独立管理自己的浏览器实例。4.3 报告里看不到失败截图现象after_step钩子里写了截图逻辑但 HTML 报告里没有图片。原因Gauge 的 HTML 报告默认只嵌入文本和链接不会自动把截图文件嵌入报告。截图文件虽然生成了但报告里没有引用它。解决在after_step里用gauge.screenshot或者把截图路径写入ExecutionContext的附件字段。更简单的做法是配置gauge_screenshot_on_failuretrue部分版本支持让 Gauge 自动处理截图和报告嵌入。如果版本不支持就在 CI 里把reports/目录整个打包上传手动查看截图文件。4.4 Python 虚拟环境与 Gauge 插件路径不一致现象在虚拟环境里pip install getgauge成功但gauge run时报ImportError: No module named getgauge。原因Gauge 启动 Python 进程时用的是系统 Python而不是你激活的虚拟环境里的 Python。插件本身不知道虚拟环境的存在。解决在env/default/default.properties里显式指定 Python 解释器路径python_path/path/to/venv/bin/python。或者在启动 Gauge 前先source venv/bin/activate确保which python指向虚拟环境。我一般会在项目根目录放一个run_tests.sh里面先激活虚拟环境再执行gauge run避免手动操作遗漏。4.5 表格参数里的空单元格导致索引越界现象spec 表格里某一行少填了一列Python 里row[2]直接抛IndexError。原因Gauge 解析表格时不会自动补齐空单元格如果某行只有两列而代码里访问第三列就会越界。解决在遍历table.rows时先检查len(row)或者用row[2] if len(row) 2 else 这种防御性写法。更好的做法是在 spec 里保证每行列数一致空值用-或N/A占位而不是留空。5. 让 Gauge 融入 CI标签过滤、报告归档与一个提速技巧标签过滤是 Gauge 在 CI 里最实用的功能。你可以在 spec 里给场景打标签然后按标签决定跑哪些## 冒烟测试首页加载 * 打开首页 * 验证页面标题包含 首页 ## 回归测试完整下单流程 * 登录系统 * 搜索商品 测试商品 * 加入购物车 * 提交订单在 CI 脚本里这样用# 只跑冒烟测试用于每次提交后的快速验证 gauge run --tags smoke specs/ # 跑全量但排除已知不稳定的场景 gauge run --tags !flaky specs/ # 同时指定多个标签与关系 gauge run --tags smoke login specs/标签语法支持与、|或、!非组合起来很灵活。我一般会在 CI 里分两个阶段提交触发时只跑smoke合并到主分支后跑全量。这样既保证了快速反馈又不会让每次提交都等十几分钟。报告归档方面Gauge 默认生成 HTML 报告到reports/html-report/但 CI 环境里这个目录是临时的。需要在流水线里加一步归档# 运行测试并指定报告输出目录 gauge run --dir specs/ --environment ci # 归档报告以 GitHub Actions 为例其他 CI 类似 # 在 workflow 里加 # - uses: actions/upload-artifactv3 # with: # name: gauge-report # path: reports/一个提速技巧Gauge 的--parallel参数可以指定并行节点数但前提是场景之间没有共享状态。如果你的测试大量依赖数据库且每个场景都会写数据并行反而会因为数据竞争导致随机失败。我一般会先跑一遍gauge run --parallel 4观察失败率如果失败率明显上升就降到--parallel 2或者关掉并行。另一个技巧是把耗时的登录操作封装成before_suite钩子只登录一次所有场景复用同一个会话但这样会牺牲场景独立性适合登录流程稳定的项目。从那以后我每次新建 Gauge 项目都会先在env/default/default.properties里把gauge_parallel_execution和python_path这两个配置写死再跑一个最小 spec 验证环境确认无误后才开始写业务步骤。这个习惯帮我省掉了至少三次“为什么本地能跑 CI 跑不了”的排查时间。希望帮到你。本文还有配套的精品资源点击获取