Create Gherkin tests

Gherkin is a well-known syntax for writing tests that implement behavior-driven development (BDD) methodology. Gherkin is plain-text English with some extra structure. It is designed to be easy-to-learn by non-programmers, yet structured enough to allow concise description of examples to illustrate business rules in many real-world domains.

Gherkin Tests can be automatically run using the Cucumber library. Cucumber implements many programming languages such as Java, .NET, Groovy, PHP, and many more.

ALM Octane supports Gherkin in the following ways:

  • A Gherkin test can be created and stored in ALM Octane.

  • The ALM Octane Manual Runner understands the Gherkin syntax and can run Gherkin tests manually.

  • The Gherkin test can be downloaded into an IDE, run externally using Cucumber, and uploaded back into ALM Octane.

This enables easy transformation from manual testing to automated testing.

Methodologically, the Gherkin test is written by a Functional Architect, and is the single source of truth (SSOT) for developers, QA and automation Engineers.

You can copy text from an external editor when creating scripts for a manual test. ALM Octane also provides version control capabilities for keeping track of manual test steps and Gherkin test scenarios.

Language support: Gherkin tests in ALM Octane support only English syntax.

Why use Gherkin tests?

Choosing Gherkin tests provides you with a methodology for transitioning from manual testing to automated testing.
  1. Write the Gherkin tests using standard Gherkin syntax in ALM Octane.

  2. Choose a few manual tests to automate and assign owners.

  3. Download the script, and in your IDE, implement code for automation.

  4. Include the automated tests in your Jenkins process. The results are linked back to the original Gherkin tests in ALM Octane.

    For details on running Gherkin tests as part of a CI progress, see Automate Gherkin tests.

  5. View the results and coverage in ALM Octane.

Using Gherkin scenario outlines, you can add parameter-like functionality to be used
  • When running the test manually.

  • Later on, if automating the tests.

Back to top

Add Gherkin tests

  1. In the Backlog or Quality modules, click + from the Tests tab.

  2. Select the Gherkin Test subtype, and give the test a name.

  3. Assign test attributes. Make sure to enter values for the following attributes:

    Test type The type of test, such as acceptance, end-to-end, regression, sanity, security, and performance. You can assign multiple test types to a single test.
    Covered content This lets you check if you have requirement coverage. Select the items the test will cover. You can assign multiple backlog items to a single test.
    Application modules When you are ready to use the test for tracking overall product quality, assign application modules to the test. You can assign multiple application modules to a single test. For details, see Work with application modules.
  4. Click Add & Edit.

  5. In the Script tab, add the required feature and test scenarios. For details, see Add test scenarios.

  6. In the Details tab, define additional attributes, as required. For details, see Create manual tests.

    When a new Gherkin test is created, the test's Details tab displays the Automation status attribute. By default, the status is set to Not automated. To learn more about automating Gherkin tests and automation statuses, see Automate Gherkin tests.

  7. Save the test.

After you assign the test to an owner, this test is included in a user's My Work list.

Team members can only delete items that they have created.

Back to top

Add test scenarios

After creating a Gherkin test and specifying its basic attributes, add its feature and scenarios. For details about the syntax, see Gherkin test syntax.

  1. Click the Script tab. The script is auto-generated with the Test ID (TID) and revision number (the script version number). This enables ALM Octane to identify to which Gherkin test to map the automated test run results.

    By default, the script is created with the following 3 lines. The second line is the Test ID tag and revision number.

    Note: The Test ID tag is used for mapping the automation results back to ALM Octane. DO NOT DELETE the Test ID tag!

    1 #Auto generated NGA revision tag
    2 @TID1001REV0.1.0
    3 Feature:

    The 3-digit revision number can help you identify from which revision you downloaded the test.

  2. In the Feature line, add a description of the feature. After this line, you can add the required scenarios and steps to your script.

  3. Click Add Scenario.

    Your script must meet Gherkin syntax standards.

  4. Save the script.

    The script is saved as a text file, which you can edit in ALM Octane or download to your IDE.

Tip: You can save labeled versions of your Gherkin test script or your manual test steps. As you design your test, you can compare versions to view what has been modified, and by whom. For details, see Save and compare versions of test scripts.

Back to top

Prepare your Gherkin tests for automation

  1. In ALM Octane, mark the Gherkin tests that you want to automate. In the test Details tab, set the Automation status to Ready for automation. This enables the automation engineers to readily identify the tests to automate.

  2. Download the Gherkin script and automate it in your preferred Java development environment.

Gherkin automation statuses

In the test Details tab in ALM Octane, you can view the automation status of the Gherkin test to see whether the test was automated as expected, or whether it requires update or approval due to discrepancies in script versions that require your attention and synchronization.

A Gherkin test can have the following automation statuses:

Not automated The default automation status of a new Gherkin test.
Ready for automation

To designate a test for automation, change its status to Ready for automation. You can filter by this automation status to quickly identify the tests that are ready to automate.


The Gherkin test is automated. The test was successfully automated in the code and run in the CI server. The results are linked back to the original Gherkin test in ALM Octane.

When the automation process completes, and the script in ALM Octane matches that in the IDE, the Automation Status automatically changes to Automated. This is ideal, since the test is accurately checking what it is supposed to, and the results will accurately reflect the quality of the current product or feature that is being tested.

The following automation statuses are displayed when the script versions in the IDE and ALM Octane are not synchronized. You can compare versions to see what has changed, and you can decide which version is the official, approved version. For details about comparing versions, see Save and compare versions of test scripts.

Requires update

This status is displayed when the script has been modified in ALM Octane, and is not up-to-date in the automation code.

To resolve the script conflict:

  1. Download the new version of the script from ALM Octane.

  2. Merge the script with the previous version in the IDE.

  3. Update the automation code accordingly.

The CI server uses the latest version of the script from the automation code. Therefore, when the script version in the automation code is not up-to-date, the test runs with an older script version than the one in ALM Octane, and thus is not testing the latest feature definitions.

Requires approval

This status is displayed when the script has been modified externally in the IDE and is not up-to-date in ALM Octane.

To resolve the script conflict:

  1. In ALM Octane, accept or decline the newer script version that was modified in the IDE. In the Scripts tab, on the upper right, the Script changed externally link, Accept button, and Decline button are displayed.

  2. Click the Script changed externally link to view and compare script versions and see what has changed.

  3. Decide which script version you want to approve.

  4. Click Accept to update the script in ALM Octane according to the external version from the automation code. Click Decline to reject the externally modified script and to keep the ALM Octane script version.

    The script is now the same in the automation code and in ALM Octane, and the test's Automation status is displayed as Automated in ALM Octane, indicating that the test is automated successfully.

You can filter by automation status to identify the tests that are ready for automation, and those that need further analysis. Using the automation status and the built-in version-tracking capabilities, ALM Octane enables you to synchronize script versions that are modified within ALM Octane or in an external IDE. This way you know that the tests being run are up-to-date and are in accordance with your functional specifications.

Next steps:

To run the Gherkin test manually, proceed to: