Configure Gauge¶

Global configuration of Gauge (gauge.properties)¶

gauge.properties is a .properties file that contains all Gauge specific configurations. You can use or change the key value pairs present in this file to configure Gauge across all Gauge projects. This file is located at ~/.gauge/config in macOS and Linux systems and at %APPDATA%\gauge\config in Windows systems.

You can also use the gauge config command to change the value of a key in the gauge.properties file.

gauge config [flags] [args]

Example

For example, to change the value of check_updates in gauge.properties, use the command in the following way:

gauge config check_updates false

This changes the value of the key, check_updates, to false.

The list of key value pairs present in gauge.properties are listed as follows:

 1# Allow Gauge and its plugin updates to be notified to the user.
 2check_updates = true
 3
 4# Set to a URL, which acts as plugin repository for Gauge.
 5gauge_repository_url = https://downloads.gauge.org/plugin
 6
 7# Set to a URL, which acts as a template repository for Gauge.
 8gauge_templates_url = https://downloads.gauge.org/templates
 9
10# Timeout in milliseconds for requests from language
11# runner when connecting to IDE.
12ide_request_timeout = 30000
13
14# Sets the timeout in milliseconds for Gauge while
15# connecting to plugins (except language runner plugins).
16plugin_connection_timeout = 10000
17
18# Sets the timeout in milliseconds for a plugin to stop
19# after a kill message has been sent.
20plugin_kill_timeout = 10000
21
22# Sets the timeout in milliseconds for Gauge while
23# connecting to the language runner.
24runner_connection_timeout = 30000
25
26# Sets the timeout in milliseconds for requests from the
27# language runner to Gauge.
28# If the size of the Gauge project is too big, Gauge might time out before the
29# language runner returns the response message.
30runner_request_timeout = 10000

Local configuration of Gauge (default.properties)¶

default.properties is a .properties file that contains key value pairs. You can use or change the key value pairs present in this file to configure a particular Gauge project. The changed value overrides the default value of a key. This file is located at <project_root>/env/default, where <project_root> is the location at which you have created your Gauge project.

The list of key value pairs present in default.properties are listed as follows:

 1# The path to the gauge reports directory should be either relative to
 2# the project directory or an absolute path.
 3gauge_reports_dir = reports
 4
 5# Set as false if gauge reports should not be overwritten
 6# when Gauge runs a specification.
 7# If set to true, a new, time-stamped directory is
 8# created every time when Gauge runs a specification.
 9overwrite_reports = true
10
11# Set to false to disable screenshots on failure in Gauge reports.
12screenshot_on_failure = true
13
14# The path to the Gauge logs directory should be either relative to the
15# project directory or an absolute path.
16logs_directory = logs
17
18# Set to true to use multithreading for parallel execution
19enable_multithreading = false
20
21# The path to the gauge specifications directory.
22# Takes a comma separated list of specification files or directories.
23gauge_specs_dir = specs
24
25# CsvDelimiter holds delimiter used to parse csv files
26# default: `,`
27csv_delimiter = ,
28
29# Allows steps to be written in multiline
30allow_multiline_step = false

Language plugin configurations¶

<language>.properties is the .properties file corresponding to the language plugin that you have used while creating a Gauge project. Configuration properties set in these files are available as environment variables when Gauge runs a specification. You can use these properties or change them as per your requirements.

You can find the language specific .properties file at <project_root>/env/default/<language>.properties, where <project_root> is the location at which you have created the Gauge project.

For example, if you have installed Java on your system, then the path of the .properties file is <project_root>/env/default/java.properties.

For more details about running language plugins as an environment, see Environments.

If you have installed Java, then you can make Java specific configuration changes in the java.properties file. The following key value pairs are listed in java.properties:

 1# Specify an alternate Java home if you want to use a custom version of the Java Development Kit (JDK).
 2gauge_java_home = PATH_TO_JAVA_HOME
 3
 4# Use this property if you need to override the build path for the Gauge project.
 5# IntelliJ Idea and Eclipse out directory are usually auto-detected.
 6gauge_custom_build_path = PATH_TO_CUSTOM_BUILDPATH
 7
 8# Specify the directory where additional libraries are kept.
 9# You can specify multiple directory names separated with a comma `,`
