BDD testing


This functionality is currently available for users on the Early Access release track. See Quarterly release tracks for more information about how to update your instance to the early access track.

You can create and run Behavior Driven Development (BDD) scenarios using Gherkin syntax in TestRail. A BDD template is available for use when creating test cases.  This template facilitates Gherkin keyword suggestions and syntax highlighting.

With this functionality, you can design and execute your BDD scenarios directly inside of TestRail, if you wish. Scenarios can also be implemented as part of an automated testing workflow, either by importing scenarios into TestRail via .feature files or by exporting them out of TestRail as .feature files.

Designing BDD tests in TestRail

You can design your BDD scenarios when creating a test case or editing one by setting the Template drop-down option to ‘Behavior Driven Development’. After you select this option when creating a  new test case or editing an existing one, you will see a newly added section, ‘BDD Scenarios’. Click Add the first scenario to start adding your BDD scenarios:


You can then start adding information to each scenario in your test case. The scenarios handle the Gherkin syntax, which specializes in highlighting a set of keywords to give structure and meaning to executable specifications. Most lines in each scenario start with a highlighted keyword that can be selected from auto-suggestion as you start typing the word:

  • Feature
  • Rule 
  • Scenario
  • Given, When, Then, And, But
  • Background
  • Scenario Outline 
  • Examples 

The advantage of designing your BDD scenarios inside of TestRail and using the WYSIWYG editor is the keyword auto-suggestion and syntax color highlighting to help improve readability and productivity. Each auto-suggested keyword changes to a different highlighted color when you select the suggestion from an automatic drop-down list.



Your TestRail project must be using the WYSIWYG text formatter to take advantage of the automatic colorization and auto-suggest features. However, it is not mandatory to use this text formatter, since the BDD template is still available in any projects you may have that utilize the Markdown or Plaintext text formatters. You can use other editor formats instead as well.  Still, WYSIWYG is recommended due to its mentioned advantages.

If you have added several scenarios, you also have the option to organize scenarios in the order you want, add more scenarios, or delete scenarios. These options can be found in the lower-right corner of each added scenario. Clicking on either of the gray arrows allows you to ascend or descend your scenario. Clicking the red ‘X’ deletes the scenario, and clicking the green ‘+’ adds a scenario.


 To save your desired configuration for each test case, click Save Test Case

Running BDD tests in TestRail

BDD test cases can be executed in TestRail in the same way as step-based test cases and record test statuses for individual scenarios. If you select a test case that has the BDD template format and scenarios in it, you can run the BDD scenarios manually the same way you would run a test case that uses steps in it.

You can do this by accessing the case through the Test Runs & Results or Test Cases tabs. Once you find your test case, click the case, then click Test & Results, and finally click +Add Result inside your desired test case. The following window will appear:


Here, you can manually select the scenario you want to execute separately, the same way you would execute steps in another test case.

Export BDD test cases to .feature files

Once your BDD scenarios have been created, you can also export them directly out of TestRail to use them in your desired automation framework by clicking the green Export feature button inside the selected test case UI, just left of the Edit button:


The BDD scenarios are then exported in the ‘.feature’ format. 

Import .feature files as test cases

If you prefer to write your BDD scenarios outside of TestRail, you can still do so and then import them via the Test Cases UI by clicking the green Import feature button:


Click + Select Files to add the ‘.feature’ file. You can either select Add New Test Cases to create a new test case for each uploaded file, or Update Existing Text Cases to update the test cases according to the title of the files you want to import. Click + Import to upload the file. 

When the entire feature is loaded into a single case, you can verify if it was uploaded correctly by accessing the test case as you would normally do. Also, you can verify by trying to split out the scenarios so they can be executed manually as steps, as explained above in BDD Scenario Execution. 

Exporting and importing BDD scenarios using API endpoints

The ability to export and import any BDD ‘.feature’ file is also supported by the TestRail API. The following API endpoints are available for you to export and import your BDD files:

Was this article helpful?
1 out of 1 found this helpful