' do|role, table| puts table.rows puts table.columns end13.2 Execution hooks
Test execution hooks can be used to run arbitrary test code as different levels during the test suite execution.
13.2.1 Implementation
Listing 13.11: C# public class ExecutionHooks {
[BeforeSuite]
13.2. Execution hooks 79 Gauge Documentation, Release 0.9.8
public void BeforeSuite(){ // Code for before suite }
[AfterSuite] public void AfterSuite(){ // Code for after suite }
[BeforeSpec] public void BeforeSpec(){ // Code for before spec }
[AfterSpec] public void AfterSpec(){ // Code for after spec }
[BeforeScenario] public void BeforeScenario(){ // Code for before scenario }
[AfterScenario] public void AfterScenario(){ // Code for after scenario }
[BeforeStep] public void BeforeStep(){ // Code for before step }
[AfterStep] public void AfterStep(){ // Code for after step }
}
Listing 13.12: Java public class ExecutionHooks{
@BeforeSuite public void BeforeSuite(){ // Code for before suite }
@AfterSuite public void AfterSuite(){ // Code for after suite }
@BeforeSpec public void BeforeSpec(){ // Code for before spec }
80 Chapter 13. Language Features Gauge Documentation, Release 0.9.8
@AfterSpec public void AfterSpec(){ // Code for after spec }
@BeforeScenario public void BeforeScenario(){ // Code for before scenario }
@AfterScenario public void AfterScenario(){ // Code for after scenario }
@BeforeStep public void BeforeStep(){ // Code for before step }
@AfterStep public void AfterStep(){ // Code for after step }
}
Listing 13.13: Javascript hooks.beforeSuite(fn,[opts]){ // Code for before suite } hooks.beforeSpec(fn,[opts]){ // Code for before spec } hooks.beforeScenario(fn,[opts]){ // Code for before scenario } hooks.beforeStep(fn,[opts]){ // Code for before step } hooks.afterSuite(fn,[opts]){ // Code for after suite } hooks.afterSpec(fn,[opts]){ // Code for after spec } hooks.afterScenario(fn,[opts]){ // Code for after scenario }
13.2. Execution hooks 81 Gauge Documentation, Release 0.9.8
hooks.afterStep(fn,[opts]){ // Code for after step }
Listing 13.14: Python from getgauge.python import before_step, after_step, before_scenario, after_scenario,
˓→before_spec, after_spec, before_suite, after_suite
@before_step def before_step_hook(): print("before step hook")
@after_step def after_step_hook(): print("after step hook")
@before_scenario def before_scenario_hook(): print("before scenario hook")
@after_scenario def after_scenario_hook(): print("after scenario hook")
@before_spec def before_spec_hook(): print("before spec hook")
@after_spec def after_spec_hook(): print("after spec hook")
@before_suite def before_suite_hook(): print("before suite hook")
@after_suite def after_spec_hook(): print("after suite hook")
Listing 13.15: Ruby before_suite do # Code for before suite end after_suite do # Code for after suite end before_spec do # Code for before spec end after_spec do # Code for after spec
82 Chapter 13. Language Features Gauge Documentation, Release 0.9.8
end before_scenario do # Code for before scenario end after_scenario do # Code for after scenario end before_step do # Code for before step end after_step do # Code for after step end
By default, Gauge clears the state after each scenario so that new objects are created for next scenario execution. You can configure to change the level at which Gauge clears cache.
13.3 Data Store
Data (Objects) can be shared in steps defined in different classes at runtime using DataStores exposed by Gauge. There are 3 different types of DataStores based on the lifecycle of when it gets cleared.
13.3.1 ScenarioStore
This data store keeps values added to it in the lifecycle of the scenario execution. Values are cleared after every scenario executes
Listing 13.16: C# using Gauge.CSharp.Lib;
// Adding value var scenarioStore= DataStoreFactory.ScenarioDataStore; scenarioStore.Add("element-id", "455678");
// Fetching Value var elementId=(string) scenarioStore.Get("element-id");
// avoid type cast by using generic Get var anotherElementId= scenarioStore.Get("element-id");
Listing 13.17: Java import com.thoughtworks.gauge.datastore.*;
// Adding value DataStore scenarioStore= DataStoreFactory.getScenarioDataStore(); scenarioStore.put("element-id", "455678");
13.3. Data Store 83 Gauge Documentation, Release 0.9.8
// Fetching Value String elementId=(String) scenarioStore.get("element-id");
Listing 13.18: Javascript // Adding value gauge.dataStore.scenarioStore.put(key, value);
// Fetching Value gauge.dataStore.scenarioStore.get(key);
Listing 13.19: python from getgauge.python import DataStoreFactory // Adding value DataStoreFactory.scenario_data_store().put(key, value)
// Fetching Value DataStoreFactory.scenario_data_store().get(key)
Listing 13.20: Ruby // Adding value scenario_store= DataStoreFactory.scenario_datastore; scenario_store.put("element-id","455678");
// Fetching Value element_id= scenario_store.get("element-id");
13.3.2 SpecStore
This data store keeps values added to it during the lifecycle of the specification execution. Values are cleared after every specification executes
Listing 13.21: C# using Gauge.CSharp.Lib;
// Adding value var specStore= DataStoreFactory.SpecDataStore; specStore.Add("element-id", "455678");
// Fetching Value var elementId=(string) specStore.Get("element-id");
// avoid type cast by using generic Get var anotherElementId= specStore.Get("element-id");
Listing 13.22: Java // Import Package import com.thoughtworks.gauge.datastore.*;
// Adding value DataStore specStore =
84 Chapter 13. Language Features Gauge Documentation, Release 0.9.8
DataStoreFactory.getSpecDataStore(); specStore.put("key", "455678");
// Fetching value DataStore specStore = String elementId=(String) specStore.get("key");
Listing 13.23: Javascript // Adding value DataStore specStore = gauge.dataStore.specStore.put(key, value); // Fetching value DataStore specStore = gauge.dataStore.specStore.get(key);
Listing 13.24: Python // Import Package import from getgauge.python import DataStoreFactory // Adding value DataStore specStore= DataStoreFactory.spec_data_store().put(key, value)
// Fetching value DataStore specStore= DataStoreFactory.spec_data_store().get(key)
Listing 13.25: Ruby // Adding value spec_store= DataStoreFactory.spec_datastore; spec_store.put("element-id","455678");
// Fetching Value element_id= spec_store.get("element-id");
13.3.3 SuiteStore
This data store keeps values added to it during the lifecycle of entire suite execution. Values are cleared after entire suite execution. Warning: SuiteStore is not advised to be used when executing specs in parallel. The values are not retained between parallel streams of execution.
Listing 13.26: Java // Import Package import com.thoughtworks.gauge.datastore.*;
// Adding value DataStore suiteStore= DataStoreFactory.getSuiteDataStore(); suiteStore.put("element-id", "455678");
// Fetching value DataStore suiteStore= DataStoreFactory.getSuiteDataStore(); String elementId=(String) suiteStore.get("element-id");
13.3. Data Store 85 Gauge Documentation, Release 0.9.8
Listing 13.27: Javascript // Adding value DataStore suiteStore = gauge.dataStore.suiteStore.put(key, value); // Fetching value DataStore specStore = gauge.dataStore.suiteStore.get(key);
Listing 13.28: python // Import Package import from getgauge.python import DataStoreFactory // Adding value DataStore suiteStore= DataStoreFactory.suite_data_store().put(key, value)
// Fetching value DataStore specStore= DataStoreFactory.suite_data_store().get(key)
Listing 13.29: Ruby // Adding value suite_store= DataStoreFactory.suite_datastore; suite_store.put("element-id","455678");
// Fetching Value suite_store= DataStoreFactory.suite_datastore; element_id= suite_store.get("element-id");
13.4 Taking Custom Screenshots
• By default gauge captures the display screen on failure if this feature has been enabled. • If you need to take CustomScreenshots (using webdriver for example) because you need only a part of the screen captured, this can be done by implementing the ICustomScreenshotGrabber (IScreenGrabber in C#) interface;
Note: If multiple custom ScreenGrabber implementations are found in classpath then gauge will pick one randomly to capture the screen. This is because Gauge selects the first ScreenGrabber it finds, which in turn depends on the order of scanning of the libraries.
Listing 13.30: C# //Using Webdriver public class CustomScreenGrabber: IScreenGrabber{
// Return a screenshot byte array public byte[] TakeScreenshot(){ var driver= DriverFactory.getDriver(); return((ITakesScreenshot) driver).GetScreenshot().AsByteArray; } }
86 Chapter 13. Language Features Gauge Documentation, Release 0.9.8
Listing 13.31: Java // Using Webdriver public class CustomScreenGrabber implements ICustomScreenshotGrabber{ // Return a screenshot byte array public byte[] takeScreenshot(){ WebDriver driver= DriverFactory.getDriver(); return((TakesScreenshot) driver).getScreenshotAs(OutputType.BYTES); }
}
Listing 13.32: Javascript gauge.screenshotFn= function(){ return "base64encodedstring"; };
Listing 13.33: Python from getgauge.python import screenshot @screenshot def take_screenshot(): return"base64encodedstring"
Listing 13.34: Ruby # Using Webdriver Gauge.configure do|config| # Return a screenshot byte array config.screengrabber=->{ driver.save_screenshot('/tmp/screenshot.png') return File.binread("/tmp/screenshot.png") } end
13.5 Custom messages in reports
Custom messages/data can be added to execution reports using the below API from the step implementations or hooks. These messages will appear under steps in the execution reports.
Listing 13.35: C# GaugeMessages.WriteMessage("Custom message for report"); var id= "4567"; GaugeMessages.WriteMessage("User id is {0}", id);
Listing 13.36: Java Gauge.writeMessage("Custom message for report"); String id= "4567"; Gauge.writeMessage("User id is %s", id);
13.5. Custom messages in reports 87 Gauge Documentation, Release 0.9.8
Listing 13.37: Javascript gauge.message("Custom message for report");
Listing 13.38: Python from getgauge.python import Messages
Messages.write_message("Custom message for report")
Listing 13.39: Ruby Gauge.write_message("Custom message for report") id="4567" Gauge.write_message("User id is"+ id)
13.6 Enum as Step parameter
The constant values of an Enum data type can be used as parameters to a Step. However, the type of parameter should match the Enum name itself in step implementation. Step:
* Navigatetowards"SOUTH"
Implementation:
Listing 13.40: Java public enum Direction{ NORTH, SOUTH, EAST, WEST;}
@Step("Navigate towards ") public void navigate(Direction direction){ // code here }
13.7 Continue on Failure
The default behaviour in Gauge is to break execution on the first failure in a step. So, if the first step in a scenario fails, the subsequent steps are skipped. While this works for a majority of use cases, there are times when you need to execute all steps in a scenario irrespective of whether the previous steps have failed or not. To address that requirement, Gauge provides a way for language runners to mark steps as recoverable, depending on whether the step implementation asks for it explicitly. Each language runner uses different syntax, depending on the language idioms, to allow a step implementation to be marked to continue on failure.
Listing 13.41: C# // The ``[ContinueOnFailure]`` attribute tells Gauge to continue executing others // steps even if the current step fails. public class StepImplementation{ [ContinueOnFailure]
88 Chapter 13. Language Features Gauge Documentation, Release 0.9.8
[Step("Say to ")] public void HelloWorld(string greeting, string name){ // If there is an error here, Gauge will still execute next steps }
}
Listing 13.42: Java // The ``@ContinueOnFailure`` annotation tells Gauge to continue executing other // steps even if the current step fails. public class StepImplementation{ @ContinueOnFailure @Step("Say to ") public void helloWorld(String greeting, String name){ // If there is an error here, Gauge will still execute next steps }
}
Listing 13.43: Javascript // The ``@ContinueOnFailure`` annotation tells Gauge to continue executing other // steps even if the current step fails. gauge.step("Say to .",{ continueOnFailure: true}, function
˓→(greeting,product){ });
Listing 13.44: Python // The ``@ContinueOnFailure`` annotation tells Gauge to continue executing other // steps even if the current step fails.
@continue_on_failure([RuntimeError]) @step("Say to ") def step2(greeting,product): pass
Listing 13.45: Ruby # The ``:continue_on_failure => true`` keyword argument # tells Gauge to continue executing other steps even # if the current step fails. step 'Say to ', :continue_on_failure=> true do|greeting, name| # If there is an error here, Gauge will still execute next steps end
Continue on Failure can take an optional parameter to specify the list of error classes on which it would continue to execute further steps in case of failure. This is currently supported only with the following runners.
13.7. Continue on Failure 89 Gauge Documentation, Release 0.9.8
Listing 13.46: Java @ContinueOnFailure({AssertionError.class, CustomError.class}) @Step("hello") public void sayHello(){ // code here }
@ContinueOnFailure(AssertionError.class) @Step("hello") public void sayHello(){ // code here }
@ContinueOnFailure @Step("hello") public void sayHello(){ // code here }
Listing 13.47: Python @continue_on_failure([RuntimeError]) @step("Step 2") def step2(): pass
In case no parameters are passed to @ContinueOnFailure, on any type of error it continues with execution of further steps by default. This can be used to control on what type of errors the execution should continue, instead of just continuing on every type of error. For instance, on a RuntimeException it’s ideally not expected to continue further. Whereas if it’s an assertion error, it might be fine to continue execution.
Note: • Continue on failure comes into play at post execution, i.e. after the step method is executed. If there is a failure in executing the step, ex. parameter count/type mismatch, Gauge will not honour the ContinueOnFailure flag. • Continue on failure does not apply to hooks. Hooks always fail on first error. • Step implementations are still non-recoverable by default and Gauge does not execute subsequent steps upon failure. To make a step implementation continue on failure, it needs to be explicitly marked in the test code. • There is no way to globally mark a test run to treat all steps to continue on failure. Each step implementation has to be marked explicitly. • If an implementation uses step aliases, marking that implementation to continue on failure will also make all the aliases to continue on failure. So, if a step alias is supposed to break on failure and another step alias is supposed to continue on failure, they need to be extracted to two different step implementations.
90 Chapter 13. Language Features CHAPTER 14
Reports
The test results report should be easy to comprehend and should be useful for all the stakeholders.
14.1 HTML Reports
Reports are generated using html-report plugin. By default html-report is added to the project. When the specs are executed, the html report is generated in reports directory in the project by default. Notes • A comprehensive test results report template prepared in a html format providing the overall summary with drill down of the test cases executed and effort spent during the testing for each stage and feature. • It provides the details for the defects found during the run. • It indicates the tests by color code - failed(red), passed(green) and skipped(grey). • The failure can be analyzed with the stacktrace and screenshot(captures unless overwritten not to). • The skipped tests can be analyzed with the given reason. • Custom messages in reports allows users to add messages at runtime.
14.1.1 Configuration
The HTML report plugin can be configured by the properties set in the env/default.properties file in the project. The configurable properties are: gauge_reports_dir • Specifies the path to the directory where the execution reports will be generated. • Should be either relative to the project directory or an absolute path. By default it is set to reports directory in the project
91 Gauge Documentation, Release 0.9.8
overwrite_reports • Set to true if the reports must be overwritten on each execution maintaining only the latest execution report. • If set to false then a new report will be generated on each execution in the reports directory in a nested time-stamped directory. Default value is true GAUGE_HTML_REPORT_THEME_PATH • Specifies the path to the custom reports directory. • Should be either relative to the project directory or an absolute path. By default, default theme shipped with gauge is used.
14.1.2 Report re-generation
If report generation fails due to some reason, we don’t have to re-run the tests again. The html-report plugin now generates a last_run_result.json file in the root of the reports directory. There is also a symlink to the html-report executable in the same location. To regenerate the report • Navigate to the reports directory • run ./html-report –input=last_run_result.json –output=”/some/path” Note: The output directory is created. Take care not to overwrite an existing directory While regenerating a report, the default theme is used. A custom can be used if --theme flag is specified with the path to the custom theme.
14.2 XML Report
XML Report plugin creates JUnit XML test result document that can be read by tools such as Go, Jenkins. When the specs are executed, the xml report is generated in reports directory in the project. The format of XML report is based on JUnit XML Schema Sample XML Report Document :
˓→hostname="INcomputer.local">
14.2.1 Installation
To install XML Report plugin :
92 Chapter 14. Reports Gauge Documentation, Release 0.9.8
gauge install xml-report
To install a specific version of XML report plugin use the --version flag. gauge install xml-report --version 0.0.2
Offline Installation : If plugin should be installed from a zipfile instead of downloading from plugin repository, use the --file or -f flag. gauge install xml-report --file ZIP_FILE_PATH
Download the plugin zip from the Github Releases
14.2.2 Configuration
To add XML report plugin to your project, run the following command : gauge install xml-report
The XML report plugin can be configured by the properties set in the env/default.properties file in the project. The configurable properties are: gauge_reports_dir Specifies the path to the directory where the execution reports will be generated. • Should be either relative to the project directory or an absolute path. By default it is set to reports directory in the project overwrite_reports Set to true if the reports must be overwritten on each execution hence maintaining only the latest execution report. • If set to false then a new report will be generated on each execution in the reports directory in a nested time-stamped directory. Default value is true
14.3 Spectacle
This is a Gauge plugin that generates static HTML from Specification/Markdown files. Ability to filter specifications and scenarios are available.
14.3.1 Installation
To install: gauge install spectacle
To install a specific version of spectacle plugin use the --version flag. gauge install spectacle --version 0.0.2
14.3. Spectacle 93 Gauge Documentation, Release 0.9.8
Offline Installation: If plugin should be installed from a zip file instead of downloading from plugin repository, use the --file or -f flag. gauge install spectacle --file ZIP_FILE_PATH
Download the plugin zip from the Github Releases
14.3.2 Usage
Run the following command to export to HTML in a Gauge project gauge docs spectacle
Sample Spectacle Report
Fig. 14.1: Sample spectacle report
Filter Specification/Scenario based on Tags Tags allow you to filter the specs and scenarios. Add the tags to the textbox in the report to view all the specs and scenarios which are labeled with certain tags. Tag expressions with operators |, &, ! are supported. In the following image, the specs/scenarios are filtered using a tag expression(refactoring & !api).
94 Chapter 14. Reports Gauge Documentation, Release 0.9.8
Fig. 14.2: Filter Specification/Scenario
14.3. Spectacle 95 Gauge Documentation, Release 0.9.8
14.4 Flash
Real-time execution reporting plugin! Watch test runs go green or red. Install it in your CI/CD setup and connect to Flash using your browser to see what your test suites are doing.
14.4.1 Installation
To install Flash plugin : gauge install flash
To install a specific version of the plugin use the --version flag. gauge install flash --version 0.0.1
Offline Installation : If plugin should be installed from a zipfile instead of downloading from plugin repository, use the --file or -f flag. gauge install flash --file ZIP_FILE_PATH
Download the plugin zip from the Github Releases
14.4.2 Usage
To add Flash plugin to your project, run the following command : gauge install flash
Execute specs and open the URL in browser shown in console output.
14.4.3 Configuration
The Flash plugin can be configured by the properties set in the env/default.properties file in the project. The configurable properties are: FLASH_SERVER_PORT To use a specific port, set FLASH_SERVER_PORT={port} as environment variable or in env/default/ flash.properties file.
96 Chapter 14. Reports CHAPTER 15
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.
15.1 Global
1 # set to a url, which acts as plugin repository for Gauge.
2 gauge_repository_url= https://downloads.gauge.org/plugin
3
4 # set to a url, which holds version information of Gauge.
5 # This is used to determine if an update is available.
6 gauge_update_url= https://downloads.gauge.org/gauge
7
8 # set to an url, which acts as template repository for Gauge.
9 gauge_templates_url= https://downloads.gauge.org/templates
10
11 # sets the timeout in milliseconds for making a
12 # connection to the language runner.
13 runner_connection_timeout= 30000
14
15 # sets the timeout in milliseconds for making a connection
16 # to plugins (except language runner plugins).
17 plugin_connection_timeout= 10000
18
19 # sets the timeout in milliseconds for a plugin to stop
20 # after a kill message has been sent.
21 plugin_kill_timeout= 10000
22
23 # sets the timeout in milliseconds for requests from the
24 # language runner.
25 # If the size of the project is too big, Gauge may timeout before the
26 # runner returns the response message. This value can be configured
97 Gauge Documentation, Release 0.9.8
27 # accordingly.
28 runner_request_timeout= 10000
15.2 Local (Project level)
Certain properties can be configured in env/default/default.properties, which overrides the default prop- erties and are scoped only to the current project. These are key value pairs.
1 # The path to the gauge reports directory. Should be either relative to
2 # the project directory or an absolute path
3 gauge_reports_dir= reports
4
5 # Set as false if gauge reports should not be overwritten
6 # on each execution.
7 # If set to true, a new time-stamped directory will be
8 # created on each execution.
9 overwrite_reports= true
10
11 # Set to false to disable screenshots on failure in reports.
12 screenshot_on_failure= false
13
14 # The path to the gauge logs directory. Should be either relative to the
15 # project directory or an absolute path
16 logs_directory= GaugeLogs
17
18 # Specify the level at which cached objects should get removed while
19 # execution.
20
21 # Possible values for this property are 'suite', 'spec' or 'scenario'.
22 # default: 'scenario'.
23 gauge_clear_state_level= spec
24 # The above clears the objects after the execution of each specification, so
25 # that new objects are created for next execution.
26
27 # Set to false to disable screenshots on failure in reports.
28 screenshot_on_failure= true
29
30 # Path to generate custom report theme.
31 # Should be either relative to the project directory or an absolute path.
32 # Default theme is used if not set
33 GAUGE_HTML_REPORT_THEME_PATH= custom_theme_path
34
35 # sets the excluded dirs for gauge.
36 # Gauge always looks for concepts in the whole project, folders starting
37 # with dot(.) are excluded and a user can add folders to the excluded
38 # folders list by passing a comma separeted paths of folder.Paths can be
39 # relative to the path of directory or absolute.
40 gauge_exclude_dirs= src/test,bin
15.3 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.
98 Chapter 15. Configuration Gauge Documentation, Release 0.9.8
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 environ- ment 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.
15.3.1 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
15.3.2 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
15.3.3 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.
15.3. Environments 99 Gauge Documentation, Release 0.9.8
• 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 /env/default is not present, Gauge will set the default env variables with values mentioned in the table above. – If /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 /env/java_ci is not present, Gauge will end with a non-zero exit code. – If /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.
15.4 Language Plugin
15.4.1 General
Configuration properties set here will be available to the test execution as environment variables. Please see Environ- ments for more details. Properties are defined in the following format.
sample_key = sample_value
100 Chapter 15. Configuration Gauge Documentation, Release 0.9.8
15.4.2 Java
Java Specific configuration changes can be made in the env/default/java.properties file.
1 # Specify an alternate Java home if you want to use a custom version.
2 gauge_java_home= PATH_TO_JAVA_HOME
3
4 # Use this property if you need to override the build path for the
5 # project.
6 # Note: IntelliJ out directory will be usually auto-detected.
7 gauge_custom_build_path= PATH_TO_CUSTOM_BUILDPATH
8
9 # Specify the directory where additional libraries are kept.
10 # You can specify multiple directory names separated with a comma `,`
11 # `libs` directory in the gauge project is added by default. 12 gauge_additional_libs= libs/ *, PATH_TO_NEW_LIBRARY 13
14 # Specify the JVM arguments passed to java while launching.
15 gauge_jvm_args=
15.4.3 Javascript
Javascript Specific configuration changes can be made in the env/default/js.properties file.
1 # Use this property if you need to override the timeout of step
2 test_timeout= 10000
15.4.4 Python
Python Specific configuration changes can be made in the env/default/python.properties file.
1 # Override this if you want to use a different command
2 GAUGE_PYTHON_COMMAND= python
Note: CSharp and Ruby language runners do not hold any configuration beyond what is listed in default properties.
15.5 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.
15.5.1 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
15.5. HTTP Proxy 101 Gauge Documentation, Release 0.9.8
15.5.2 With Authentication
If authentication is required, set the environment variable HTTP_PROXY to proxy server URL along with the creden- tials. export HTTP_PROXY=http://username:[email protected]:5678
15.6 Build tools
You can use Gauge with any of the build tools that you like. Here are the sample build files for 1. Maven 2. Gradle 3. Ant
15.6.1 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.
4.0.0
com.foo my-gauge-tests 1.0-SNAPSHOT
102 Chapter 15. Configuration Gauge Documentation, Release 0.9.8
com.thoughtworks.gauge gauge-java 0.2.2 test
${project.basedir}/src/test/java com.thoughtworks.gauge.maven gauge-maven-plugin 1.0.3 test specs execute
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
15.6. Build tools 103 Gauge Documentation, Release 0.9.8
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
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=specsGauge specs directory path. Required for executing specs. Takes a comma separeted list of spec files/directories. tags -Dtags=tag1 & Filter specs by specified tag expression. tag2 inParallel-DinParallel=trueExecute 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.
15.6.2 Gradle
Use the gauge-gradle-plugin to execute specifications in your Gauge java project and manage dependencies using Gradle.
104 Chapter 15. Configuration Gauge Documentation, Release 0.9.8
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
15.6. Build tools 105 Gauge Documentation, Release 0.9.8
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' }
106 Chapter 15. Configuration Gauge Documentation, Release 0.9.8
} }
15.6.3 Ant Task
Gauge specs can be invoked via Ant by adding the below configuration in your build.xml
Listing 15.1: build.xml
15.6. Build tools 107 Gauge Documentation, Release 0.9.8
108 Chapter 15. Configuration CHAPTER 16
Troubleshooting
16.1 Logs
• Gauge logs are created under the logs directory in the project. • Two log files are created – gauge.log - logs for test execution – api.log - logs for gauge core api exposed for plugins • To customize logs directory set the logs_directory property in the env/default/default. properties file to a custom logs directory path. logs_directory = my_logs_dir
• For non-project specific actions like plugin installation log files are created in the following location.
Windows - %APPDATA%\gauge\logs MacOS* - /.gauge/logs Linux - /.gauge/logs
16.2 Gauge Installation
16.2.1 Windows
• The default installation location is %ProgramFiles%\gauge. • gauge_install_location\bin should be in PATH to run from command line. • Gauge plugins are installed at %APPDATA%\gauge\plugins directory. • APPDATA directory is usually located at C:\Users\USER_NAME\AppData\Roaming.
109 Gauge Documentation, Release 0.9.8
16.2.2 Mac OS X
• The default installation location is /usr/local/. • usr/local/bin/ or custom_install_location/bin should be in PATH. • Run brew update before installing the latest version of gauge. • If installation is failing Upgrade homebrew • Gauge plugins are installed under ~/.gauge/plugins directory.
16.2.3 Linux
• The default installation location is /usr/local/. • usr/local/bin/ or custom_install_location/bin should be in PATH. • Gauge plugins are installed under ~/.gauge/plugins directory.
16.3 Plugin installation
• If plugin installation fails due to a network connection issue, you can manually download the plugin dis- tributable zip and install it using the -f flag.
gauge install plugin_name -f path_to_zip_file
Example:
gauge install html-report -f html-report-1.0.3-darwin.x86.zip
• Find the plugin zip files under Releases section of the plugin github repositories. See the gauge plugin list for plugin repositories details.
16.3.1 Plugins directory
Plugins are installed in the .gauge/plugins directory in user’s home. You can check this directory to manually install / uninstall plugins as well as to verify the installed plugins. The plugin installation directory for various operating systems are listed below. • Windows: %APPDATA%\.gauge\plugins • Mac OS X: ~/.gauge/plugins • Linux: ~/.gauge/plugins
16.3.2 Custom Plugin Install location
By default the plugins are stored at %APPDATA%\gauge\plugins for windows and ~/.gauge/plugins in mac and linux. To install plugins at different location, set GAUGE_HOME environment variable to the custom location. After setting the GAUGE_HOME env, run the install command. The plugin will get installed at the GAUGE_HOME custom location.
110 Chapter 16. Troubleshooting Gauge Documentation, Release 0.9.8
16.4 Execution
It is advised to use the latest version of gauge and gauge plugins. See our download page for links to latest installation
16.4.1 Validation Errors
[WARN] Validation failed. The following steps have errors ...
These generally occur if step implementation is not found for a particular step. • Ensure the step implementation for the step has been added. • The step template marking the step in code is case sensitive and should match the step usage in the spec file.
16.4.2 Compatibility errors
Failed to start a runner. Compatible runner version to 0.0.7 not found
• The language plugin installed is not compatible with the gauge version installed. • Run gauge install language_NAME to install the latest compatible version. See plugin installation for more details
16.4.3 Execution Errors
Error: too many open files
• This error occurs when the upper limit to open the number of files is too low. To fix the error, increase the upper limit by adding the command ulimit -S -n 2048 to your ~/.profile file and relogin.
16.5 Intellij idea plugin
It is advised to use the latest version of gauge and Intellij-gauge.
16.5.1 Intellij idea Errors
Gauge API error
Could not start gauge api: Could not find executable in PATH or GAUGE_ROOT. Gauge is
˓→not installed.
This can occur because of following reasons : • Gauge is not installed • Gauge is installed at custom location and custom_install_location/bin is not in PATH. To Solve this : • If gauge is not installed, install gauge.
16.4. Execution 111 Gauge Documentation, Release 0.9.8
• If gauge is installed at custom location, add custom_install_location/bin to PATH • On custom installation location Set GAUGE_ROOT to custom_install_location • Restart Intellij
Steps marked as unimplemented
If steps have implementation code and are still marked as unimplemented: • Ensure that src/test/java directory is marked as test sources root in the project. Right click on the src/ test/java directory and select Mark Directory as -> Test sources root • Ensure the project is compiling. Press ctrl/cmd + F9 to build project or select Build -> Make project. • Ensure Module SDK is set to a valid JDK under Module settings. • Restart Intellij or close and reopen the project.
Check dependencies
For a gauge maven project
• The gauge-java dependency should be added in the pom.xml • Enable auto-import for the project. Under File > Settings > Maven > Importing, mark the check- box Import Maven projects automatically.
For a simple gauge java project
• Under Project Settings -> Modules select the gauge module. Under the dependencies tab should be gauge-lib and project-lib. • If not present restart Intellij or close and re-open project. They should be added
Project Build failing with compilation error but the Java Files do not mark any errors.
• The project compilation fails however the java files do not mark any errors in the file. • This is a specific issue with Java <= 1.7 on Windows. • To resolve set -Duser.home=USER_HOME in the IDEA_INSTALLATIONbinidea.exe.vmoptions file.
-Duser.home=C:\\Users\\
• See the Intellij idea forum post for more details
112 Chapter 16. Troubleshooting CHAPTER 17
Examples
17.1 Basic
Follow the instructions in Quick start
17.2 Web Application
These examples illustrate the use of Gauge with a browser driver. Clone the github project on your system. Follow the instructions mentioned on the project’s page for setup.
Features Java C# Ruby Groovy Web app using Selenium Yes Yes Yes Yes Web app using Sahi Yes No No No
113 Gauge Documentation, Release 0.9.8
114 Chapter 17. Examples CHAPTER 18
HOWTOs
18.1 Integrating Gauge with CI/CD tools
Gauge can be easily integrated with any Continuous Integration environment. Since Gauge supports first class command line, invoking it from any CI/CD tool is very straightforward. Steps to Integrate Gauge with CI tool: • Install the Gauge and language plugin on CI machine • Add gauge commands as tasks in CI to run tests. For example, to run the specs use gauge run specs • If you want to run specific instance of gauge on CI, add it in PATH env or use absolute path of specific instance. • Gauge returns html-reports, console output as result of execution which can be configured to view on CI.
18.1.1 HOWTO: Integrating Gauge with GoCD
GoCD is a continuous integration and deployment tool.
Setup
• Setup a new pipeline on Go
115 Gauge Documentation, Release 0.9.8
• Download and Install Gauge on the Go Agents • Install the required gauge language plugin on the Go agents.
Tips on Installation
• Gauge is installed system wide by default and not user wide. However, plugins are installed per user. So plugins should be installed via user account with which the Go agent executes. Refer default install location of Gauge and its plugins here. • Alternately, you can set custom location for plugins so that its accessible to Go agent running as a different user.
Create execution task
• Create a new task which will run gauge run specs. • If you want to run only a subset of specs, you can use Tagged Execution. Eg. gauge run --tags "tag1 & tag2" specs • Adding a flag -p runs them using Parallel Execution. • Run against specific Environments using the --env flag • See the Help for list of all the flags that can be used.
Fig. 18.1: configuring
Reports
• Gauge generates html-reports after execution which can be configured in Go by adding a new artifact in Arti- facts tab. • Artifacts can be viewed in the artifacts tab.
116 Chapter 18. HOWTOs Gauge Documentation, Release 0.9.8
Fig. 18.2: artifact
Fig. 18.3: artifact
18.1. Integrating Gauge with CI/CD tools 117 Gauge Documentation, Release 0.9.8
• Console output can be seen while execution of job and reports can be seen after execution.
Fig. 18.4: console
• You can also add a custom tab to view your html reports generated.
18.1.2 HOWTO: Integrating Gauge with TeamCity
• Download and Install Gauge on the agents. Read more on installing Gauge here. • Install the required Gauge language plugins on the agents as: gauge install
Tips on Installation
• Gauge is installed system wide by default and not user wide. However, plugins are installed per user. So plugins should be installed via user account with which the TeamCity agent executes. Refer default install location of Gauge and its plugins here. • Alternately, you can set custom location for plugins so that its accessible to TeamCity agent running as a different user.
Create execution task
• Create a new project in TeamCity pointing to Gauge project repository URL. • Add a build step which will run gauge run specs. image:: images/TeamCity_buildStep.png
118 Chapter 18. HOWTOs Gauge Documentation, Release 0.9.8
• If you want to run only a subset of specs, you can use Tagged Execution. Eg. gauge run --tags "tag1 & tag2" specs • Adding a flag -p runs them using Parallel Execution. • Run against specific Environments using the --env flag. • See the Help for list of all the flags that can be used.
Reports
• Gauge generates html-reports after execution which can be configured in TeamCity by adding a new artifact in Artifacts tab. These artifacts can be viewed/downloaded from the artifacts tab.
Fig. 18.5: artifact
• You can also add a custom tab to view your html reports generated. To add custom tab, go to Project Settings -> Report tabs -> Add a new build report tab. • Console output can be seen while execution of steps and reports can be seen after execution.
18.1.3 HOWTO: Integrating Gauge with Travis CI
Travis CI is a hosted, distributed continuous integration service used to build and test software projects hosted at GitHub. • Login to Travis CI and goto accounts menu. • Choose your project repository to be built and flick that switch on.
Creating tasks
• Create a .travis.yml file in your project root. • Add these lines in .travis.yml according to the platform on which you want to build.
18.1. Integrating Gauge with CI/CD tools 119 Gauge Documentation, Release 0.9.8
Fig. 18.6: reportsTab
120 Chapter 18. HOWTOs Gauge Documentation, Release 0.9.8
Listing 18.1: OS X language: - language_name
os: - osx
install: - brew install gauge - gauge install html-report
script:'gauge run specs'
sudo: false
Listing 18.2: Linux language: - language_name os: - linux install: - sudo apt-key adv --keyserver hkp://pool.sks-keyservers.net --recv-keys
˓→023EDB0B - echo deb https://dl.bintray.com/gauge/gauge-deb stable main| sudo tee -a/
˓→etc/apt/sources.list - sudo apt-get update - sudo apt-get install gauge - gauge install html-report
script:'gauge run specs'
sudo: true
• If you want to run only a subset of specs, you can use Tagged Execution. Example: add script: gauge run --tags "tag1 & tag2" specs in your .travis.yml. • Adding a flag -p runs them using Parallel Execution. Example: script: gauge run -p specs in your .travis.yml. • Run against specific Environments using the --env flag. • See the Help for list of all the flags that can be used.
Reports
• Goto your project on travis and see the console output. • Gauge generates html-report after execution whose location can be set by environment variable gauge_reports_dir. This defaults to reports directory in the Gauge project. • You can upload Gauge execution reports to your choice of hosted web server. Read more for uploading artifacts.
18.1.4 HOWTO: Integrating Gauge with CircleCI
CircleCI is a cloud hosted, continuous integration and delivery platform.
18.1. Integrating Gauge with CI/CD tools 121 Gauge Documentation, Release 0.9.8
Configure gauge as a dependency in circle.yml and add xml report plugin to your gauge project.
Listing 18.3: Linux dependencies: pre: - sudo apt-key adv --keyserver hkp://pool.sks-keyservers.net --recv-keys 023EDB0B - echo deb https://dl.bintray.com/gauge/gauge-deb stable main| sudo tee -a /etc/
˓→apt/sources.list - sudo apt-get update - sudo apt-get install gauge
Running tests and publishing reports
Configure circle.yml to run tests in the specs folder and publish junit results. test: post: - gauge install - gauge run specs - mkdir -p $CIRCLE_TEST_REPORTS/junit/ - cp ./reports/xml-report/result.xml $CIRCLE_TEST_REPORTS/junit/
18.2 Gauge tests on docker
Gauge can be easily installed on Docker container.
18.2.1 Prerequisites
• Docker
18.2.2 Docker image for Gauge
• Create a Dockerfile file in your project root.
122 Chapter 18. HOWTOs Gauge Documentation, Release 0.9.8
• Add these lines in Dockerfile according to the platform on which you want to build.
Listing 18.4: DockerFile FROM ubuntu
# Install Java. RUN apt-get update&& apt-get install -q -y\ default-jdk\ sudo\ apt-transport-https
# Install gauge RUN apt-key adv --keyserver hkp://pool.sks-keyservers.net --recv-keys 023EDB0B&&\ echo deb https://dl.bintray.com/gauge/gauge-deb stable main| sudo tee -a /etc/
˓→apt/sources.list
RUN apt-get update&& apt-get install gauge
# Install gauge plugins RUN gauge install java&&\ gauge install screenshot
ENV PATH=$HOME/.gauge:$PATH
18.2.3 Run Gauge specs on Docker
• Build the docker image tagged as test docker build . -t test • Mount the docker image with the and run the specs in the container docker run -v pwd:/ -w=”/” test gauge run specs
• FAQs – Installation
* Where’s the gauge executable installed by default? * Where are the plugins installed? * What is GAUGE_HOME? * How can I manually install a plugin? – Execution
* Why do I get validation failure warning? * Why does the runner fail to start? * Why are there too many open files? * Why can’t gradle execute gauge specs, despite adding a task as per the document? – IDE
* Configuration · How can I increase the language runner timeout?
18.2. Gauge tests on docker 123 Gauge Documentation, Release 0.9.8
* Logs · Where does gauge log the test execution output. warnings, validation results etc? · Where can I find gauge core API logs for debugging IDE plugins? · How can I customize the log directory location? · Where does gauge non project specific logs like plugin installation etc.? – JS FAQs
* How to · Debug without IDE · Requirements · How it works · }); · Caveats – Python FAQs
* Errors · ImportError: No module named getgauge · Failed to start gauge API: Plugin ‘python’ not installed on following locations : [PATH] · ImportError: No module named step_impl.<file_name>
* How to · Change/Rename default step implementation(step_impl) directory · Use different version of python while running specs · Debug without IDE
124 Chapter 18. HOWTOs CHAPTER 19
FAQs
19.1 Installation
19.1.1 Where’s the gauge executable installed by default?
OS Path Windows %ProgramFiles%\gauge\bin MacOS/Linux /usr/local/bin
19.1.2 Where are the plugins installed?
OS Path Windows %APPDATA%\gauge\plugins MacOS/Linux ~/.gauge/plugins
19.1.3 What is GAUGE_HOME?
GAUGE_HOME environment variable can be used to customize config files and plugins installation location.
19.1.4 How can I manually install a plugin?
Download the plugin distributable zip file and install it using the -f flag. gauge install plugin_name -f path_to_zip_file
125 Gauge Documentation, Release 0.9.8
19.2 Execution
19.2.1 Why do I get validation failure warning?
[WARN] Validation failed. The following steps have errors ...
Check if the step is implemented. The steps are case sensitive, check if the cases match.
19.2.2 Why does the runner fail to start?
Failed to start a runner. Compatible runner version to 0.0.7 not found
The language plugin is not compatible with the gauge version installed. Run gauge install language_name
19.2.3 Why are there too many open files?
Error: too many open files
The upper limit to the number of open files is low. Increase the upper limit by adding a command ulimit -S -n 2048 to you ~/.profile. Don’t forget to re-login for the changes to take effect.
19.2.4 Why can’t gradle execute gauge specs, despite adding a task as per the document?
* What went wrong: A problem occurred evaluating root project 'INDYGauge'. > Could not get unknown property 'GaugeTask' for root project 'INDYGauge' of type org.
˓→gradle.api.Project.
This can happen when gradle is unable to recognize the GaugeTask. Try using the fully qualified name for GaugeTask as below: .. code-block:: console task customGauge(type: com.thoughtworks.gauge.gradle.GaugeTask) { gauge { specsDir = ‘specs’ env = ‘default’ tags = ‘tag1’ inParallel = true nodes = 4 additionalFlags = ‘–verbose’ } }
19.3 IDE
19.3.1 Configuration
126 Chapter 19. FAQs Gauge Documentation, Release 0.9.8
Note: Gauge specific properties are stored in gauge.properties under gauge configuration folder. Refer to Gauge Properties.
How can I increase the language runner timeout?
By setting
runner_connection_timeout= 3000
19.3.2 Logs
Where does gauge log the test execution output. warnings, validation results etc?
You’ll find the logged at logs/gauge.log in your projects directory.
Note: logs is the default location for log files. This can be changed using logs_directory in project’s proper- ties.
Where can I find gauge core API logs for debugging IDE plugins?
You’ll find that at logs/api.log in your projects directory.
Note: logs is the default location for log files. This can be changed using logs_directory in project’s proper- ties.
How can I customize the log directory location?
You can specify a custom directory by changing the logs_directory property under env/default/ default.properties Refer to project’s properties.
logs_directory= my_custom_log_directory
Where does gauge non project specific logs like plugin installation etc.?
OS Path Windows %APPDATA%\gauge\logs MacOS / Linux ~/.gauge/logs
19.3. IDE 127 Gauge Documentation, Release 0.9.8
19.4 JS FAQs
19.4.1 How to
Debug without IDE gauge-js supports debugging your test implementation code using node-inspector.
Requirements
Ensure you have the latest Chrome browser and node-inspector installed. Please consult the node-inspector documen- tation for installation instructions. Ensure that the binaries node-debug and node-inspector are available on PATH. Starting gauge-js with debugger You can do either of these: Set the DEBUG key to true in env//js.properties file in your gauge project. Set the environment variable DEBUG=true when calling gauge. Like: DEBUG=true gauge specs/. This needs gauge v0.3.2 or newer.
How it works
Setting the debug option will launch the runner code through node-debug. It will start node-inspector, launch Chrome DevTools and pause on the first line of execution. You will need to continue execution to let gauge carry on with its execution. You can set debugger; inside step implementation or hook callbacks to pause execution in the debugger. This retains the gauge context and gives you a full blown debugger to debug your test implementations. Example: ‘‘‘ gauge.step(“There are vowels.”, function (num) { debugger; assert.equal(num, 5);
});
This will pause the debugger when this step’s callback is executed by gauge-js.
Caveats
The debugger exposes entire gauge-js runner code. You need to be quick enough to hit continue in the browser when node-inspector launches. If this takes too long, gauge will timeout connecting to the API. A workaround for this is to increase the runner_connection_timeout property to an acceptable value.
128 Chapter 19. FAQs Gauge Documentation, Release 0.9.8
19.5 Python FAQs
19.5.1 Errors
ImportError: No module named getgauge
Installing the getgauge package using pip should fix this. You can install the package by running the following command
[sudo] pip install getgauge
Failed to start gauge API: Plugin ‘python’ not installed on following locations : [PATH]
Installing the gauge-python plugin should fix this. You can install the plugin by running the following command
gauge--install python
Make sure you have the getgauge package. If you don’t have, run the following command to install
[sudo] pip install getgauge
For more details, refer Installation docs.
ImportError: No module named step_impl.<file_name>
This error happens on older versions of Python(2.7, 3.2). Create step_impl/__init__.py to fix this.
19.5.2 How to
Change/Rename default step implementation(step_impl) directory
Create python.properties file in the /env/default directory and add the following line to it.
STEP_IMPL_DIR= PATH_TO_STEP_IMPLEMENTATION_DIR
Note: The path specified in STEP_IMPL_DIR property should be relative to project root.
Use different version of python while running specs
By default the language runner uses python command to run specs. To change the default behaviour, add GAUGE_PYTHON_COMMAND property to the python.properties file in the /env/ default directory.
GAUGE_PYTHON_COMMAND= GAUGE_PYTHON_COMMAND= python3 GAUGE_PYTHON_COMMAND= python2
19.5. Python FAQs 129 Gauge Documentation, Release 0.9.8
Debug without IDE
Gauge-Python supports debugging your test implementation code using pbd.
import pdb
The typical usage to break into the debugger from a running program is to insert
pdb.set_trace()
Execution will stop where it finds the above statement and you can debug.
130 Chapter 19. FAQs CHAPTER 20
Errors
20.1 GAUGE-VS-001 : Gauge API Not Started
Gauge-Visualstudio support requires gauge.exe to run as a daemon. Hence, Gauge-Visualstudio tries to launch gauge as a child Process with the same working directory as the project. Sometimes this can fail. Here are things to watch out: 1. Ensure latest Gauge is installed and available in PATH. You can install gauge from here. 2. Ensure that the latest Gauge CSharp plugin is installed. Since you are using Gauge + VisualStudio, it is assumed that you are using Gauge + CSharp, and this requires the gauge-csharp plugin to be installed. Run gauge install csharp in your Command Prompt to get the latest plugin. 3. Verify (1) and (2) above by running gauge version in your Command Prompt. 4. Allow gauge.exe via Windows Firewall, if you have firewall enabled. You also need to allow gauge to use port range 46337-46997 in the firewall, since this is the port number that Gauge-Visualstudio uses by default. 5. If port range 46337-46997 has a conflict for some reason, or you cannot allow these ports in Windows Firewall, you can tell Gauge-Visualstudio to use a different port by setting it in Tools->Options->Gauge->API Options in Visual Studio. Ensure that the port set in this setting is white-listed in your firewall.
20.2 GAUGE-VS-002 : Incompatible Gauge Version installed.
Gauge-Visualstudio support requires gauge.exe to be above a certain minimum version of Gauge. This error indicates that the version of Gauge installed is incompatible with the Gauge VisualStudio plugin version installed. 1. Install the latest version of gauge and update your Gauge Visualstudio plugin.
131 Gauge Documentation, Release 0.9.8
20.3 GAUGE-VS-003 : Unable to read Gauge version
Gauge-Visualstudio support requires gauge.exe to be above a certain minimum version of Gauge. This error indicates that Gauge Visual Studio is unable to read the installed Gauge version. 1. Verify that the latest version of gauge is installed and available in PATH. An easy way to do this is to run gauge version in your command prompt. 2. Inspect Output Window of Visual Studio and see the log for possible actions.
132 Chapter 20. Errors CHAPTER 21
Welcome
Gauge is a light-weight cross-platform test automation tool with the ability to author test cases in the business language.
• Start Here – Quick start Get started quickly. – Long Start Go deeper into concepts and syntax. • Plugins – Language Plugins Choose a language for automation. – Reporting Plugins View results and statistics in various formats. – IDE Support Help author and maintain Gauge specs. – Explore All • Resources – Examples Reference implementation using Gauge – HOWTOs Recipes for specific use cases. • Community – Github All components of Gauge reside here! – Gitter Chat with us! – Google Groups Email us (public forum)
133
