Gauge中文文档(9)—配置

最新翻译(2020/12/1)已更新在个人博客：https://www.nothinghere.cn/gauge/overview/

所有gauge内部的特定配置都存储在gauge.properties文件。在MAC/LINUX系统此文件存于~/.gauge/config，在windows系统存于%APPDATA%\GAUGE\config(或者GAUGE_ROOT)。这些属性都是键值对。

全局配置

# set to a url, which acts as plugin repository for Gauge.
# gauge插件库下载地址
gauge_repository_url = https://downloads.getgauge.io/plugin

# set to a url, which holds version information of Gauge.
# This is used to determine if an update is available.
# gauge插件库升级地址
gauge_update_url = https://downloads.getgauge.io/gauge

# set to an url, which acts as template repository for Gauge.
# gauge模版库下载地址
gauge_templates_url = https://downloads.getgauge.io/templates

# sets the timeout in milliseconds for making a
# connection to the language runner.
# 连接到language runner的超时时间，时间单位：毫秒
runner_connection_timeout = 30000

# sets the timeout in milliseconds for making a connection
# to plugins (except language runner plugins).
# 连接到除了language runner之外的插件的超时时间，时间单位：毫秒
plugin_connection_timeout = 10000

# sets the timeout in milliseconds for a plugin to stop
# after a kill message has been sent.
# 设置在发送kill消息后插件停止的超时时间，时间单位：毫秒
plugin_kill_timeout = 10000

# sets the timeout in milliseconds for requests from the
# language runner.
# If the size of the project is too big, Gauge may timeout before the
# runner returns the response message. This value can be configured
# accordingly.
# 设置从language runner请求超时，单位毫秒
# 如果项目太大，gauge可能会在runner返回响应消息之前超时。这个值应当设置合理。
runner_request_timeout = 10000

# sets the excluded dirs for gauge.
# Gauge always looks for concepts in the whole project, folders starting
# with dot(.) are excluded and a user can add folders to the excluded
# folders list by passing a comma separeted paths of folder.Paths can be
# relative to the path of directory or absolute.
# 设置gauge排除目录
# gauge通常在整个项目中查找concepts，排除以点(.)开头的文件夹
# 用户可以通过传递逗号分割的文件夹路径来将其添加到排除文件夹列表中
# 文件夹的路径可以相对于目录路径或者绝对路径。
gauge_exclude_dirs = "src/test,bin"

本地配置（项目层级）

某些属性可以在env/default/default.properties里配置， 这些属性覆盖默认属性且只在当前项目中生效。它们都是键值对。

# The path to the gauge reports directory. Should be either relative to
# the project directory or an absolute path
# gauge报告目录路径，可以是对于项目的相对路径或者绝对路径
gauge_reports_dir = reports

# Set as false if gauge reports should not be overwritten
# on each execution.
# If set to true, a new time-stamped directory will be
# created on each execution.
# 设置为false则报告在每次执行后不会被覆盖
# 设置为true则每次执行会生成一个新的带时间戳的目录
overwrite_reports = true

# Set to false to disable screenshots on failure in reports.
# 设置为flase则报告中的失败不会截屏
screenshot_on_failure = false

# The path to the gauge logs directory. Should be either relative to the
# project directory or an absolute path
# gauge日志目录路径，可以是对于项目的相对路径或者绝对路径
logs_directory = GaugeLogs

# Specify the level at which cached objects should get removed while
# execution.
# 指定执行时被移除缓存对象的层级
# Possible values for this property are 'suite', 'spec' or 'scenario'.
# default: 'scenario'.
# 可用的属性值：'suite', 'spec' or 'scenario'。
# 默认值：'scenario'.
gauge_clear_state_level = spec
# The above clears the objects after the execution of each specification, so
# that new objects are created for next execution.
# 上述内容在执行每个spec后清除对象，以便创建新对象已供下次执行。

