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 :doc:`installed <installing>`, list the 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.

Flags

Since 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

For details, see how to :ref:`create a Gauge project <create_a_project>`.

Executing tests

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

The syntax is:

gauge [options] <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 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 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 specs/helloworld.spec:4 specs/helloworld.spec:7

These scenarios can also belong to different specifications.

You can also specify a specific :ref:`scenario <scenario_syntax>` or a list of scenarios to execute. To execute scenarios, gauge takes path to a specification file, followed by a colon and a zero-indexed number of scenarios.

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

gauge 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 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 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 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 specs/spec1.spec

Or, to execute multiple specification files:

gauge 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 --verbose specs/

Errors during execution

Parse error in a spec file:

This occurs if the spec file doesn't follow the expected :ref:`specifications <spec_syntax>` syntax or parameters could not be resolved.

Example

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

Unimplemented steps present in spec file

If the spec file has a step that does not have an implementation in the projects programming language there will be a validation error.

Appropriate underlying code implementation has to be provided for all the steps in the specs to be executed.

Example

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

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.

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 --table-rows "1" specs/hello.spec
gauge --table-rows "1,4,7" specs/hello.spec

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

Example:

gauge --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 --tags tag1,tag2 specs

or,

gauge --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 --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 --parallel specs

or,

gauge -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 --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 -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 -n=4 -g=2 specs

gauge -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 -n=4 --strategy="lazy" specs

or,

gauge -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 -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 -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 -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 :ref:`hooks <execution_hooks>` method.

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

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

  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 :ref:`hooks <execution_hooks>` can run. This will ensure that the hook runs only on scenarios and specifications that have the required tags.

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

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

  # 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 --list-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 --list-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 :ref:`Specifications <spec_syntax>` 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

  public class Users {

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

  }

  public class Users {

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

  }

  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

  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
      }

  }

  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
      }

  }

  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 specs and 3 scenarios failed, you can run re-run only failed scenarios instead of executing all scenarios by following command.

gauge --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 --env="chrome" --verbose specs

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

gauge --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 :ref:`managing environments <environments>`.

Specs Directory

The specs directory contains all :ref:`spec <spec_syntax>` 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 :ref:`spec <spec_syntax>`.

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 --add-plugin <plugin-name>

Example :

gauge --add-plugin 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 :doc:`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.

Intellij IDEA
Visual Studio

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 :ref:`features of Gauge Intellij IDEA plugin <intellij-features>` 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 :ref:`gauge-maven-plugin <maven>` 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 * The environment to run against * Add a tag filter to the execution * Choose the number of parallel streams

run configuration

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 :ref:`specification <spec_syntax>` or :ref:`concept <concept_syntax>` 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 an HTML preview.

This is a spec file in markdown.

spec text

On click of the HTML Preview tab at the bottom of the editor, it shows the HTML equivalent preview of spec file.

spec text

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

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 toggle button on the toolbar.

If you want to use the parallel run of Gauge please refer the :ref:`command line parallel execution <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

Files

using.rst

Latest commit

History

using.rst

File metadata and controls

Using Gauge

Command Line Interface

Flags

Creating a project

Executing tests

Specify scenarios

Specify directories

Specify files

Verbose reporting

Errors during execution

Parse error in a spec file:

Unimplemented steps present in spec file

Failure to launch the language runner plugin

Data driven execution

Execute selected data table rows

Tagged Execution

Tag expressions

Parallel Execution

Parallel Execution using threads

Executing a group of specification

Run your test suite with lazy assignment of tests

Rerun one execution stream

Current Execution Context in the Hook

Filtering Hooks execution based on tags

Gauge Project Templates

Initialize a Gauge project with Template

Step alias

Use case

Example 1

Implementation

Example 2

Implementation

Re-run failed tests

Refactoring

Rephrase steps

Example

Project Structure

Common Gauge files

Env Directory

Specs Directory

Manifest file

C# Project files

packages.config

StepImplementation.cs

default.properties

Java project files

libs

src

java.properties

Ruby Project files

step_implementations directory

ruby.properties

IDE Support

IntelliJ IDEA

Installation

Installing Nightly

Creating a Java project

Maven project using gauge-maven-plugin

Syntax Highlighting

Auto Completion

Implement Step

Navigation

Formatting

Execution

Single Scenario Execution

Parallel Execution

Debugging

Run Configuration

Rephrase Steps

Find Usages

Extract Concept

Create Spec and Concept files

Creating markdown table

Writing Specification Heading