Behaviour-Driven Development (BDD) and Cucumber have become essential practices for teams wanting clearer requirements, improved collaboration, and reliable automated testing. But when organisations scale BDD inside Jira, teams face common questions about writing Gherkin, integrating automation frameworks, synchronising feature files with Git, managing test results, and combining manual and automated scenario execution.
To help development, QA, and product teams get the most out of BDD in Jira, we’ve created a comprehensive FAQ covering the most searched, most misunderstood, and most important topics for teams practising BDD — especially those using the AssertThat BDD & Cucumber for Jira plugin.
This page brings together all high-priority questions in one place, including:
Writing and structuring Gherkin feature files inside Jira
Integrating Cucumber test automation via GitHub Actions, Azure DevOps, Jenkins and more
Synchronising feature files between Jira and Git repositories
Uploading Cucumber JSON reports and linking results to user stories
Managing BDD at scale with traceability, dashboards, shared steps and hybrid execution
Combining manual and automated testing for a single source of truth
Whether you’re just starting with BDD or running large enterprise programmes with multiple teams and pipelines, these FAQs will help you understand how to bring clear requirements, shared understanding, and reliable Cucumber automation directly into your Jira workflows.
BDD and Cucumber
What is Behavior-Driven Development (BDD)?
Behavior-Driven Development (BDD) is an innovative software development approach that focuses on defining the behavior of an application from the perspective of its stakeholders. Central to BDD is the use of a common, ubiquitous language to describe system behavior, fostering collaboration between developers, QA, and non-technical stakeholders. This approach emphasizes continuous example-based communication, with scenarios written in natural language to describe system functionality.
Does AssertThat support all Gherkin syntax (Scenario Outline, Examples, Background, Tags)?
Yes. AssertThat supports the full Gherkin syntax specification, including:
Scenario
Scenario Outline
Examples tables
Background sections
Step Tables
DocStrings
Tags (@smoke, @regression, @wip, etc.)
Every element is rendered and stored exactly according to the Cucumber standard. You can create complex scenarios, parameterised test outlines, shared backgrounds, and tagged execution groups — all directly within Jira.
This ensures compatibility with all major Cucumber runners (Java, JS, Ruby, .NET, Python) and avoids vendor lock-in.
More information can be found in this video – Add BDD Scenarios in Jira with AssertThat Plugin
AssertThat doesn’t currently support Rules.
Can I import existing Gherkin feature files into Jira?
Yes. AssertThat supports importing existing .feature files directly into Jira. You can:
Upload feature files individually
Bulk-import multiple files from your local machine
Import feature definitions from Git repositories via our Maven/CLI integration
Map imported features to Jira stories or epics
The importer preserves all original Gherkin syntax — including tags, examples tables, comments, and formatting.
This is ideal for teams migrating from standalone Cucumber frameworks or centralising multiple repositories into Jira.
How does AssertThat integrate with Git for feature-file version control?
AssertThat BDD & Cucumber for Jira enables seamless integration with Git repositories, so your teams can collaborate across Jira and Git workflows.
Supports pulling and pushing feature files with Git providers: GitHub, GitLab, Bitbucket, Azure Repos.
Two sync models documented: AssertThat as master (feature files owned in Jira and synced to Git) and Git as master (feature files owned in Git and synced into Jira). Reference the workflows:
This allows developers to work in Git and business analysts/testers to work in Jira without duplicating feature definitions or losing version control.
With this setup, you maintain synchronized versioning, consistent feature-file definitions, and full traceability across both environments, supporting flexible workflows and reducing maintenance overhead.
Can automated and manual scenario execution be combined in AssertThat?
Yes — AssertThat supports a flexible hybrid execution model where scenarios authored in Jira can be executed either manually or automatically — and both result types feed back into the same scenario history, reporting and traceability. Here’s how it works in detail:
How hybrid execution works:
You author . feature files in Jira (or import them) and link them to user stories or requirements.
At first, a tester or business-analyst may execute a scenario manually (e.g., using the built-in test run screen inside Jira).
Later, when the scenario becomes stable, you can automate it in your CI/CD pipeline (e.g., using Cucumber, GitHub Actions, Azure DevOps or other frameworks).
When your automation runs, the plugin automatically uploads results (via the REST API or other supported upload mechanism) and updates the same scenario in Jira — so it’s exactly the same scenario definition, but now with automated execution history.
Both manual and automated executions are visible in the scenario’s history tab in Jira, so you retain full traceability of “how many times executed manually vs via automation”, pass/fail results, and links back to the user story or requirement.
You can continue to run some scenarios manually (e.g., exploratory, ad-hoc, or maintenance runs) while others transition to full automation — and this doesn’t require duplicating scenario definitions or maintaining parallel manual vs automated tracks.
Key benefits for your team:
Single source of truth: You don’t need separate definitions for manual vs automated tests — the same Scenario or Scenario Outline in Jira serves both.
Smooth transition to automation: As automation matures, you simply hook the same scenarios into CI/CD rather than starting anew.
Traceability and reporting: Because the results from both manual and automated executions are aggregated in Jira, you get unified reporting (pass/fail trends, execution frequency, history) regardless of execution mode.
Reduced maintenance overhead: No need to maintain two parallel sets of tests; your teams can evolve manual runs into automation without rewriting definitions.
How do I integrate my Cucumber automation framework with Jira using AssertThat?
AssertThat provides native integrations to connect your automated Cucumber tests to Jira. You can:
Use our Maven plugin
Use the REST API
Commit results from CI/CD pipelines (Jenkins, GitHub Actions, GitLab CI, Bamboo, Azure DevOps)
Upload standard Cucumber JSON reports
Automatically link executed scenarios to Jira issues
Once uploaded, test results appear directly in Jira with:
Execution status
Pass/fail trends
Error messages
Console logs
Linked user stories
This closes the loop between requirements, scenarios, automation, and reporting — all inside Jira. For more information integrations please see our confluence pages
How do I see BDD Cucumber test results in Jira?
With AssertThat BDD & Cucumber for Jira, Cucumber test results are published directly into Jira from your CI/CD pipeline using standard Cucumber JSON reports. Once uploaded, results are visible inside Jira issues and dedicated execution views, showing pass/fail status, execution history, logs, and linked requirements.
This allows teams to track automated BDD execution without leaving Jira, providing full traceability between requirements, scenarios, and test outcomes.
How can I reuse or standardise steps across multiple teams and projects?
AssertThat supports step reuse and standardisation to prevent duplication and ensure consistent behaviour definitions across Jira projects.
Key capabilities include:
Reusing existing steps from other scenarios or features
Searching for matching steps while writing new ones
Encouraging business-level language that can be shared across teams
Reducing maintenance by centralising common patterns
For large organisations, shared steps help enforce consistent test language, accelerate scenario creation, and simplify onboarding for new team members.
Can I validate or lint Gherkin syntax in Jira before saving?
Yes. AssertThat performs live validation of Gherkin syntax as you author scenarios. The plugin automatically checks:
Correct Given/When/Then/And/But structure
Valid Examples tables
- Duplicate or conflicting scenario names
Missing parameters in Scenario Outline examples
Malformed tags or formatting errors
The plugin also has shortcut keys to easily format the scenarios and to auto complete steps. See video Add BDD Scenarios in Jira with AssertThat Plugin
Validation happens instantly, so teams catch issues before running tests or pushing changes to automation pipelines.
This helps maintain high-quality feature files and reduces failures caused by incorrect syntax in CI/CD.
How do I write and structure Gherkin feature files directly inside Jira?
With AssertThat BDD & Cucumber for Jira, you can create, edit, and manage Gherkin feature files natively inside Jira — without needing an external editor. Every Scenario, Scenario Outline, Background, and Examples table can be authored in the feature editor and stored directly against your Jira project.
The editor supports multi-line steps, fast auto-completion of Given/When/Then syntax, and a clean layout that mirrors standard Cucumber conventions. Teams can write acceptance criteria in the language of the business, attach them directly to user stories, and keep test intent visible throughout the development lifecycle.
This ensures your BDD process is centralised in Jira, reducing friction between BAs, QAs, and developers. For more information see the full product walkthrough video
How can I use BDD in Jira?
AssertThat enables teams to practice BDD entirely within Jira by authoring Gherkin feature files, linking scenarios to Jira issues, and managing execution results in one place. Business analysts can write acceptance criteria in Gherkin, testers can execute scenarios manually or automatically, and developers can integrate those same scenarios into automation pipelines.
This makes Jira the central collaboration hub for BDD, rather than just a backlog tool.
Can BDD be integrated with other testing frameworks or tools?
Yes. BDD scenarios written in Gherkin can be automated using many frameworks, including Selenium, Playwright, Cypress, REST clients, and custom test runners. Cucumber acts as the execution layer, while AssertThat manages the lifecycle in Jira.
This allows teams to integrate BDD seamlessly with CI/CD pipelines, source control systems, and existing automation stacks while keeping Jira as the central source of truth.
Where can I view available BDD and Cucumber plugins on Atlassian Marketplace?
You can browse all BDD and Cucumber-related plugins on the Atlassian Marketplace by searching for keywords such as BDD, Cucumber, or test management. Each listing includes feature descriptions, pricing, hosting compatibility, and customer reviews.
AssertThat BDD & Cucumber Test Management for Jira is listed on the Marketplace with full Cloud and Data Center support.
How does BDD differ from traditional software development methods?
Traditional development often defines requirements separately from tests, leading to misinterpretation and late feedback. BDD differs by expressing requirements as executable examples written in a shared, structured language before development begins.
Instead of testing after implementation, BDD encourages collaboration upfront, using scenarios to define expected behaviour that can later be automated and verified continuously.
What is Cucumber, and how does it relate to BDD?
Cucumber is a testing framework that supports BDD by executing specifications written in Gherkin. BDD is the methodology, while Cucumber is one of the most widely used tools that implements it.
AssertThat bridges Cucumber and Jira by allowing Gherkin scenarios to be managed as first-class artefacts inside Jira, rather than existing only in code repositories.
Can you explain Gherkin language as used in Cucumber?
Gherkin is a structured, plain-text language used to describe system behaviour using keywords such as Feature, Scenario, Given, When, and Then. Its purpose is to make requirements readable by both technical and non-technical stakeholders.
AssertThat provides a Jira-native editor for Gherkin, supporting Scenario Outlines, Examples tables, tags, and validation to ensure compatibility with Cucumber automation.
What are the best practices for writing effective BDD scenarios?
Effective BDD scenarios should describe behaviour, not implementation, and focus on observable outcomes. They should be concise, consistent, and written from the user or business perspective.
AssertThat supports these practices by encouraging reusable steps, validating syntax, and allowing scenarios to evolve from manual acceptance criteria into automated tests without duplication.
What are the benefits of using BDD and Cucumber in software development?
BDD and Cucumber help teams align on expected behaviour early, reduce rework, and improve test coverage through executable specifications. Scenarios serve as both documentation and tests, keeping requirements and verification tightly coupled.
When combined with Jira via AssertThat, these benefits extend to improved traceability, clearer acceptance criteria, and better visibility of quality throughout the delivery lifecycle.
How does BDD help in improving communication between technical and non-technical team members?
BDD uses examples written in business-readable language rather than technical specifications. This allows product owners, analysts, testers, and developers to collaborate using the same artefacts.
By managing Gherkin scenarios directly in Jira, AssertThat ensures these shared conversations remain visible, reviewable, and actionable for all roles.
