Behaviour-Driven Development (BDD) commands reference

The TestRail CLI provides comprehensive support for Behaviour-Driven Development workflows using Gherkin syntax. 

The BDD features enable you to manage test cases written in Gherkin format, execute BDD tests with various frameworks (Cucumber, Behave, pytest-bdd, etc.). Within TestRail, the only supported framework is Cucumber JSON (other BDD frameworks are not supported by TRCLI at this time).

Behaviour-Driven Development (BDD)

TestRail supports BDD-style test cases written in Gherkin syntax (Feature, Scenario , Given/When/Then). 

Using TRCLI, you can:

• Import Gherkin .feature files into TestRail
• Export existing BDD test cases from TestRail
• Upload execution results from Cucumber JSON reports

Global requirements for BDD commands

Before using any BDD-related command, ensure that:

• BDD template is enabled in your TestRail project
• You have permission to add or update test cases and results
• Your Gherkin syntax follows standard Cucumber formatting

The TestRail CLI provides four commands for complete BDD workflow management:

The parse_cucumber command allows you to upload automated test results from BDD frameworks that generate Cucumber JSON format, including:

• Cucumber (Java, JavaScript, Ruby)
• Behave (Python)
• pytest-bdd (Python)
• SpecFlow (.NET)
• Cucumber-JVM (Java)

The parse_cucumber command:

• Parses Cucumber JSON output
• Matches executed scenarios to TestRail test cases
• Uploads pass/fail results to a test run

Only scenario-level results are uploaded. Individual steps are not stored as results.

Reference

$ trcli parse_cucumber --help
Usage: trcli parse_cucumber [OPTIONS]

  Parse Cucumber JSON results and upload to TestRail

  This command parses Cucumber JSON test results and uploads them to TestRail
  using BDD matching mode. Features are matched to TestRail BDD test cases by
  feature name only (case-insensitive, whitespace-normalized).

  BDD Matching:
  - Matches Cucumber features to TestRail BDD test cases by feature name
  - Auto-creates missing BDD test cases by default (use -n to disable)
  - Sections are auto-created based on feature names
  - Does not use automation_id or case-matcher (BDD uses feature name matching only)

Options:
  -f, --file                 Filename and path.
  --close-run                Close the newly created run
  --title                    Title of Test Run to be created in TestRail.
  --suite-id                 Suite ID to submit results to.  [x>=1]
  --run-id                   Run ID for the results they are reporting.  [x>=1]
  --plan-id                  Plan ID with which the Test Run will be associated.  [x>=1]
  --config-ids               Comma-separated configuration IDs to use along with Test Plans.
  --milestone-id             Milestone ID to which the Test Run should be associated to.  [x>=1]
  --run-description          Summary text to be added to the test run.
  --result-fields            List of result fields and values for test results creation.
  --allow-ms                 Allows using milliseconds for elapsed times.
  -v, --verbose              Enable verbose logging output.
  --help                     Show this message and exit.

Note: The following options are NOT supported for parse_cucumber as they are not relevant for BDD matching:

• --case-matcher - BDD always uses feature name matching
• --suite-name- Use --suite-id instead
• --section-id- Sections are auto-created based on feature names
• --case-fields - BDD test cases are created via .feature file upload, not standard case creation

[
  {
    "id": "user-login",
    "name": "User Login",
    "description": "As a registered user\n\tI want to log in to the application\n\tSo that I can access my account",
    "uri": "features/login.feature",
    "elements": [
      {
        "id": "user-login;successful-login-with-valid-credentials",
        "name": "Successful login with valid credentials",
        "type": "scenario",
        "description": "",
        "keyword": "Scenario",
        "tags": [
          {"name": "@smoke"},
          {"name": "@authentication"}
        ],
        "steps": [
          {
            "keyword": "Given ",
            "name": "I have a valid username \"testuser\"",
            "result": {
              "status": "passed",
              "duration": 1500000000
            }
          },
          {
            "keyword": "When ",
            "name": "I enter my credentials",
            "result": {
              "status": "passed",
              "duration": 500000000
            }
          },
          {
            "keyword": "Then ",
            "name": "I should be redirected to the dashboard",
            "result": {
              "status": "passed",
              "duration": 300000000
            }
          }
        ]
      }
    ]
  }
]

