Testing with Cucumber

About Cucumber

Cucumber is a software testing tool that fosters better communication among domain experts, business analysts, testers, and developers by providing everyone a clear view of the testing effort. Cucumber is based on the principles of behavior-driven development (BDD). See Behavior Driven Development for more information.

A functional test script for the Eclipse version of HCL OneTest™ UI is a collection of Java™ methods. You must be able to read and understand the Java™ code to completely understand the test script. With Cucumber integration, anyone can understand the test script because the flow of the test is described in simple, English statements within a Cucumber feature file.

The basic steps for using Cucumber with HCL OneTest™ UI are as follows:

1. Create a Feature file, a text file with a .feature extension.
2. Create a Runner File, an empty functional test script, and annotate the Class in the test script with @FTCucumberOptions annotations. Any functional test script that is annotated becomes a runner file.
3. Provide Step definitions using Cucumber annotations, such as @When, @Given, @Then, and so on.
4. Run the Runner File, either from HCL OneTest™ UI or from the command line.

Requirements

Before using the Cucumber integration in HCL OneTest™ UI, you must set up Cucumber. There are two ways to set up Cucumber:

• By downloading the required Cucumber jar files, and copying them to the customization folder
• By running a Maven command to set up Cucumber automatically (Starting in 9.2.1)

Manual setup

To set up Cucumber manually, add the following Cucumber-related jar files to the HCL OneTest™ UI Customization directory, which on Windows™ is located at C:\ProgramData\IBM\RFT\customization.

• cucumber-core-1.2.5.jar
• cucumber-java-1.2.5.jar
• cucumber-jvm-deps-1.0.5.jar
• gherkin-2.12.2.jar
• cucumber-html-0.2.3.jar

You can download these jar files from the Central Maven repository at https://mvnrepository.com by searching for them one by one. All of the Cucumber-related libraries are grouped under the info.cukes group in the Maven repository at https://mvnrepository.com/artifact/info.cukes. The version numbers vary, depending on when you download the files.

Automated setup in 9.2.1 using Maven

To set up Cucumber with Maven:

1. Verify that you have an Internet connection.
2. You must have installed Maven and set up an environment variable that points to the M2_HOME directory. For more details about setting up Maven, see Testing with Maven.
3. Verify that the pom_dependency_cucumber.xml file is available from your Maven setup.
4. Run the following command in your command prompt window:

   mvn -f <path to pom_dependency_cucumber.xml file> dependency:copy-dependencies -DoutputDirectory=<FT Customization Directory> -Dmdep.stripVersion=true

   For example:

   mvn -f C:\Users\Win10\Desktop\pom_dependency_cucumber.xml dependency:copy-dependencies -DoutputDirectory=C:\ProgramData\IBM\RFT\customization -Dmdep.stripVersion=true

   This command downloads the required Cucumber jars into the HCL OneTest™ UI Customization directory. Depending on the speed of your Internet connection, this command can take several minutes to complete.

Cucumber feature file

The Cucumber feature file is a text file. It provides an abstraction layer that shields the non-technical user from the underlying code. A feature file describes one feature, but can describe multiple scenarios or test cases. It follows a Given-When-Then format, as follows:

• (Given) some context
• (When) some action is carried out
• (Then) a particular set of observable consequences are obtained.

For example:

• Given the login page is displayed for the application.
• When user attempts to log in with incorrect credentials.
• Then user should be re-prompted for credentials.
• Reset password link should be displayed.

The feature files are saved in a folder named features inside the functional test project.

A sample feature file that contains four scenarios is as follows:

Cucumber Runner file

A HCL OneTest™ UI Cucumber Runner file is a functional test script that includes @FTCucumberOptions annotations. The @FTCucumberOptions annotations must be declared outside of the class definition, as shown in the following figure:

Use the Run button in HCL OneTest™ UI to run the Runner file, or use the command line. For Cucumber command line options, see https://cucumber.io/docs/cucumber/api/ and look for List configuration options

