hiptest/hiptest-publisher

HipTest Publisher

概述

HipTest Publisher（hiptest-publisher）是一个工具，用于从CucumberStudio（原HipTest）读取测试管理项目，并将其发布为可执行的测试脚本存根，以便开始自动化测试开发。

核心功能与特性

• 支持从CucumberStudio项目导出测试脚本，生成可执行的测试存根
• 兼容多种编程语言和测试框架（如Cucumber、JUnit、RSpec、Robot Framework等）
• 可从特定测试运行（test run）导出测试套件
• 生成动作词签名文件（actionwords_signature.yaml），用于处理动作词更新
• 支持将测试结果推送回CucumberStudio
• 提供命令行参数和配置文件两种配置方式
• 支持HTTP代理环境

适用场景

适用于测试自动化工程师、QA团队，当需要将CucumberStudio中的测试管理项目转换为具体编程语言的可执行测试脚本时使用，加速自动化测试开发流程。

安装与使用

使用Docker镜像

hiptest-publisher的Docker镜像已自动构建并发布在https://hub.docker.com/r/hiptest/hiptest-publisher/%E3%80%82

直接运行Docker命令

通过以下命令使用Docker镜像调用hiptest-publisher：

bash
docker run -it --rm -u $UID -v $(pwd):/app hiptest/hiptest-publisher <参数>

使用包装脚本

项目提供了包装脚本 https://raw.githubusercontent.com/hiptest/hiptest-publisher/master/bin/hiptest-publisher-docker%EF%BC%8C%E4%BD%BF%E7%94%A8%E6%AD%A5%E9%AA%A4%E5%A6%82%E4%B8%8B%EF%BC%9A

1. 将 bin/hiptest-publisher-docker 复制到PATH环境变量中的目录（如 ~/bin 或 /usr/local/bin）
2. 重命名为 hiptest-publisher
3. 赋予执行权限：chmod +x hiptest-publisher

之后即可像本地安装一样使用 hiptest-publisher 命令。

本地安装

需要先在机器上安装 Ruby，然后通过gem安装：

shell
gem install hiptest-publisher

注意：Windows用户请参考 Windows安装指南。

导出项目

1. 访问 CucumberStudio项目列表，选择目标项目，进入“设置”（Settings）标签页（仅项目管理员可见）
2. 复制项目的密钥令牌（secret token）
3. 执行以下命令导出测试脚本：

shell
hiptest-publisher --token=<您的令牌>

默认生成Ruby测试套件。目前支持以下语言和框架：

• Behat
• Behave
• CSharp (NUnit)
• Cucumber（Groovy/Java/Javascript/Ruby/TypeScript）
• Cucumber Legacy（Groovy/Java/TypeScript）（旧版Cucumber）
• Groovy (Spock)
• Java（Espresso/JUnit/TestNg）
• JavaScript（CodeceptJS/Jasmine/Mocha/Protractor/QUnit）
• JBehave
• PHP (PHPUnit)
• Python (UnitTest)
• Robot Framework
• Ruby（MiniTest/RSpec）
• Selenium IDE
• SpecFlow
• Swift (XCTest)

可通过命令行指定输出语言和框架，例如：

shell
hiptest-publisher --token=<您的令牌> --language=ruby --framework=minitest

导出时会生成 actionwords_signature.yaml 文件，请将其存储在代码仓库中，用于处理动作词更新。

从测试运行导出

可通过指定 --test-run-id=<ID> 选项从项目的特定测试运行导出测试套件。测试运行ID可在浏览器地址栏中找到（例如地址 https://studio.cucumber.io/projects/1234/testRuns/6941 中的 6941）：

shell
hiptest-publisher --token=<您的令牌> --test-run-id=6941

可用选项

执行以下命令查看所有可用选项：

shell
hiptest-publisher --help

输出示例：

shell
从CucumberStudio导出测试以进行自动化。