10# `libs` directory in the gauge project is added by default.
11gauge_additional_libs = libs/*, PATH_TO_NEW_LIBRARY
12
13# Specify the JVM arguments passed to Java while launching.
14# Enter multiple values separated by comma (,). For example, Xmx1024m, Xms128m
15gauge_jvm_args = <JVM_ARGS>
16
17# Specify the directory containing Java files to be compiled.
18# You can specify multiple directory names separated with a comma (,).
19gauge_custom_compile_dir =
20
21# Specify the level at which the in-memory objects should be cleared
22# Possible values are suite, spec, and scenario. Default value is scenario.
23gauge_clear_state_level = scenario

If you have installed JavaScript, then you can make JavaScript specific configuration changes in the js.properties file. The following key value pairs are listed in js.properties:

1# Use this property if you need to override the timeout of a step when Gauge runs the step in a specification.
2test_timeout = 10000
3
4# Change this to true to enable browser debugging support
5DEBUG = false
6
7# Comma separated list of directories or paths (a path should be relative to project root).
8STEP_IMPL_DIR = tests

If you have installed Python, then you can make Python specific configuration changes in the python.properties file. The following key value pair is listed in python.properties:

1# Comma separated list of dirs. path should be relative to project root.
2STEP_IMPL_DIR = tests

If you have installed Csharp, then you can make Csharp specific configuration changes in the csharp.properties file. The following key value pair is listed in csharp.properties:

 1# Holds the location of the created Gauge project
 2GAUGE_CSHARP_PROJECT_FILE = SampleCsharp.csproj
 3
 4# The build configuration when running tests for the Gauge project
 5GAUGE_CSHARP_PROJECT_CONFIG = Debug
 6
 7# The build platform when running tests for the Gauge project
 8GAUGE_CSHARP_PROJECT_PLATFORM = Any CPU
 9
10# Specify the level at which the in-memory objects should be cleared
11# Possible values are suite, spec, and scenario. Default value is scenario.
12gauge_clear_state_level = scenario

If you have installed Ruby, then you can make Ruby specific configuration changes in the ruby.properties file. Ruby do not have any specific default configuration properties of its own currently.

HTTP_PROXY setting while using Gauge¶

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

export HTTP_PROXY=http://server-ip:port

export HTTP_PROXY=http://server-ip:port

set HTTP_PROXY=http://server-ip:port

export HTTP_PROXY=http://username:password@server-ip:port

export HTTP_PROXY=http://username:password@server-ip:port

set HTTP_PROXY=http://username:password@server-ip:port

Gauge configuration while using build tools¶

If you are using Gauge with the build tools such as Maven or Gradle, then you must be aware of specific configuration properties.

• For configuration information while using Gauge with Maven, see Gauge Maven Plugin repository.

• For configuration information while using Gauge with Gradle, see Gauge Gradle Plugin repository.

Using environments in a Gauge project¶

Environment specific variables can be managed by using property files. The property files have a set of key value pairs which are set as environment variables when Gauge runs a specification. Gauge allows you to create groups of property files by defining an environment.

A Gauge project can have multiple environments. default is the default environment. Gauge uses the –env flag to load an environment, when Gauge runs a specification. If –env is not specified, then the default environment is chosen during run time. Multiple environments can be specified along with the –env flag.

Example

The following example shows an env directory structure for a Java project. default.properties and java.properties are the .properties files created when you create a Gauge project with Java as the language runner. You can use or change the key value pairs in these .properties files as per your requirements.

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

Custom location for Environment Property files¶

By default, Gauge looks for environment property files in the env directory of the project.

To override Gauge’s default location for reading environment property files use the following options

• Set the location of the directory containing the environment property files in gauge_env_dir environment variable.

• Set EnvironmentDir key in manifest.json to the location of the directory containing the environment property files.

If gauge_env_dir is unset and EnvironmentDir is missing in manifest.json, gauge will default to env.

Create a new environment in a Gauge project¶

For ease of testing, you can create an environment in addition to the default existing environment in your Gauge project. You can create a new .properties file or add an existing property file to this new environment and customize the configuration properties as per your requirements.

Create a directory in the env folder of your Gauge project. The environment folder is present at <project_root>, where project_root is the location at which you have created your Gauge project.

mkdir <name_of_env>

Example

Create an environment called ci.

mkdir ci

A ci environment is created at <project_root>/env.

If you want to add your own key value pairs, then create a .properties file within the newly created environment.

Example

The following example shows multiple environments in a Gauge project, where env is located at <project_root>. ci, dev, and experimental are newly created environments in addition to the already existing default environment. The default environment is created when you create and initialize a Gauge project. ci and dev have newly created user.properties file, whereas experimental has default.properties and java.properties, which are already existing files.

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

For more information about language plugin configurations, see Language plugin configuration .

Run a Gauge specification with an environment¶

You can use the -env flag to load an environment when Gauge runs a specification. During run time, the key value pairs that you have used in the .properties file are set as environment variables. If -env is not specified, then the default environment is loaded during run time.

Use the following command at <project_root> (location at which you have created the Gauge project) to run a Gauge specification with an environment:

You can use the -env flag to load an environment when Gauge runs a specification. During run time, the key value pairs that you have used in the .properties file are set as environment variables. If -env is not specified, then the default environment is loaded during run time.

gauge run --env <name_of_env> specs

<name_of_env> - name of the environment that you choose to load

Example

In the following example, the ci environment is loaded when Gauge runs a specification.

gauge run --env ci specs

Run a Gauge specification with multiple environments¶

You can load multiple environments by using the -env flag when Gauge runs a specification. This allows ease of testing.

Use the following command at <project_root> (location at which you have created the Gauge project) to run a Gauge specification with multiple environments:

gauge run --env "<name_of_env_1>, <name_of_env_2>, default" specs

<name_of_env_1,2> - names of the environments that you choose to load

Example

In the following example, ci, experimental, and default environments are loaded when Gauge runs a specification.

gauge run --env "ci, experimental, default" specs

As per the rules of precedence, environment variables from ci are set first, followed by experimental, and then default.

Example

In the following example, environment variables from ci are set first, followed by default, and then experimental.

gauge run –env “ ci, default, experimental” specs

Example

In the following example, though default environment is not explicitly specified as an argument to --env, Gauge automatically adds this environment at the end of the list, which is after experimental.

gauge run –env “ ci, experimental” specs

Precedence of environments when running Gauge¶

If multiple environments are loaded when Gauge runs a specification, then Gauge follows the rules of precedence to load the environment variables as provided by the user and from the default environment. It is recommended that you understand these rules to run your tests effectively.

The rules of precedence to load the environment variables are as follows:

• Environment variables provided in the user shell of the user’s operating system.

• Environment variables (from the environments) provided by the user in the --env flag.

• Environment variables from gauge.properties (global configuration of Gauge; located at <project_root>/env).

• Environment variables from the default environment.

Gauge workflow with multiple environments¶

When Gauge is run with multiple environments, the following events occur:

1. Gauge loads the environment variables set at the operating system’s user shell.

2. Gauge loads the environment variables from the environments provided by the user in the --env flag.

   Attention

   If the environment mentioned in the --env flag is not found at <project_root>/env, Gauge ends with a non-zero exit code.

3. Next, Gauge loads the environment variables from gauge.properties (global configuration).

   Important

   Only those variables that are not yet set are loaded.

4. Lastly, Gauge loads the default environment variables as follows:

   • If the default directory is not present at <project_root>/env, Gauge internally sets the environment variables as mentioned in default.properties (local configuration).

   • If default is located at <project_root>/env, Gauge loads the environment variables from default.properties.

   Important

   Only those variables that are not yet set are loaded.

For more information about global configuration, see Global configuration of Gauge. For more information about local configuration, see Local configuration of Gauge.