Configuration¶

All the Gauge specific internal configurations are stored in gauge.properties file present in ~/.gauge/config in Mac/Linux and in %APPDATA%\Gauge\config in windows (or GAUGE_ROOT) repository. These properties are key value pairs.

Global¶

# set to a url, which acts as plugin repository for Gauge.
gauge_repository_url = https://downloads.gauge.org/plugin

# set to a url, which holds version information of Gauge.
# This is used to determine if an update is available.
gauge_update_url = https://downloads.gauge.org/gauge

# set to an url, which acts as template repository for Gauge.
gauge_templates_url = https://downloads.gauge.org/templates

# sets the timeout in milliseconds for making a
# connection to the language runner.
runner_connection_timeout = 30000

# sets the timeout in milliseconds for making a connection
# to plugins (except language runner plugins).
plugin_connection_timeout = 10000

# sets the timeout in milliseconds for a plugin to stop
# after a kill message has been sent.
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.
runner_request_timeout = 10000

Local (Project level)¶

Certain properties can be configured in env/default/default.properties, which overrides the default properties and are scoped only to the current project. These are key value pairs.

# The path to the gauge reports directory. Should be either relative to
# the project directory or an absolute path
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.
overwrite_reports = true

# Set to false to disable screenshots on failure in reports.
screenshot_on_failure = false

# The path to the gauge logs directory. Should be either relative to the
# project directory or an absolute path
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'.
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.

# Set to false to disable screenshots on failure in reports.
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

# 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_exclude_dirs = src/test,bin

Environments¶

Environment specific variables can be managed using property files. The property files have set of key value pairs which are set as environment variables during execution.

Gauge allows you to create groups of property files, by defining and environment.

A project can have multiple environments, and depending on the argument –env specified, the corresponding environment is loaded at runtime. default is the default environment, which is loaded when no –env is specified.

The env directory structure for a java project:

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

Custom properties can be added to an existing property files or in a newly created one.

Creating new environment¶

To create an environment called ci:

Create a directory called ci in env directory
Add property files (e.g. user.properties)

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

Executing with environment¶

The environment is specified using the env flag. For example if ci environment is used during execution

gauge run --env ci specs

Precedence of Environments¶

Precedence to the env variable value is given in the below order. 1. User shell / OS env variable values 2. Project environment passed in the --env flag 3. Project environment present in the env/default dir (if present) 3. Gauge default env variable values, as below

Property	Value
gauge_reports_dir	reports
overwrite_reports	true
screenshot_on_failure	true
logs_directory	logs

Gauge loads the enviroment variables as below.

When Gauge starts, the environment passed by the user in the --env flag will be loaded. If this flag is not passed by the user, default environment will be loaded.
Gauge will then load the default environment. Only the values which are not yet set will be loaded. This step won’t overwrite the variables which are set in step 1.
Finally, Gauge will load the environment variables which are not yet set, as per the table above.
These values can be overwritten by explicitly setting the respective OS environment variables.
If the environment mentioned in the --env flag is not found in the project, Gauge will end with a non-zero exit code.
Gauge project doesn’t need to have a default env since Gauge will use the above values as default. User can still set the default env to either overwrite or add new env variables, but doesn’t want to pass the --env flag.

Examples¶

User executes gauge run specs
- If <project_root>/env/default is not present, Gauge will set the default env variables with values mentioned in the table above.
- If <project_root>/env/default is present, Gauge will set the env variables mentioned in the default environment. It will then set any env variable (which is not already set) as per the table above.
User executes gauge run --env=java_ci specs
- If <project_root>/env/java_ci is not present, Gauge will end with a non-zero exit code.
- If <project_root>/env/java_ci is present, Gauge will set the env variables mentioned in the java_ci environment. It will then load other variables from the default environment which are not already set. Finally, it will the set the env vars with values mentioned in the table above (if they are not already set).
User executes gauge_reports_dir=newReportsDir gauge run specs or user explicitly sets gauge_reports_dir=newReportsDir in shell and then runs gauge run specs
- Gauge will set all the default env variables from env/default directory and then from the above table, except for the variable gauge_reports_dir. This variable’s value will still continue to be newReportsDir.
User executes gauge_reports_dir=newReportsDir gauge run --env=java_ci specs or user explicitly sets gauge_reports_dir=newReportsDir in shell and then runs gauge run --env=java_ci specs
- Gauge will set the env variables mentioned in the java_ci environment. It will then load other variables from the default environment which are not already set. Finally, it will the set the env vars with values mentioned in the table above (if they are not already set). However variable gauge_reports_dir, which is explicitly set in the shell will not be overwritten. This variable’s value will still continue to be newReportsDir.

Language Plugin¶

General¶

Configuration properties set here will be available to the test execution as environment variables. Please see Environments for more details.

Properties are defined in the following format.

sample_key = sample_value

Java¶

Java Specific configuration changes can be made in the env/default/java.properties file.