# Set to false to disable screenshots on failure in reports.
# 设置为flase则报告中的失败不会截屏
# （译者注：上面的配置中已经有一个false，只需要配置一个true或者false）
screenshot_on_failure = true

# Path to generate custom report theme.
# Should be either relative to the project directory or an absolute path.
# Default theme is used if not set
# 生成自定义报告主题的路径
# 可以是对于项目的相对路径或者绝对路径
# 如果不设置则使用默认
GAUGE_HTML_REPORT_THEME_PATH = custom_theme_path

环境变量

环境指定变量可以通过使用属性文件管理。这个属性文件具有在执行测试时设置为环境变量的一组键值对。

Gauge允许您通过定义和环境创建属性文件组。

一个项目可以有多个环境，并且根据参数-env指定，在运行时加载相应的环境。default是默认环境，它在没有指定-env时被加载。

Java项目环境目录结构：

├── env
  └── default
     ├── default.properties
     └── java.properties

自定义属性可以添加到已有属性文件或者新创建的属性文件。

创建新环境变量

为创建名为ci的环境：

• 在env目录创建ci目录
• 添加属性文件(如：user.properties)

├── env
   ├── ci
      |── user.properties
   |── default
      ├── default.properties
      └── java.properties

通过环境变量执行

环境通过使用env标志来指定。例如执行时使用ci环境。

>gauge run --env ci specs

环境优先级

环境变量值的优先级顺序如下：

1. 用户shell/系统环境变量值；
2. 通过--env标志传递的项目环境；
3. env/default目录（如果存在）内项目环境；
4. Gauge默认环境变量值，如下：
   |属性|值|
   |-|-|
   |gauge_reports_dir|reports|
   |overwrite_reports|true|
   |screenshot_on_failure|true|
   |logs_directory|logs|

Gauge加载环境变量如下：

• Gauge项目开始后，用户传递的--env标志内的环境会被加载。如果用户没有传递此标志，则会加载default环境。
• Gauge然后加载default环境，只有还未设置的值会被加载。这一步不会覆盖第一步里设置的变量。
• 最后Gauge将加载还未设置的环境变量，如上表。
• 可以通过明确设置相应的系统环境变量来覆盖这些值。
• 如果在--env标志提到的环境在项目中未被找到，则gauge会以非0退出编码结束。
• gauge项目不需要有default环境，因为gauge会使用上述变量的默认值。用户仍可以设置default环境为覆盖或者添加新的环境变量，但是不用通过--env标志。

示例

• 用户执行gauge run specs
  • 如果<project_root>/env/default不存在，Gauge将设置默认环境变量为上述表格提到的值。
  • 如果<project_root>/env/default存在，Gauge将设置环境变量为default环境提到的值。然后设置任意变量（仍未设置的变量）如上表。
• 用户执行gauge run --env==java_ci specs
  • 如果<project_root>/env/java_ci不存在，Gauge将以非0退出编码结束。
  • 如果<project_root>/env/java_ci存在，Gauge将设置环境变量为java_ci环境提到的值。然后从default环境加载还未设置的变量。最后，设置环境变量(如果还未设置)为上表提到的值。
• 用户执行gauge_reports_dir=newReportsDir gauge run specs或者用户明确地在shell里设置gauge_reports_dir=newReportsDir然后执行gauge run specs
  • 除了变量gauge_reports_dir，Gauge将先从env/default目录再从上述表格内设置所有的默认环境变量。这个变量的值依然是newReportsDir。
• 用户执行gauge_reports_dir=newReportsDir gauge run --env=java_ci specs 或者用户明确地在shell里设置gauge_reports_dir=newReportsDir然后执行gauge run --env=java_ci specs
  • Gauge将设置环境变量为java_ci环境提到的值。然后从default环境加载还未设置的其他变量。最后， 设置环境变量(如果还未设置)为上表提到的值。然后变量gauge_reports_dir,已经明确地在shell设置后将不会被覆盖。这个变量的值依然是newReportsDir。