Cucumber Step Definitions

The Step Definition file is a functional test script that contains the code behind each Cucumber annotation in the feature file, that is the @Given, @When, and @Then annotations. An example of a step definitions file for HCL OneTest™ UI Cucumber integration is as follows:

Reports

Two kinds of reports are available:

• Default Cucumber logs
• Extent reports (requires 9.2.1)

Default Cucumber logs

When you run a HCL OneTest™ UI test script with Cucumber annotations, the log files that are generated contain color-coding to indicate the pass-fail status of each step, as shown in the following example:

In this example, the steps in red indicate a failure, while the step in blue indicates that the step was not run due to the failure of the previous steps.

The log files also indicate the start point and end point of the feature and each scenario.

Extent reports (requires 9.2.1)

Starting with 9.2.1, you can run the Maven command to enhance Cucumber reporting. For more details about running the Maven command, see pom_dependency_extent.xml. After running this command, you will see an extra option for viewing Extent reports at the end of test execution in the HCL OneTest™ UI logs, as shown in the following image:

To view the Extent reports, you can run the following command in a command prompt window:

mvn -f <path to pom_dependency_extent.xml file> dependency:copy-dependencies -DoutputDirectory=<FT Customization Directory> -Dmdep.stripVersion=true

For example:

mvn -f "C:\Users\Win10\Desktop\pom_dependency_extent.xml" dependency:copy-dependencies -DoutputDirectory="C:\ProgramData\IBM\RFT\customization" -Dmdep.stripVersion=true

Running a feature file with default options

Here is sample code for running a feature file with default options:

@FTCucumberOptions( cucumberOptions = 
	{
		"cuketest2.feature"  // just providing the folder to the feature files will also work fine.
	})

Here are the default options for the other required parameters for the preceding example:

--glue '' --plugin pretty --plugin html:CukeLogs --plugin json:CukeLogs/abc.json --monochrome";

Required annotations for making a functional test script integrate with Cucumber

Cucumber annotations must be applied to the class. Cucumber options that are passed must be in the same format they would be passed in the Cucumber command line interface. The required annotations include --glue and the .feature file that needs to be run.

• --glue: Specifies where glue code (step definitions, hooks and plugins) are loaded from. In this case, a blank string ("") as a value to glue tells HCL OneTest™ UI to search for the step definitions inside all folders in the functional tester project. Duplicate steps lead to exceptions.
• The feature file is in a folder named Features inside the functional test project .

@code
@FTCucumberOptions(cucumberOptions = 
 { 
 	"--glue", "", 
  	"Features\\ValidateOrderFeature.feature"
 })

Command-line options for running functional test scripts with Cucumber

• Option 1: -datastore <datastore> -usecucumberoptionscli -playback CucumberRunnerScript
• Option 2: -datastore <datastore> -cucumberoptionscli All Cucumber options as single entry -playback CucumberRunnerScript

Option 1 assumes you have already added FTCucumberOptions annotations to the functional test script class (a Runner Script). HCL OneTest™ UI uses these annotations to run as Cucumber.

With Option 2, any options in the Runner Script are ignored, but command-line options are honored.

Option 1 example:-datastore C:\work\RFT_WS2\Cuketest3 -usecucumberoptionscli -playback steps.CucumberRunnerScript

Options 2 example: -datastore C:\work\RFT_WS2\Cuketest3 -cucumberoptionscli --glue 'steps' C:\work\RFT_WS2\Cuketest3\cuketest2.feature -playback steps.CucumberRunnerScript

The value for key cucumberoptionscli is a single value between double quotes. All of the Cucumber-related command line options go as a single value.

The value for (--glue) is either no value between single quotes for all packages (') or for specific packages, values between single quotes, for example, 'steps'. For more than one glue entry, specify separate entries as follows: --glue 'steps' --glue 'moreSteps'.