Behavior-Driven Development (BDD)

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 functionality allows you to design and execute your BDD scenarios directly within TestRail. You can also implement your scenarios as part of an automated testing workflow, either by importing or exporting them as feature files.

Designing BDD scenarios 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. BDD scenarios begin each line with a Gherkin keyword. The primary keywords used in Gherkin include:

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


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?
37 out of 64 found this helpful