Using Gauge¶

Gauge is a first class command line tool. This means that you can operate entirely from the command line. Or, if you prefer to use an IDE then Gauge also has excellent integration with multiple IDEs.

Command Line Interface¶

Gauge has first-class command line support. With gauge installed, list the subcommands/flags supported by running.

gauge

The command-line interface works across platforms. On GNU/Linux and OSX, you can use any terminal. On Windows, you can use cmd or Powershell.

Help¶

Since subcommands/flags get added/deprecated with versions, it is recommended to get this reference via gauge itself.

gauge help

Creating a project¶

To create or initialize a Gauge project use run

gauge init <template>

For details, see how to create a Gauge project.

Executing tests¶

Inside a Gauge project, you can execute your tests by invoking gauge with path to specifications. By convention, specifications are stored in the the ./specs/ sub-directory in the project root.

The syntax is:

gauge run [flags] <path-to-specs>

The gauge command-line utility allows multiple ways to specify the specifications to be executed. A valid path for executing tests can be path to directories that contain specifications or path to specification files or path to scenarios or a mix of any of these three methods.

To execute all the tests in a given folder specs, use

gauge run specs/

This will give a colored console output with details of the execution as well an execution summary.

Specify scenarios¶

A single scenario of a specification can be executed by specifying the line number in the span of that scenario in the spec. To execute a Admin Login scenario in the following spec use gauge run specs/login_test.spec:4 command.

Configuration
=============

Admin Login
-----------
* User must login as "admin"
* Navigate to the configuration page

This executes only the scenario present at line number 4 i.e Admin Login in login_test.spec. In the above spec, specifying line numbers 4-7 will execute the same scenario because of the span.

Multiple scenarios can be executed selectively as follows :

gauge run specs/helloworld.spec:4 specs/anotherhelloworld.spec:7

These scenarios can also belong to different specifications.

You can also specify a specific scenario or a list of scenarios to execute. To execute scenarios, gauge takes path to a specification file, followed by a colon and the line number of the scenario. You may specify any line number which the scenario spans across. For example, in the above spec file, both the below commands will run the same scenario.

gauge run specs/helloworld.spec:4 # Runs scenario 'Admin Login'
gauge run specs/helloworld.spec:6 # Runs scenario 'Admin Login'

For example, to execute the second scenario of a specification file named spec1.spec, you would do:

gauge run specs/spec1.spec:1

To specify multiple scenarios, add multiple such arguments. For example, to execute the first and third scenarios of a specification file named spec1.spec, you would do:

gauge run specs/spec1.spec:0 specs/spec1.spec:2

Specify directories¶

You can specify a single directory in which specifications are stored. Gauge scans the directory and picks up valid specification files.

For example:

gauge run specs/

You can also specify multiple directories in which specifications are stored. Gauge scans all the directories for valid specification files and executes them in one run.

For example:

gauge run specs-dir1/ specs-dir2/ specs-dir3/

Specify files¶

You can specify path to a specification files. In that case, Gauge executes only the specification files provided.

For example, to execute a single specification file:

gauge run specs/spec1.spec

Or, to execute multiple specification files:

gauge run specs/spec1.spec specs/spec2.spec specs/spec3.spec

Verbose reporting¶

By default, gauge reports at the specification level when executing tests. You can enable verbose, step-level reporting by using the --verbose flag. For example:

gauge run --verbose specs/

Errors during execution¶

Parse errors¶

This occurs if the spec or concept file doesn’t follow the expected specifications or concepts syntax.

Example:

[ParseError] hello_world.spec : line no: 25, Dynamic parameter <product> could not be resolved

List of various Parse errors:

Parse Error	Gauge Execution Behaviour
Step is not defined inside a concept heading	Stops
Circular reference found in concept	Stops
Concept heading can only have dynamic parameters	Stops
Concept should have at least one step	Stops
Duplicate concept definition found	Stops
Scenario heading is not allowed in concept file	Stops
Table doesn’t belong to any step	Ignores table,Continue
Table header cannot have repeated column values	Mark that spec as failed,Continues for others
Teardown should have at least three underscore characters	Mark that spec as failed,Continues for other
Scenario heading should have at least one character	Mark that spec as failed,Continues for other
Table header should be not blank	Mark that spec as failed,Continues for other
Multiple spec headings found in the same file	Mark that spec as failed,Continues for other
Scenario should be defined after the spec heading	Mark that spec as failed,Continues for other
Could not resolve table from file	Mark that spec as failed,Continues for other
Spec does not have any element	Mark that spec as failed,Continues for other
Spec heading not found	Mark that spec as failed,Continues for other
Spec heading should have at least one character	Mark that spec as failed,Continues for other
Dynamic param could not be resolved	Mark that spec as failed,Continues for other
Step should not be blank	Mark that spec as failed,Continues for other
Duplicate scenario definition found in the same specification	Mark that spec as failed,Continues for other

Validation Errors¶

These are errors for which Gauge skips executing the spec where the error occurs.

There are two types of validation error which can occurs

Step implementation not found

If the spec file has a step that does not have an implementation in the projects programming language.

Duplicate step implementation

If the spec file has a step that is imlpemented multiple times in the projects.

Example

[ValidationError] login.spec:33: Step implementation not found. login with "user" and "p@ssword"

[ValidationError] foo.spec:11 Duplicate step implementation => 'Vowels in English language are <table>'

Failure to launch the language runner plugin¶

If the language specific plugin for the project has not been installed then the execution will fail.

Data driven execution¶

A data table is defined in markdown table format in the beginning of the spec before any steps.
The data table should have a header row and one or more data rows
The header names from the table can be used in the steps within angular brackets < > to refer a particular column from the data table as a parameter.
On execution each scenario will be executed for every data row from the table.
Table can be easily created in IDE using template table:<no of columns>, and hit Tab.
Table parameters are written in Multi-markdown table formats.

Example:

Table driven execution
======================

     |id| name    |
     |--|---------|
     |1 |vishnu   |
     |2 |prateek  |
     |3 |navaneeth|

Scenario
--------
* Say "hello" to <name>

Second Scenario
---------------
* Say "namaste" to <name>

In the above example the step uses the name column from the data table as a dynamic parameter.

Both Scenario and Second Scenario are executed first for the first row values 1, vishnu and then consecutively for the second and third row values from the table.

External CSV for data table¶

Data Tables for a specification can also be passed from an external CSV file. The parameter contains a prefix table and the path to the csv file.

Prefix : The prefix is table

Value : The value is the path to the csv file. This can be absolute file path or relative to project.

Example:

Table driven execution
======================

table: /system/users.csv

Scenario
--------
* Say "hello" to <name>

Second Scenario
---------------
* Say "namaste" to <name>

In the above example the step uses the name column from the csv file.

Execute selected data table rows¶

By default, scenarios in a spec are run against all the data table rows. It can be run against selected data table rows with flag --table-rows and specifying the row numbers against which the scenarios should be executed. If there are multiple row numbers, they should be separated by commas.

Example:

gauge run --table-rows "1" specs/hello.spec
gauge run --table-rows "1,4,7" specs/hello.spec

Range of table rows can also be specified, against which the scenarios are run.

Example:

gauge run --table-rows "1-3" specs/hello.spec

This executes the scenarios against table rows 1, 2, 3.

Tagged Execution¶

Tags allow you to filter the specs and scenarios quickly for execution. To execute all the specs and scenarios which are labelled with certain tags, use the following command.

gauge run --tags tag1,tag2 specs

or,

gauge run --tags "tag1, tag2" specs

This executes only the scenarios and specifications which are tagged with tag1 and tag2.

Example:

Spec

In the above spec, if all the scenarios tagged with “search” and “admin” should be executed, then use the following command:

gauge run --tags "search & admin" SPEC_FILE_NAME

Tag expressions¶

Tags can be selected using expressions. Examples:

Tags	Selects specs/scenarios that
`!TagA`	do not have `TagA`
`TagA & TagB`	have both `TagA` and `TagB`.
`TagA & !TagB`	have `TagA` and not `TagB`.
`TagA \| TagB`	have either `TagA` or `TagB`.
`(TagA & TagB) \| TagC`	have either `TagC` or both `TagA` and `TagB`
`!(TagA & TagB) \| TagC`	have either `TagC` or do not have both TagA and TagB
`(TagA \| TagB) & TagC`	have either [`TagA` and `TagC`] or [`TagB` and `TagC`]

Parallel Execution¶

Specs can be executed in parallel to run the tests faster and distribute the load.

This can be done by the command:

gauge run --parallel specs

or,

gauge run -p specs

This creates a number of execution streams depending on the number of cores of the machine and distribute the load among workers.

The number of parallel execution streams can be specified by -n flag.

Example:

gauge run --parallel -n=4 specs

This creates four parallel execution streams.

Note

The number of streams should be specified depending on number of CPU cores available on the machine, beyond which it could lead to undesirable results. For optimizations, try parallel execution using threads.

Parallel Execution using threads¶

In parallel execution, every stream starts a new worker process. This can be optimized by using multithreading instead of processes. This uses only one worker process and starts multiple threads for parallel execution.

To use this, Set enable_multithreading env var to true. This property can also be added to the default/custom env.

enable_multithreading = true

Requirements:

Thread safe test code.
Language runner should support multithreading.

Note: Currently, this feature is only supported by Java langauge runner/plugin.

Executing a group of specification¶

Specifications can be distributed into groups and --group | -g flag provides the ability to execute a specific group.

This can be done by the command:

gauge run -n=4 -g=2 specs

This creates 4 groups (provided by -n flag) of specification and selects the 2nd group (provided by -g flag) for execution.

Specifications are sorted by alphabetical order and then distributed into groups, which guarantees that every group will have the same set of specifications, no matter how many times it is being executed.

Example:

gauge run -n=4 -g=2 specs

gauge run -n=4 -g=2 specs

The above two commands will execute the same group of specifications.

Run your test suite with lazy assignment of tests¶

This features allows you to dynamically allocate your specs to streams during execution instead of at the start of execution.

This allows Gauge to optimise the resources on your agent/execution environment. This is useful because some specs may take much longer than other, either because of the number of scenarios in them or the nature of the feature under test

The following command will assign tests lazily across the specified number of streams:

gauge run -n=4 --strategy="lazy" specs

or,

gauge run -n=4 specs

Say you have 100 tests, which you have chosen to run across 4 streams/cores; lazy assignment will dynamically, during execution, assign the next spec in line to the stream that has completed it’s previous execution and is waiting for more work.

Lazy assignment of tests is the default behaviour.

Another strategy called eager can also be useful depending on need. In this case, the 100 tests are distributed before execution, thus making them an equal number based distribution.

gauge run -n=4 --strategy="eager" specs

Note: The ‘lazy’ assignment strategy only works when you do NOT use the -g flag. This is because grouping is dependent on allocation of tests before the start of execution. Using this in conjunction with a lazy strategy will have no impact on your test suite execution.

Rerun one execution stream¶

Specifications can be distributed into groups and --group | -g flag provides the ability to execute a specific group.

This can be done by the command:

gauge run -n=4 -g=2 specs

This creates 4 groups (provided by -n flag) of specification and selects the 2nd group (provided by -g flag) for execution.

Specifications are sorted by alphabetical order and then distributed into groups, which guarantees that every group will have the same set of specifications, no matter how many times it is being executed.

Example:

gauge run -n=4 -g=2 specs

The above two commands will execute the same group of specifications.

Current Execution Context in the Hook¶

To get additional information about the current specification, scenario and step executing, an additional ExecutionContext parameter can be added to the hooks method.

C#¶

  This feature is not yet
  supported in Gauge-CSharp. Please refer to
  https://github.com/getgauge/gauge-csharp/issues/53 for updates.

Java¶

  @BeforeScenario
  public void loginUser(ExecutionContext context) {
    String scenarioName = context.getCurrentScenario().getName();
    // Code for before scenario
  }

  @AfterSpec
  public void performAfterSpec(ExecutionContext context) {
    Specification currentSpecification = context.getCurrentSpecification();
    // Code for after step
  }

Javascript¶

  hooks.beforeScenario(fn, [opts]) { ... }
  hooks.afterSpec(fn, [opts]) { ... }

Python¶

  from getgauge.python import before_step, after_scenario

  @before_scenario
  def before_scenario_hook():
      print("before scenario hook")

  @after_spec
  def after_spec_hook():
      print("after spec hook")

ruby¶

  before_spec do |execution_info|
      puts execution_info.inspect
  end

  after_spec do |execution_info|
      puts execution_info.inspect
  end

Filtering Hooks execution based on tags¶

You can specify tags for which the execution hooks can run. This will ensure that the hook runs only on scenarios and specifications that have the required tags.

C#¶

  // A before spec hook that runs when tag1 and tag2
  // is present in the current scenario and spec.
  [BeforeSpec("tag1, tag2")]
  public void LoginUser() {
      // Code for before scenario
  }

  // A after step hook runs when tag1 or tag2
  // is present in the current scenario and spec.
  // Default tagAggregation value is Operator.AND.
  [AfterStep("tag1", "tag2")]
  [TagAggregationBehaviour(TagAggregation.Or)]
  public void PerformAfterStep() {
      // Code for after step
  }

Java¶

  // A before spec hook that runs when tag1 and tag2
  // is present in the current scenario and spec.
  @BeforeSpec(tags = {"tag1, tag2"})
  public void loginUser() {
      // Code forbefore scenario
  }

  // A after step hook runs when tag1 or tag2
  // is present in the currentscenario and spec.
  // Default tagAggregation value is Operator.AND.
  @AfterStep(tags = {"tag1", "tag2"}, tagAggregation = Operator.OR)
  public void performAfterStep() {
      // Code for after step
  }

Javascript¶

  // A before spec hook that runs when tag1 and tag2
  // is present in the current scenario and spec.
  hooks.beforeSpec(function () {
      //implementation
  }, { tags: [ "tag1","tag2" ]});

  // A after step hook runs when tag1 or tag2
  // is present in the currentscenario and spec.
  // Default tagAggregation value is Operator.AND.
  hooks.afterStep(function () {
      //implementation
  }, { tags: [ "tag1","tag2" ]});