语言插件

一般情况

这里设置的配置属性可在测试执行时被作为环境变量，更多细节请见环境章节（译者注：上一小节）。
属性是已下列格式定义：

sample_key = sample_value

Java

Java特定配置可以在env/default/java.properties被改变。

# Specify an alternate Java home if you want to use a custom version.
# 如果你想使用自定义版本，指定备用的java home路径
gauge_java_home = PATH_TO_JAVA_HOME

# Use this property if you need to override the build path for the
# project.
# Note: IntelliJ out directory will be usually auto-detected.
# 使用此属性如果你想为此项目覆盖构建路径
# 备注：Intellij输出路径通常会自动检测
gauge_custom_build_path = PATH_TO_CUSTOM_BUILDPATH

# Specify the directory where additional libraries are kept.
#   You can specify multiple directory names separated with a comma `,`
#   `libs` directory in the gauge project is added by default.
# 指定额外库保存目录，您可以指定多个目录名字以逗号`,`隔开
# `libs`目录在gauge项目中默认被添加
gauge_additional_libs = libs/*, PATH_TO_NEW_LIBRARY

# Specify the JVM arguments passed to java while launching.
# 在执行时传递给java的指定JVM参数
gauge_jvm_args = <JVM_ARGS>

---

备注
C#和ruby语言运行器不会有超出默认属性中列出的任何配置。

---

HTTP代理

Gauge连接互联网来下载插件，模版等等。如果您想使用代理，您需要配置代理设置使得gauge通过代理服务器连接互联网。

无认证

如果不需要认证，将环境变量HTTP_PROXY设置为代理服务器URL。

export HTTP_PROXY=http://10.0.2.2:5678

有认证

如果需要认证，将环境变量HTTP_PROXY设置为代理服务器URL以及认证信息。

export HTTP_PROXY=http://username:password@10.0.2.2:5678

构建工具

您可以将gauge同任何您喜欢的构建工具一起使用。

下列是几款简单的构建文件：

1. Maven
2. Gradle
3. Ant

Maven

使用gauge-maven-plugin在您的gauge java项目执行specs，并使用maven管理依赖项。

从archetype创建新项目

mvn archetype:generate -DgroupId={projectGroupId}
-DartifactId={projectArtifactId}
-DarchetypeArtifactId=gauge-archetype-java
-DarchetypeGroupId=com.thoughtworks.gauge.maven

基于您的项目来设置{projectGroupId} 和 {projectArtifactId} 。查看maven文档以理解groupId和artifactId在maven项目中的意义。

在IDE创建gauge maven项目

---

备注
查看在maven项目中使用gauge-maven-plugin

---

在项目中生成的pom.xml将具有gauge-java依赖关系和在测试阶段定义的执行目标gauge:execute。

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.foo</groupId>
    <artifactId>my-gauge-tests</artifactId>
    <version>1.0-SNAPSHOT</version>

    <dependencies>
        <dependency>
            <groupId>com.thoughtworks.gauge</groupId>
            <artifactId>gauge-java</artifactId>
            <version>0.2.2</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <testSourceDirectory>${project.basedir}/src/test/java</testSourceDirectory>
        <plugins>
            <plugin>
                <groupId>com.thoughtworks.gauge.maven</groupId>
                <artifactId>gauge-maven-plugin</artifactId>
                <version>1.0.3</version>
                <executions>
                    <execution>
                        <phase>test</phase>
                        <configuration>
                            <specsDir>specs</specsDir>
                        </configuration>
                        <goals>
                            <goal>execute</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

使用maven执行specs

如果在测试阶段（参考上述xml文件）执行目标被添加，然后运行maven测试阶段将也在项目中执行gauge specs。

> mvn test

仅仅执行gauge specs

> mvn gauge:execute -DspecsDir=specs

运行对应pom.xml中特定测试配置文件的gauge specs

> mvn gauge:execute -P < profile-name >

并行执行specs

> mvn gauge:execute -DspecsDir=specs -DinParallel=true

通过tags执行specs

> mvn gauge:execute -DspecsDir=specs -Dtags="!in-progress"

指定执行环境

> mvn gauge:execute -DspecsDir=specs -Denv=“dev”

所有其他属性

可以额外设置以下插件属性：

属性	用法	描述
specsDir	-DspecsDir=specs	gauge specs目录路径，用来执行specs
tags	-Dtags=tag1 & tag2	通过tag表达式来筛选specs
inParallel	-DinParallel=true	并行执行specs
nodes	-Dnodes=3	同parallel一同使用，设置并行执行流数量
env	-Denv=qa	gauge执行环境
dir	-Ddir=.	设置gauge工作目录，默认是 project.base.dir.
flags	-Dflags="–verbose"	添加额外的gauge标志来执行

查看gauge帮助文档，列出所有可用于**-Dflags**选项的flags。

Gradle

使用gauge-gradle-plugin来执行您gauge java项目中的specs，并通过gradle管理依赖项。

项目中使用插件

添加插件gauge并添加classpath至您的build.gradle，下列是一个gradle文件示例：

apply plugin: 'java'
apply plugin: 'gauge'
apply plugin: 'application'

group = "my-gauge-tests"
version = "1.0.0"

description = "My Gauge Tests"

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'com.thoughtworks.gauge.gradle:gauge-gradle-plugin:+'
    }
}

repositories {
    mavenCentral()
}

dependencies {
}

// configure gauge task here (optional)
gauge {
    specsDir = 'specs'
    inParallel = true
    nodes = 2
    env = 'dev'
    tags = 'tag1'
    additionalFlags = '--verbose'
}

此插件亦在Gradle Plugin Portal可用，更多细节参考这里。

执行specs

为执行gauge specs

> gradle specs

并行执行specs

> gradle gauge -PinParallel=true -PspecsDir=specs

通过tags执行specs

> gradle gauge -Ptags="!in-progress" -PspecsDir=specs

指定执行环境

> gradle gauge -Penv=“dev” -PspecsDir=specs

备注：将specsDir作为最后一个参数传递。

所有其他属性

可以额外设置以下插件属性：

属性	用法	描述
specsDir	-PspecsDir=specs	gauge specs目录路径，用来执行specs
tags	-Ptags=tag1 & tag2	通过tag表达式来筛选specs
inParallel	-PinParallel=true	并行执行specs
nodes	-Pnodes=3	同parallel一同使用，设置并行执行流数量
env	-Penv=qa	gauge执行环境
dir	-Pdir=.	设置gauge工作目录，默认是 project.base.dir.
flags	-Pflags="–verbose"	添加额外的gauge标志来执行

查看gauge帮助文档，列出所有可用于**-PadditionalFlags **选项的flags。

添加/配置自定义gauge任务

可以通过扩展GaugePlugin类定义新的自定义gauge任务，这可以用来创建/配置指定不同环境的任务。例如：

task gaugeDev(type: GaugeTask) {
    doFirst {
        gauge {
            specsDir = 'specs'
            inParallel = true
            nodes = 2
            env = 'dev'
            additionalFlags = '--verbose'
        }
    }
}

task gaugeTest(type: GaugeTask) {
    doFirst {
        gauge {
            specsDir = 'specs'
            inParallel = true
            nodes = 4
            env = 'test'
            additionalFlags = '--verbose'
        }
    }
}

Ant Task

通过添加下列的配置到您的build.xml文件中，ant可以调用gauge specs。

<target name="specs">
    <exec executable="gauge">
        <arg value="specs"/>
    </exec>
</target>

---

章节指引
一、安装
二、快速开始
三、深入开始
四、Gauge使用
五、语法
六、插件
七、语言特点
八、报告
九、配置
十、故障处理
十一、项目实例
十二、怎么做?