README

"在将更改提交到仓库之前，在您的CI服务器上尝试您的更改！"

TryLib是一个简单的PHP库，帮助您生成工作副本的差异并将其发送到Jenkins以运行测试套件，并应用您的更改的最新代码。您可以在Etsy技术博客《Code As Craft》上了解更多关于try的信息：Code As Craft。

TryLib目前支持Freestyle项目，当您的测试套件只包含单个Jenkins作业时，以及当您的测试套件包含多个Jenkins作业时的MasterProject项目。

示例用法

try --help 输出

$ try -h
usage: try [options...] [subjob] [subjob] ...

    -h, --help            Show help
    -n, --diff-only       Create diff, but do not send to Hudson
    -v, --verbose         Verbose (show shell commands as they're run)
    -p, --patch ...       Path to patch file to use instead of generating a diff
    -U, --lines-of-context ...  Generate a diff with n lines of context (like git-diff's -U option)
    -s, --staged          Use staged changes only to generate the diff
    -w, --safelist ...    Generate the patch for only the safelisted files
    -b, --branch ...      Remote branch to diff and try against [main]

    -c, --show-results    Show final try job results
    -P, --show-progress   Print subtasks progressively as they complete
    --extra-param ...     Extra parameters to send to jenkins - format key=value
    -C, --callback ...    Callback string to execute at the end of the try run.

Use ${status} and ${url} as placeholders for the try build status and url
Example: --callback 'echo "**Try status : [${status}](${url})**"'

    --jenkinsjob ...      Master Job Name in Jenkins  [try]
    --jenkinsjobprefix ...  Subjobs prefix              [try]
    --jenkinsserver ...   URL to the jenkins server   [localhost:8080]
    --wcpath ...          Working Copy Path           [.]

在Freestyle项目上运行try并显示控制台中的结果。

$ try --show-results
Started try-unit-tests #25
Completed try-unit-tests #25 : SUCCESS

仅运行单元测试和集成测试（MasterProject配置），并显示子作业完成状态

$ try --show-progress
Executing DEFAULT sub-jobs: try-functional-tests try-integration-tests try-unit-tests
......... try ( pending )
......... try ( pending )
......... try ( http://etsyny-l523.local:8080/job/try/13/console )


                  try-unit-tests SUCCESS
            try-functional-tests SUCCESS
           try-integration-tests SUCCESS

Try Status : SUCCESS (http://etsyny-l523.local:8080/job/try/13)

运行try并将结果发布到github问题

try --callback "curl -s --user <login>:<password> --request POST --data '{\"body\":\"Try status : [${status}](${url})\"}'" https://github.com/api/v3/repos/etsy/try/issues/1/comments"

使用在您的jenkins作业中定义的参数运行try

try --extra-param foo=bar --extra-param baz=boo

尝试脚本配置

请随意在try中重用模板代码，并根据您的环境更新参数。根据您的设置（Freestyle项目或master-project），您可能需要注释/取消注释代码的一些部分 - 在注释中寻找[仅Jenkins MasterProject]。

# URL to your jenkins server (without http)
$jenkins_server = 'localhost:8080';

# Path to the jenkins cli.jar - download it from http://your.jenkins.instance/cli
$jenkins_cli_jar = '/usr/bin/jenkins-cli.jar';

# Jenkins job name
$default_jenkins_job = 'try';

# Working copy path (path to your local git repository)
$repo_path = '.';

重要：try脚本在工作副本根目录中生成patch.diff文件 - 请将其添加到您的.gitignore文件中，以避免应用补丁时出现冲突。

Jenkins配置

Freestyle项目

创建一个新的Freestyle项目
输入SCM设置
- 请确保在SCM选项中选择检出后清理
- 如果您想支持分支，请使用${branch}在分支检出名称中使用
勾选此构建是参数化的复选框，并输入以下参数

文件参数 文件位置：patch.diff

字符串参数 名称：guid 这是可选的 - 如果您有多个开发人员同时尝试，指定一个guid将有所帮助

字符串参数 名称：branch 这是可选的，如果您想基于分支构建

输入以下shell命令来应用补丁

  echo "Patch..."
  git apply --verbose patch.diff
  git add .
  # your command to launch your unit tests

MasterProject

master-project插件提供了一个新的项目类型，您可以从中选择应在一个逻辑主项目中执行的一组子项目。

为了在主项目上运行try，每个子项目都必须以主项目名称为前缀。一个设置的示例可能是

try : master-project
    try-unit-tests : sub-project to run the unit tests
    try-integration-tests : sub-project to run the integrations tests
    try-functional-tests : sub-project to run the functional tests

如果您的子作业没有以您的master-job名称为前缀，请相应地设置$jenkinsjobprefix，无论是在try脚本中还是在命令行中

$default_jenkins_job_prefix = 'foo';

./try --jenkinsjobprefix foo

更多信息可以在divide and concur Code As Craft博客条目中找到。

在Jenkins中设置master-project

如果您还没有安装，请安装master-project插件
按照FreeStyle项目的说明设置各个子作业。每个子作业必须具有相同的名称前缀 - 例如：try-。默认情况下，使用的是主项目名称作为前缀，但您可以通过指定 --jenkinsjobprefix 来覆盖此行为。
创建一个新的 主项目 并将其命名为 try
勾选 允许构建和隐藏选定的子作业 复选框
指定 默认项目名称，例如：try-unit-tests try-orm-tests try-integration-tests
勾选此构建是参数化的复选框，并输入以下参数

文件参数 文件位置：patch.diff

字符串参数 名称：guid 这是可选的 - 如果您有多个开发人员同时尝试，指定一个guid将有所帮助

字符串参数 名称：branch 这是可选的，如果您想基于分支构建
在 子作业 中，勾选所有应与主项目一起启用的子项目（至少包括所有默认项目，但您可以选择更多作业）

处理分支（Git）

try 将与您的分支一起工作！以下场景受支持：

您正在处理 main 分支
- 您想针对 main 分支进行尝试
```
  try [options] [subjobs]
```
- 您想与不同的分支进行 diff 和尝试
```
  try --branch=my_other_branch [options] [subjobs]
```
您正在处理一个 远程跟踪的分支
- 您想针对该分支进行尝试
```
  try [options] [subjobs]
```
- 您想与不同的分支（例如 main）进行 diff 和尝试
```
  try --branch=main [options] [subjobs]
```
您正在处理一个 未跟踪的本地分支
- 如果远程有相同名称的分支，它将被用来生成 diff 并针对它进行尝试
- 如果远程没有相同名称的分支，它将使用默认远程：main
- 您想与特定的远程分支进行 diff 和尝试
```
  try --branch=my_branch [options] [subjobs]
```

使用预检查

在生成 diff 之前，您可以为 try 配置运行一系列预检查。

$pre_checks = array(
    new TryLib\Precheck\ScriptRunner('/path/to/some/script'),
    new TryLib\Precheck\GitCopyBehind(array('main')),
    new TryLib\Precheck\GitCopyAge(48, 96, $remote_branch)
    new TryLib\Precheck\GitReportUntracked(),
);

$repo_manager->runPrechecks($pre_checks);

一些预检查只会发出警告，而另一些可能会阻止 try 执行。

运行测试

您可以使用以下方式运行单元测试套件：

phpunit

etsy / try-lib

维护者

详细信息