Python¶

  // A before spec hook that runs when tag1 and tag2
  // is present in the current scenario and spec.
  @before_spec("<tag1> and <tag2>")
  def before_spec_hook():
      print("before spec hook with tag")

  // A after step hook runs when tag1 or tag2
  // is present in the currentscenario and spec.
  // Default tagAggregation value is Operator.AND.
  @after_step("<tag1> and <tag2>")
  def after_step_hook():
      print("after step hook with tag")

Ruby¶

  # A before spec hook that runs when
  # tag1 and tag2 is present in the current scenario and spec.
  before_spec({tags: ['tag2', 'tag1']}) do
      # Code for before scenario
  end

  # A after step hook runs when tag1 or tag2 is present in the current scenario and spec.
  # Default tagAggregation value is Operator.AND.

  after_spec({tags: ['tag2', 'tag1'], operator: 'OR'}) do
      # Code for after step
  end

Note

Tags cannot be specified on @BeforeSuite and @AfterSuite hooks

Gauge Project Templates¶

Gauge provides templates that can be used to bootstrap the process of initializing a Gauge project along with a suitable build dependency tool, webdriver etc.

To list all the Gauge project templates available, run the following command:

gauge init --templates

These templates can also be found in Bintray Gauge Templates.

Initialize a Gauge project with Template¶

Say you want to initialize a Gauge project with Java as language for writing test code and Selenium as driver of choice. You can quickly setup such project which is ready to start writing tests with selenium by using java_maven_selenium Gauge template.

To initialize a Gauge project with a template, choose a name from the list shown on running gauge init --templates and pass that name as an argument when initializing the Gauge project.

For example, to create a Gauge project with the java_maven_selenium template, you need to run this command:

gauge init java_maven_selenium

This template creates a Gauge project with Maven as build tool and the selenium Webdriver. This will download the Gauge template java_maven_selenium and setup your project with useful sample code.

Now, you can start writing Specifications and execute them.

Step alias¶

Multiple Step names for the same implementation. The number and type of parameters for all the steps names must match the number of parameters on the implementation.

Use case¶

There may be situations where while authoring the specs, you may want to express the same functionality in different ways in order to make the specs more readable.

Example 1¶

User Creation
=============
Multiple Users
--------------
* Create a user "user 1"
* Verify "user 1" has access to dashboard
* Create another user "user 2"
* Verify "user 2" has access to dashboard

In the scenario named Multiple Users, the underlying functionality of the first and the third step is the same. But the way it is expressed is different. This helps in conveying the intent and the functionality more clearly. In such situations like this, step aliases feature should be used so that you can practice DRY principle at code level, while ensuring that the functionality is expressed clearly.

Implementation¶

C#¶

  public class Users {

      [Step({"Create a user <user_name>", "Create another user <user_name>"})]
      public void HelloWorld(string user_name) {
          // create user user_name
      }

  }

Java¶

  public class Users {

      @Step({"Create a user <user_name>", "Create another user <user_name>"})
      public void helloWorld(String user_name) {
          // create user user_name
      }

  }

Javascript¶

  step(["Create a user <username>", "Create another user <username>"], function (username) {
  // do cool stuff
  });

Python¶

  from getgauge.python import step

  @step(["Create a user <user name>", "Create another user <user name>"])
  def hello(user_name):
      print("create {}.".format(user_name))

Ruby¶

  step 'Create a user ','Create another user ' do |user_name|
      // create user user_name
  end

Example 2¶

User Creation
-------------
* User creates a new account
* A "welcome" email is sent to the user

Shopping Cart
-------------
* User checks out the shopping cart
* Payment is successfully received
* An email confirming the "order" is sent

In this case, the underlying functionality of the last step (sending an email) in both the scenarios is the same. But it is expressed more clearly with the use of aliases. The underlying step implementation could be something like this.

Implementation¶

C#¶

  public class Users {

      [Step({"A <email_type> email is sent to the user", "An email confirming the <email_type> is sent"})]
      public void HelloWorld(string email_type) {
          // Send email of email_type
      }

  }

Java¶

  public class Users {

      @Step({"A <email_type> email is sent to the user", "An email confirming the <email_type> is sent"})
      public void helloWorld(String email_type) {
          // Send email of email_type
      }

  }

Javascript¶

  step(["A <email_type> email is sent to the user", "An email confirming the <email_type> is sent"], function (email_type) {
      // do cool stuff
  });

Python¶

  from getgauge.python import step

  @step(["A <email_type> email is sent to the user", "An email confirming the <email_type> is sent"])
  def email(email_type):
      print("create {}.".format(email_type))