# Specify an alternate Java home if you want to use a custom version.
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.
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.
gauge_additional_libs = libs/*, PATH_TO_NEW_LIBRARY

# Specify the JVM arguments passed to java while launching.
gauge_jvm_args = <JVM_ARGS>

Javascript¶

Javascript Specific configuration changes can be made in the env/default/js.properties file.

# Use this property if you need to override the timeout of step
test_timeout = 10000

Python¶

Python Specific configuration changes can be made in the env/default/python.properties file.

# Override this if you want to use a different command
GAUGE_PYTHON_COMMAND = python

Note

CSharp and Ruby language runners do not hold any configuration beyond what is listed in default properties.

HTTP Proxy¶

Gauge connects to internet for downloading plugins, templates, etc. If you are behind a proxy, you will have to configure the proxy settings so that Gauge connects to internet via the proxy server.

Without Authentication¶

If authentication is not required, set the environment variable HTTP_PROXY to proxy server URL.

export HTTP_PROXY=http://10.0.2.2:5678

With Authentication¶

If authentication is required, set the environment variable HTTP_PROXY to proxy server URL along with the credentials.

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

Build tools¶

You can use Gauge with any of the build tools that you like.

Here are the sample build files for

Maven
Gradle
Ant

Maven¶

Use the gauge-maven-plugin to execute specifications in your gauge java project and manage dependencies using maven.

Creating a new project from archetype¶

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

Set {projectGroupId} and {projectArtifactId} based on your project. See maven docs to understand what groupId and artifactId mean in a maven project.

Gauge maven project creation in IDE¶

Note

See Maven project using gauge-maven-plugin

The generated pom.xml in the project will have the gauge-java dependency and a gauge:execute goal defined in the test phase.

<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>

Executing specs using maven¶

If the execute goal is added for test phase (see above xml) then running maven test phase will also execute gauge specs in the project

mvn test

To only run gauge specs in a particular directory,¶

mvn gauge:execute -DspecsDir=specs

To run one gauge spec,¶

mvn gauge:execute -DspecsDir=specs/example.spec

To run multiple gauge specs,¶

mvn gauge:execute -DspecsDir="specs/example.spec,specs/example2.spec"

To only run gauge specs that correspond to a particular test profile in pom.xml,¶

mvn gauge:execute -P <profile-name>

Execute specs In parallel¶

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

Execute specs by tags¶

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

Specifying execution environment¶

mvn gauge:execute -DspecsDir=specs -Denv="dev"

All additional Properties¶

The following plugin properties can be additionally set:

Property	Usage	Description
`specsDir`	`-DspecsDir=specs`	Gauge specs directory path. Required for executing specs. Takes a comma separeted list of spec files/directories.
`tags`	`-Dtags=tag1 & tag2`	Filter specs by specified tag expression.
`inParallel`	`-DinParallel=true`	Execute specs in parallel.
`nodes`	`-Dnodes=3`	Number of parallel execution streams. Use with `parallel`.
`env`	`-Denv=qa`	gauge env to run against.
`dir`	`-Ddir=.`	Set working directory for gauge. Default is project.base.dir.
`flags`	`-Dflags="--verbose"`	Add additional gauge flags to execution.

See gauge’s Help for list of all flags that be used with -Dflags option.

Gradle¶

Use the gauge-gradle-plugin to execute specifications in your Gauge java project and manage dependencies using Gradle.

Using plugin in project¶

Apply plugin *gauge* and add classpath to your *build.gradle*. Here is a sample gradle file,

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'
}

The plugin is also available at Gradle Plugin Portal. Find more details here.

Executing specs¶

To execute gauge specs,

gradle gauge

Execute specs in parallel¶

gradle gauge -PinParallel=true -PspecsDir=specs

Execute specs by tags¶

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

Specifying execution environment¶

gradle gauge -Penv="dev" -PspecsDir=specs

Note : Pass specsDir parameter as the last one.

All additional Properties¶

The following plugin properties can be additionally set:

Property	Usage	Description
`specsDir`	`-PspecsDir=specs`	Gauge specs directory path. Required for executing specs.
`tags`	`-Ptags=tag1 & tag2`	Filter specs by specified tag expression.
`inParallel`	`-PinParallel=true`	Execute specs in parallel.
`nodes`	`-Pnodes=3`	Number of parallel execution streams. Use with `parallel`.
`env`	`-Penv=qa`	gauge env to run against.
`dir`	`-Pdir=.`	Set working directory for gauge. Default is project.base.dir.
`flags`	`-Pflags="--verbose"`	Add additional gauge flags to execution.

See gauge’s Help for list of all flags that be used with -PadditionalFlags option.

Adding/configuring custom Gauge tasks¶

It is possible to define new custom Gauge tasks by extending GaugePlugin class. It can be used to create/configure tasks specific for different environments. For example,

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¶

Gauge specs can be invoked via Ant by adding the below configuration in your build.xml

build.xml¶

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