Mapping Cucumber JSON to TestRail entities:

The parse_cucumber command uses BDD matching mode to intelligently match Cucumber features to TestRail BDD test cases by feature name. This provides a seamless workflow for uploading BDD test results.

Key Features:

• Feature Name Matching: Automatically matches Cucumber features to TestRail BDD test cases by feature name
• Auto-Creation: Automatically creates missing BDD test cases (can be controlled with flags)
• Section Auto-Creation: Creates TestRail sections on-the-fly if they don't exist
• Batch Pre-fetching: Efficiently fetches all BDD cases once and caches them for O(1) lookups
• Duplicate Detection: Warns when multiple BDD cases have the same feature name

Control how the TestRail CLI handles missing BDD test cases:

Default behavior (auto-create):

# Auto-create missing BDD test cases (default)
$ trcli parse_cucumber -f cucumber-results.json \
  --project "Your Project" \
  --suite-id 2 \
  --title "BDD Test Run"

Explicit auto-creation with -y flag:

# Same as default - auto-create missing test cases
$ trcli parse_cucumber -f cucumber-results.json \
  --project "Your Project" \
  --suite-id 2 \
  --title "BDD Test Run" \
  -y

Strict matching mode with -n flag:

# Only match existing BDD test cases - error if not found
$ trcli parse_cucumber -f cucumber-results.json \
  --project "Your Project" \
  --suite-id 2 \
  --title "BDD Test Run" \
  -n

How BDD matching works

1. Fetches all BDD test cases from the specified suite (one-time batch operation)
2. Normalizes feature names for matching (case-insensitive, whitespace-normalized)
3. For each feature in Cucumber JSON:
   • Tries to find existing BDD test case by feature name
   • If found: Uses that case ID and uploads scenario results
   • If not found and auto-create enabled: Creates new BDD test case with complete Gherkin content
   • If not found and auto-create disabled (-n): Shows error and exits
4. Aggregates all scenario results per feature
5. Uploads results to TestRail with scenario-level detail

Important Notes:

• Feature matching is done by feature name (not automation_id or case ID tags)
• If multiple BDD cases have the same feature name, a warning is shown
• Sections are created automatically if they don't exist
• Each feature becomes one BDD test case with multiple scenario results

The parse_cucumber command uses feature name matching to link Cucumber features to TestRail BDD test cases. This is different from the automation_id approach used in JUnit.

Feature Name Matching:

• TestRail CLI normalizes and compares feature names from Cucumber JSON to BDD test case titles in TestRail
• Normalization: case-insensitive, whitespace-normalized (e.g., "User Login" matches "user login")
• One feature = one BDD test case with multiple scenario results

Example:

# Cucumber JSON feature
Feature: User Login
  Scenario: Successful login with valid credentials
    Given I am on the login page
    When I enter valid credentials
    Then I should see the dashboard

  Scenario: Failed login with invalid password
    Given I am on the login page
    When I enter invalid credentials
    Then I should see an error message

# TestRail
# - One BDD test case with title "User Login"
# - Contains both scenarios with individual pass/fail status
# - Section name: "User Login" (auto-created if needed)

Using @C Tags (Optional):

You can also explicitly specify case IDs using @C<id> tags at the feature level:

@C123
Feature: User Login
  Scenario: Successful login with valid credentials
    Given I am on the login page
    When I enter valid credentials
    Then I should see the dashboard

Tag Priority:

1. @C<id> tags at feature level (if present)
2. Feature name matching (default behavior)

Duplicate Name Handling:

If multiple BDD test cases have the same feature name, the CLI will:

• Show a warning: Warning: Multiple BDD cases found with title 'User Login': C101, C202, C303
• Use the last matching case ID
• Recommend ensuring unique feature names in TestRail

The import_gherkin command allows you to upload BDD test cases in TestRail from existing .feature files.