Ruby¶

  step 'A email is sent to the user', 'An email confirming the is sent' do |email_type|
      email_service.send email_type
  end

Re-run failed tests¶

Gauge provides you the ability to re-run only the scenarios which failed in previous execution. Failed scenarios can be run using the --failed flag of Gauge.

Say you run gauge run specs and 3 scenarios failed, you can run re-run only failed scenarios instead of executing all scenarios by following command.

gauge run --failed

This command will even set the flags which you had provided in your previous run. For example, if you had executed command as

gauge run --env="chrome" --verbose specs

and 3 scenarios failed in this run, the gauge run --failed command sets the --env and --verbose flags to corresponding values and executes only the 3 failed scenarios. In this case gauge run --failed is equivalent to command

gauge run --env="chrome" --verbose specs <path_to_failed_scenarios>

Refactoring¶

Rephrase steps¶

Gauge allows you to rephrase a step across the project. To rephrase a step run:

gauge refactor "old step <name>" "new step name"

Here < and > are used to denote parameters in the step. Parameters can be added, removed or changed while rephrasing.

This will change all spec files and code files (for language plugins that support refactoring).

Example¶

Let’s say we have the following steps in our spec file:

* create user "john" with id "123"
* create user "mark" with id "345"

Now, if we now need to add an additional parameter, say last name, to this step we can run the command:

gauge refactor "create user <name> with id <id>" "create user <name> with <id> and last name <watson>"

This will change all spec files to reflect the change.

* create user "john" with id "123" and last name "watson"
* create user "mark" with id "345" and last name "watson"

Project Structure¶

On initialization of a gauge project for a particular language a project skeleton is created with the following files

Common Gauge files¶

GAUGE_PROJECT_ROOT environment variable holds the path in which the Gauge project is created.

├── env
│  └── default
│     └── default.properties
├── manifest.json
├── specs
   └── example.spec

Env Directory¶

The env directory contains multiple environment specific directories. Each directory has .property files which define the environment variables set during execution for that specific environment.

A env/default directory is created on project initialization which contains the default environment variables set during execution.

Learn more about managing environments.

Specs Directory¶

The specs directory contains all spec files for the project. They are the business layer specifications written in simple markdown format.

A simple example spec (example.spec) is created in the specs directory to better understand the format of specifications.

Learn more about spec.

Manifest file¶

The manifest.json contains gauge specific configurations which includes the information of plugins required in the project.

After project initialization, the manifest.json will have the following content.

{
  "Language": "<language>",
  "Plugins": [
    "html-report"
  ]
}

language : Programming language used for the test code. Gauge uses the corresponding language runner for executing the specs.
Plugins : The gauge plugins used for the project. Some plugins are used by default on each gauge project. The plugins can be added to project by running the following command :

gauge install <plugin-name>

Example :

gauge install xml-report

After running the above command, the manifest.json would have the following content:

{
  "Language": "<language>",
  "Plugins": [
    "html-report",
    "xml-report"
  ]
}

C# Project files¶

When creating a new Gauge C# project, the csharp specific project files created in the project are:

├── foo.csproj
├── foo.sln
├── manifest.json
├── packages.config
├── StepImplementation.cs
│
├── env
│   └───default
│           default.properties
│
├───packages
    └───<Nuget Package Binaries>
├───Properties
│       AssemblyInfo.cs
│
└───specs
        hello_world.spec

packages.config¶

For nuget. Contains the dependencies for Gauge. One can add more to this list, depending on your project needs.

StepImplementation.cs¶

Contains the implementations for the sample steps defined in hello_world.spec.

default.properties¶

This defines default configurations for gauge csharp runner plugin. Currently the configuration parameters are:

gauge_reports_dir - The path to the gauge reports directory. Should be either relative to the project directory or an absolute path
overwrite_reports - Set as false if gauge reports should not be overwritten on each execution. A new time-stamped directory will be created on each execution. This is true by default.

Java project files¶

The java specific project files create in the project are:

├── libs
└── src
    └── test
        └── java
            └── StepImplementation.java
├── env
    └── default
        └── java.properties

libs¶

This contains the additional java dependencies for the project.

src¶

Src directory contains the classes the test code including step implementations.

java.properties¶

This defines configurations for java runner plugin. See Configuration for more details.

Javascript project files¶

The Javascript specific project files create in the project are:

└── tests
     └── step_implementation.js
├── env
    └── default
        └── js.properties

tests¶

tests directory contains the test code including step implementations.

js.properties¶

This defines configurations for Javascript runner plugin. See Configuration for more details.

Python project files¶

The Python specific project files create in the project are:

└── step_impl
     └── step_impl.py
├── env
    └── default
        └── python.properties

step_impl¶