特定选项:
    -t, --token=TOKEN                密钥令牌（在项目设置中获取）
    -l, --language=LANG              目标语言（默认：ruby）
    -f, --framework=FRAMEWORK        测试框架
    -o, --output-directory=PATH      输出目录（默认：.）
        --filename-pattern=PATTERN   文件名模式（包含%s）
    -c, --config-file=PATH           配置文件
        --overriden-templates=PATH   自定义模板文件夹
        --overriden-language-configs=PATH
                                     自定义语言配置文件夹
        --test-run-id=ID             从指定ID的测试运行导出数据
        --test-run-name=NAME         从指定名称的测试运行导出数据
        --only=CATEGORIES            限制导出到指定文件类别（--only=list可列出所有类别）
        --without=CATEGORIES         排除指定文件类别（--only=list可列出所有类别）
    -x, --xml-file=PROJECT_XML       使用本地XML文件而非从CucumberStudio获取
        --tests-only                 （已弃用）--only=tests的别名（默认：false）
        --actionwords-only           （已弃用）--only=actionwords的别名（默认：false）
        --actionwords-signature      导出动作词签名（默认：false）
        --show-actionwords-diff      显示自上次更新后的动作词差异（摘要）（默认：false）
        --show-actionwords-diff-as-json
                                     显示自上次更新后的动作词差异（JSON格式）（默认：false）
        --show-actionwords-deleted   输出已删除动作词的签名（默认：false）
        --show-actionwords-created   输出新动作词的代码（默认：false）
        --show-actionwords-renamed   输出已重命名动作词的签名（默认：false）
        --show-actionwords-signature-changed
                                     输出签名已更改的动作词（默认：false）
        --show-actionwords-definition-changed
                                     输出定义已更改的动作词（默认：false）
        --library-name=LIBRARY_NAME  与show-actionwords-*配合使用：显示指定库的差异
        --with-folders               使用文件夹层级结构导出文件到相应目录（默认：false）
        --empty-folders              导出空文件夹（默认：false）
        --split-scenarios            将每个场景导出到单独文件（Gherkin类语言除外）（默认：false）
        --leafless-export            仅使用最底层动作词（默认：false）
    -s, --site=SITE                  获取数据的站点（默认：https://studio.cucumber.io）
    -p, --push=FILE.TAP              将结果文件推送到服务器
        --global-failure-on-missing-reports
                                     当无结果文件可推送时，报告全局失败（默认：false）
        --push-format=tap            测试结果格式（cucumber-json、junit、nunit、robot、tap）（默认：tap）
        --execution-environment=NAME 执行环境名称
        --sort=[id,order,alpha]      输出中测试的排序方式：id按创建时间，order保持在hiptest中的顺序（仅--with-folders时有效，否则 fallback 到id），alpha按名称（默认：order）
        --[no-]uids                  导出UID（注意：仅Gherkin类导出可禁用，禁用可能导致结果推送问题）（默认：true）
        --[no-]parent-folder-tags    导出父文件夹的标签（注意：若设为false，这些标签将永不显示。仅Gherkin类导出可用）（默认：true）
        --parameter-delimiter        参数分隔符（仅Gherkin类导出）（默认："）
        --with-dataset-names         导出要素文件时包含数据集名称（注意：仅Gherkin类导出可用）（默认：false）
        --keep-filenames             保留CucumberStudio中的测试文件名（注意：可能导致编码问题）（默认：false）
        --keep-foldernames           保留CucumberStudio中的文件夹名（注意：可能导致编码问题）（默认：false）
        --filter-on-scenario-ids=IDS 按场景ID筛选（多个ID用逗号分隔）
        --filter-on-folder-ids=IDS   按文件夹ID筛选（多个ID用逗号分隔）
        --filter-on-scenario-name=NAME
                                     按场景名称筛选（仅接受一个名称）
        --filter-on-folder-name=NAME 按文件夹名称筛选（仅接受一个名称）
        --filter-on-tags=TAGS        按场景和文件夹标签筛选（多个标签用逗号分隔）
        --filter-on-status=STATUS    按上次构建的测试状态筛选（需配合测试运行使用）
        --not-recursive              与filter-on-folder-ids或filter-on-folder-name配合使用：仅导出指定文件夹，不包含子文件夹（默认：false）
        --check-version              检查是否有hiptest-publisher的新版本（默认：false）
        --force                      强制覆盖现有文件（不适用于测试文件）（默认：false）
        --[no-]color                 强制[不]使用ANSI颜色文本输出
    -v, --verbose                    详细模式运行（默认：false）
    -H, --languages-help             显示语言和框架选项
    -h, --help                       显示此帮助信息

配置

可将配置存储在名为 config 的文件中。复制提供的 config.sample 文件并更新为您的值即可使用。

多项目场景下，可创建多个配置文件，并通过 --config-file 选项选择：

shell
# 使用默认配置文件
hiptest-publisher
# 使用导出为minitest的配置文件
hiptest-publisher --config-file=config_minitest

例如，Java项目的配置文件内容可如下：

token = '<您的令牌>'
language = 'java'
output_directory = '<您的输出目录>'
package = 'com.youcompany'

注意：命令行参数会覆盖配置文件中的选项。

若需覆盖现有配置，可使用 --overriden-language-configs 选项指定一个路径，该路径会优先于默认配置文件被检查。若找到对应配置文件，则使用该文件；否则使用指定语言的默认配置。

在HTTP代理后使用hiptest-publisher

若需在HTTP代理后使用，设置 http_proxy 环境变量：

http_proxy=http://<代理主机>:<代理端口>

若需要用户名和密码：

http_proxy=http://<用户名>:<密码>@<代理主机>:<代理端口>

推送测试结果到CucumberStudio

使用 --push 选项可将测试结果推送回CucumberStudio。为此，需先在代码生成时通过 --test-run-id=<xxx> 选项（或在配置文件中添加）从测试运行生成测试代码。

测试需生成CucumberStudio支持的测试报告，目前支持以下格式：

• Cucumber JSON格式
• jUnit XML格式
• https://github.com/nunit/docs/wiki/XML-Formats#v2-test-results
• Robot Framework XML输出
• TAP（测试任何协议）

推送时可通过 --push-format=[cucumber-json|junit|nunit|robot|tap] 选项指定导出类型（或在配置文件中设置）。

可同时推送多个文件（使用通配符），此时需添加引号：

hiptest-publisher --config-file=<配置文件路径> --push="reports/*.xml"

将显示导入的测试结果数量。调试时，可使用 --verbose 选项单独显示每个导入的测试。