$ trcli import_gherkin --help
Usage: trcli import_gherkin [OPTIONS]

  Upload or update Gherkin .feature file in TestRail

Options:
  -f, --file            Path to .feature file to import [required]
  --section-id          Section ID where test cases will be created (required for create mode)  [x>=1]
  --case-id             Case ID to update (required with --update flag)  [x>=1]
  --json-output         Output case IDs in JSON format
  --update              Update existing BDD test case instead of creating new one
  -v, --verbose         Enable verbose logging output
  --help                Show this message and exit.

# Create new test case (requires --section-id)
$ trcli import_gherkin -f features/login.feature \
  --project "Your Project" \
  --section-id 456 \
  -y

# Update existing test case (requires --case-id)
$ trcli import_gherkin -f features/login.feature \
  --project "Your Project" \
  --case-id 789 \
  --update \
  -y

# Create with custom project settings
$ trcli import_gherkin -f features/checkout.feature \
  --project-id 10 \
  --section-id 123 \
  -v -y

How it works:

Create mode (default):

1. Reads the .feature file
2. Uploads to TestRail via add_bdd/{section_id} endpoint
3. TestRail creates new test case(s) with complete Gherkin content
4. Returns created case ID(s)

Update mode (--update):

1. Reads the .feature file
2. Uploads to TestRail via update_bdd/{case_id} endpoint
3. TestRail updates existing test case with new Gherkin content
4. Returns created case ID(s)

Example .feature file:

Feature: User Login
  As a registered user
  I want to log in to the application
  So that I can access my account

  Background:
    Given the application is running
    And I am on the login page

  @smoke @authentication
  Scenario: Successful login with valid credentials
    Given I have a valid username "testuser"
    And I have a valid password "password123"
    When I enter my credentials
    And I click the login button
    Then I should be redirected to the dashboard
    And I should see a welcome message "Welcome, testuser"

  @negative @authentication
  Scenario: Failed login with invalid password
    Given I have a valid username "testuser"
    And I have an invalid password "wrongpassword"
    When I enter my credentials
    And I click the login button
    Then I should see an error message "Invalid credentials"
    And I should remain on the login page

The export_gherkin command allows you to export existing BDD test cases from TestRail as .feature files.

$ trcli export_gherkin --help
Usage: trcli export_gherkin [OPTIONS]

  Export BDD test case from TestRail as .feature file

Options:
  --case-id    TestRail test case ID to export  [x>=1] [required]
  --output     Output path for the .feature file (prints to stdout if not specified)
  -v, --verbose  Enable verbose logging output
  --help       Show this message and exit.

# Export to stdout
$ trcli export_gherkin --case-id 123 \
  --project "Your Project"

# Export to file
$ trcli export_gherkin --case-id 123 \
  --project "Your Project" \
  --output features/exported-login.feature

# Export with verbose logging
$ trcli export_gherkin --case-id 456 \
  --project-id 10 \
  --output features/checkout.feature \
  -v

Output example:

Connecting to TestRail...
Retrieving BDD test case 123...

✓ Successfully exported test case 123
  File: features/exported-login.feature
  Size: 1247 characters

Use cases:

• Extract test cases for automation
• Synchronize TestRail with version control
• Generate documentation from test cases
• Migrate test cases between projects

Notes and limitations

• Only Cucumber-compatible Gherkin syntax is supported
• Step execution details are not uploaded as results
• Test case IDs must exist before uploading results

Getting help and contributing

• Review official TestRail documentation for CLI updates
• Report issues or questions through TestRail Support
• Share workflow improvements with your QA team

Using TRCLI with BDD allows teams to keep TestRail and Cucumber fully aligned across automation and CI pipelines.

What next?

Now that you have centralized your test results on TestRail, not only can you check the results of your automated test runs, along with the error messages for failed tests, but you can also aggregate both your manual and automated testing efforts on reports that show you the full test coverage surrounding your app and even track test automation progress. You can also report a bug directly from the automated test result to an issue tracker of your preference as you would do for your manual test results!

You can look into the TestRail’s Reports and Test Metrics video to learn about how you can leverage TestRail’s reporting capabilities.