step_impl directory contains the test code including step implementations.

python.properties¶

This defines configurations for Python runner plugin. See Configuration for more details.

Ruby Project files¶

The ruby specific project files create in the project are:

├── env
│   └── default
│       └── ruby.properties
└── step_implementations
    └── step_implementation.rb

step_implementations directory¶

This contains all the .rb files with the test code including step implementations in ruby

ruby.properties¶

This defines configurations for ruby runner plugin.

IDE Support¶

The listed IDE plugins are available for gauge to make writing specs and test code simpler.

Integration with Visual Studio Code
Integration with IntelliJ IDEA
Integration with Visual Studio

Visual Studio Code¶

Gauge projects can be created and executed in Visual Studio Code using the Gauge extension for VSCode. This plugin can be installed from Visual Studio Gallery.

Installation¶

The Gauge extension can be installed via VScode’s Install from VSIX.

Install released version¶

The released versions are available here

Install from source¶

$ npm run build This will create gauge-<version>.vsix file which can be installed via VScode’s Install from VSIX.

Install Nightly version¶

Nightly version of vscode is available in bintray. To install a nightly version,

Uninstall existing version of gauge extension. Download the latest nightly version of gauge extension from bintray.

Uninstall¶

To uninstall existing version follow these instructions

Syntax Highlighting¶

Gauge specs are in Markdown syntax. This plugin highlights Specifications, Scenarios, Steps and Tags.

Steps with missing implementation are also highlighted.

syntax highlighting

Auto Completion¶

This plugin hooks into VSCode LSP, and brings in autocompletion of Step text. The step texts brought in is a union of steps already defined, concepts defined, and step text from implementation.

Hint: Hit Ctrl + Space to bring up the Intellisense menu.

AutoComplete

Implement Step¶

If you have an unimplemented step in the spec file, it will be get highlighted with a red underline. Hover over towards the end of step text to get the Smart Tag to implement it. On clicking the Smart Tag the implementation is copied to the clipboard. Pasting this in the desired code file will then generate the step with required annotation and parameters.

step quick fix

Formatting¶

A specification file can be formatted easily using Right Click -> Format File

This formats the specification including indentation of tables and steps.

format

Execution with Code Lens¶

When you open a specification, the code lens Run Spec appears near the specification heading. Clicking this will run all the scenarios in the specification.

Code Lens

Similarly, scenarios can be executed with the code lens Run Scenario near the scenario heading

Run from Command palette¶

To invoke the command palette use - (Ctrl+Shift+P)

To run all the scenarios in a solution, choose Run All Specfications from the palette.
To run all the scenarios of a specification, choose Run Specification from the palette
To choose and run a scenario, use Run Scenario from the palette.

Command palette

Run tests cases in parallel¶

If a specification has scenarios driven by data they can be run in parallel. Use the code lens Run parallel near the scenario heading that appears only when there is a data table at the specification level.

Test results¶

As you run, write, and rerun your tests, VS Code displays the results in the Output panel.

Find Usages¶

The number of times the step is used can be seen in the definition of the step.

The usages are displayed against the step annotated methods in the implementation file(currently js files only).

IntelliJ IDEA¶

Gauge projects can be created and executed from Intellij IDEA. The plugin can be downloaded from the JetBrains plugin repository.

This plugin currently supports only Gauge with Java.

Installation¶

Plugin can be installed by downloading from Jetbrains plugin repository.

Steps to install Gauge Intellij IDEA plugin from IDE:

Open the Settings dialog (e.g. ⌘ Comma).
In the left-hand pane, select Plugins.
On the Plugins page that opens in the right-hand part of the dialog, click the Install JetBrains plugin or the Browse repositories button.
In the dialog that opens, search for Gauge. Right-click on Gauge and select Download and Install.
Confirm your intention to download and install the selected plugin.
Click Close.
Click OK in the Settings dialog and restart IntelliJ IDEA for the changes to take effect.

Note: The plugin you have installed is automatically enabled. When necessary, you can disable it as described in Enabling and Disabling plugins.

To install plugin by downloading it manually or to update plugin, follow the steps here.

Create a new Gauge project and start writing your tests.

Explore all the features of Gauge Intellij IDEA plugin now!

Installing Nightly¶

Nightly builds are also available in IntelliJ plugin repository.

Follow the instructions to add Nightly channel to IntelliJ Idea.
Add the following repository URL

https://plugins.jetbrains.com/plugins/nightly/7535

Creating a Java project¶

File -> New Project.
Choose ‘Gauge’
Choose the project location and java sdk
Finish

Note: If gauge-java is not installed, it will download it for the first time.

creation

Maven project using gauge-maven-plugin¶

File -> New Project
Choose Maven
Select Create from Archetype
Select the gauge archetype - com.thoughtworks.gauge.maven
If the com.thoughtworks.gauge.maven archetype is not added select Add Archetype
- Enter GroupId: com.thoughtworks.gauge.maven
- Enter ArtifactId: gauge-archetype-java
- Enter Version: 1.0.1 or the latest version number from

maven add archetype

Enter the groupId and artifactId for your project.
Enter Project Name and finish
The project will be created in batch mode, watch the console for progress.
After project creation close and re-open the project to enable auto-complete features.
Enable auto-import for the project. Under File > Settings > Maven > Importing, mark the checkbox Import Maven projects automatically.

See gauge-maven-plugin for more details on using the gauge maven plugin.

Syntax Highlighting¶

Gauge specs are in Markdown syntax. This plugin highlights Specifications, Scenarios, Steps and Tags.

Steps with missing implementation are also highlighted.

syntax highlighting

Auto Completion¶

Steps present in the current project can be listed by invoking the auto completion pop up ctrl+space after the ‘*’. After choosing a step, it gets inserted with parameters highlighted, you can press tab to cycle between the parameters and edit them.

creation

Implement Step¶

If you have an unimplemented step in the spec file, it will be annotated saying ‘undefined step’. A smart tag appears when you hover on the step. Clicking the smart tag opens the quick fix pop up. The destination of the implementation can be chosen, either a new class or from a list of existing classes. It will then generate the step with required annotation and parameters.

step quick fix

Navigation¶

Jump from Step text to it’s implementation.

Usage: right Click -> Go to -> Declaration

Formatting¶

A specification file can be formatted easily using the keyboard shortcut of Spec Format in the action menu ctrl+shift+a.

This formats the specification including indentation of tables and steps.

Execution¶

Specs can be executed by right click -> Run spec.
Execute all specs inside a directory by right click -> Run specifications

Single Scenario Execution¶

A single scenario can be executed by doing a right click on the scenario which should be executed and choosing the scenario. right click -> run -> Scenario Name

Note: If the right click is done in context other than that of scenario, by default, first scenario will be executed.

scenario execution

Parallel Execution¶

To run multiple specifications in parallel

Right click on the specs directory and select Create Specifications option.
In the new Run configuration select In Parallel options. This will distribute specs execution based on number of cores the machine has.
You can also specify the Number of parallel execution streams. This is optional

Warning

Select parallel nodes based on current systems performance. For example on a 2 core machine select upto 4 parallel streams. A very large number may affect performance.

Select ok. Now you can run this new configuration for parallel execution of specs.

Debugging¶

Debugging can be performed the same way spec execution works.

Right click on a specification or specs directory -> Debug. Execution will halt on marked breakpoints.

Run Configuration¶

You can edit the run configuration to make changes to:

The scenario or spec file to be executed

Choose table-rows to be executed

The environment to run against

Add a tag filter to the execution

Choose the number of parallel streams

Add program arguments (Example: –log-level)

run configuration

Multiple Spec Files Execution¶

To execute multiple specs/scenarios add || seperated list of spec/scenarios in Specification to execute section

multiple spec run configuration

Warning

The delimiter for multiple spec files in run config has been changed from comma (,) to double bar (||). Until v0.1.0 of IntelliJ plugin, the delimiter is ,. Any higher version will have delimiter ||.

Rephrase Steps¶

right click -> Refactor -> Rename on a step to rephrase it.
The parameters will be in < > in the rephrase dialog. They can be reordered,removed or new parameters can be added.
The rephrase change will reflect across all the specs in the project.

Find Usages¶

right click -> Find Usages on step/concept to see the usages.

find usages

Extract Concept¶

In the editor, select the steps to be transformed into a concept.
On the main menu or on the context menu of the selection, choose Refactor | Extract to Concept or press ⌥⌘C.
In the Extract Concept dialog box that opens
- Specify the concept name with parameters to be passed from the usage. For Example: Say “hello” to “gauge”.
- Select the file name from the spec file dropdown list or specify the new file name/path relative to the project.
- Click OK.
The selected steps will be replaced with the specified concept name. # Additional Usability features

The intellij idea gauge plugin comes with more features to simplify writing specifications.

Create Spec and Concept files¶

You can right-click in under any directory in the specs directory and create a new specification or concept file. They will be created with a template to get you started.

create spec

Creating markdown table¶

To easily create markdown tables in specification(.spec) or concept(.cpt) files you can use predefined table templates specifying the number of columns needed.

For example, to create a table with 4 columns type

table template enter

Then fill the column names in the template.

table template fill

Writing Specification Heading¶

To write the specification heading in markdown, you can use the predefined heading template.

spec heading enter

Then fill the specification name in the template.

spec heading fill

Writing Scenario Heading¶

Scenario heading in markdown can be easily written using the predefined scenario heading template.

scenario heading enter

Then fill the scenario name in the template.

scenario heading fill

HTML Preview Tab¶

A specification file, written in markdown can be viewed as HTML in browser.

This is a spec file in markdown.

spec text

Press alt + F2 or right click and select open in Browser option. It gives option to choose a browser. On choosig a browser, it opens a browser window with HTML equivalent preview of spec file.

browser preview

Since specs are written in markdown, they can be converted to HTML using any markdown to HTML convertors.

Visual Studio¶

Gauge projects can be created and executed in Visual Studio using the Visual Studio plugin for Gauge. This plugin can be installed from Visual Studio Gallery.

Installation¶

Open Visual Studio Extension Manager from Tools -> Extensions and Updates.
Go to Visual Studio Gallery and search for Gauge VS2013.
Click on Download and select Install option.
Restart Visual Studio in order for the changes to take effect.

The extension resides on the Visual Studio Gallery.

install plugin

Creating a new Gauge Project¶

Install project and item templates from Visual Studio Marketplace¶

Download the templates from Visual Studio MarketPlace.
Install the Gauge VisualStudio Templates - vsix

Create Gauge Project¶

Go to File -> New Project.
Choose Gauge Test Project under Visual C# Test category.

ProjectCreation

Choose the Project location and Project Name.
Click OK.

This should setup a new Gauge project, and add the required meta data for Gauge to execute this project.

Alternately, you can create a Gauge project from command-line as:

mkdir <project_name>
cd <project_name>
gauge init csharp

This creates <project_name>.sln file which can be opened with Visual Studio.

Syntax Highlighting¶

Gauge specs are in Markdown syntax. This plugin highlights Specifications, Scenarios, Steps and Tags.

Steps with missing implementation are also highlighted.

syntax highlighting

Auto Completion¶

This plugin hooks into VisualStudio Intellisense, and brings in autocompletion of Step text. The step texts brought in is a union of steps already defined, concepts defined, and step text from implementation.

Hint: Hit Ctrl + Space to bring up the Intellisense menu.

AutoComplete

Implement Step¶

If you have an unimplemented step in the spec file, it will be get highlighted with a red underline. Hover over towards the end of step text to get the Smart Tag to implement it. On clicking the Smart Tag a pop up opens. The destination of the implementation can be chosen, either a new class or from a list of existing classes. It will then generate the step with required annotation and parameters.

step quick fix

Navigation¶

Jump from Step text to it’s implementation.

Usage: Right Click -> Go to Declaration or hit F12

Formatting¶

A specification file can be formatted easily using Right Click -> Format File

This formats the specification including indentation of tables and steps.

Execution with Test Explorer¶

Note

Refer MSDN Documentation on Unit Test Explorer for all features of Unit Test Explorer.

When you build the test project, all the test scenarios appear in Test Explorer. If Test Explorer is not visible, choose Test on the Visual Studio menu, choose Windows, and then choose Test Explorer.

Test Explorer

Run tests¶

To run all the scenarios in a solution, choose Run All.
To run all the scenarios of a specification, choose Run… and then choose the group on the menu.
To run one or more scenarios, select the individual scenarios that you want to run, open the context menu for a selected scenario and then choose Run Selected Tests.

Run tests in parallel¶

If individual scenarios have no dependencies that prevent them from being run in any order, turn on parallel test execution with the ute_parallel toggle button on the toolbar.

If you want to use the parallel run of Gauge please refer the command line parallel execution.

Test results¶

The pass/fail bar at the top of the Test Explorer window is animated as the scenarios run. At the conclusion of the run, the pass/fail bar turns green if all tests passed or turns red if any test failed.

As you run, write, and rerun your tests, Test Explorer displays the results in default groups of Failed Tests, Passed Tests, Skipped Tests and Not Run Tests. You can change the way Test Explorer groups your tests. You can perform much of the work of finding, organizing and running tests from the Test Explorer toolbar.

Test Explorer options

Traits¶

Groups of scenarios by specification, tags that are defined.

Search and filter the test list¶

This Test Explorer feature can be used as mentioned in Search and filter the test list of Visual Studio documentation.

Debugging¶

Debugging can be performed the same way spec execution works.

Right click -> Debug Selected Tests on a scenario(s) in the Test explorer. Execution will halt on marked breakpoints.

Rephrase Steps¶

right click -> Rename on a step to rephrase it.
The parameters can also be reordered,removed or new parameters can be added.
The rephrase change will reflect across all the specs in the project.

Find Usages¶

Right click on a step -> Find All References

Create Spec and Concept files¶

You can right-click on specs directory or any nested directory, choose Add -> New Item -> Go to Gauge under Visual C# Items.
Choose Specification or Concept file type.
Enter file name and click Add.

Create File Type