---
description: When we are working on the scenario or .feature file - reading or creating it. If we are reading and its bad - ask questions and propose improvements to make it match rules.
alwaysApply: false
---
# Writing Effective BDD Feature Files
## 1. Principle: Always Start With a Feature Specification
- Before writing any feature story, check if a feature specification exists.
- If it does **not** exist, write one first. A good feature spec:
- Assess docs/ux/demo-flow.md - what we are doing and why? what will be affected?
- Defines the **user** (role or persona).
- States the **goal** (what the user wants to achieve).
- Describes the **context** (why the goal matters).
- Clarifies any **assumptions** or **preconditions**.
- Consist of one or many scenarios user is going through to achieve the goal
- Pick an ID (like a prefix for all scenarios in the file), like abbreviation "Library" -> LIB, "Dataset" - DS etc.
- Analyze the codebase - which pages/views are already available? what we will use? what we will build?
### Example Feature Spec
> Alex Chen wants to apply a moving average to Apple stock price data so they can observe trends and test signals over a historical period.
---
## 2. Principle: Be Specific — Who Does What, and Why
Each `Scenario` should:
- Identify the **actor** clearly (`Fund Analyst`, `Quant`, `User`).
- Describe **what they are trying to do**, in plain English, very specific - "Enters ABC into XYZ"
- State **why** it matters for the workflow or outcome.
- Capture precise values — asset identifiers, transformations, expected results.
- Have ID like "Scenario: LIB 1.1 Add Dataset"
## 3. Structure
Each `Scenario` should follow the format:
```gherkin
Scenario: <ID> <User goal>
Given <initial system state or data>
When <action is taken>
Then <expected result or outcome>
```
Include **exact DSL inputs**, **parameter values**, and **visual/verbal feedback** expectations.
---
## 4. Example: Data Transformation Scenario
```gherkin
Feature: DSL 1.1 Applying SMA transformation to a selected equity
Scenario: Applies applies 12-month simple moving average to AAPL equity
Given the user is in the "Workspace"
And the asset "US.Equity.AAPL" is selected in the data table "Assets"
When the user applies "transformation" "SMA(12)" to the time series in the row
Then the chart "Moving Avg: should update to show a new line representing the 12-month SMA
And the data table "Moving Avg: Table" should display the transformed values under a new column
```
---
## 5. Example: Error Handling Scenario
```gherkin
Feature: DSL 1.2 Handling invalid DSL expression
Scenario: Quant enters malformed DSL syntax
Given the user is on the Asset Selection screen
When the user enters "US.Equity..AAPL.SMA("
Then the system should display an error message "Invalid DSL syntax: unexpected token '.' at position 13"
And no data should be loaded
And the input field should remain editable
```
---
## 6. Common BDD Mistakes to Avoid
- ❌ Vague actor roles (e.g., "user" instead of "Fund Manager or Alex Chen")
- ❌ Missing context (why is the user doing this?)
- ❌ Leaving values generic (e.g., “some stock” instead of “US.Equity.AAPL”)
- ❌ Ambiguous outcomes (“should work” instead of what exactly should happen)
---
## 7. When in Doubt: Ask These Questions
- **Who** is performing the action? (Analyst, Fund Manager, Quant…)
- **What** are they trying to achieve?
- **Why** is it important?
- **Which exact input(s)** are used?
- **What are the expected outputs**, UI reactions, or system responses?
---
## 8. Optional Extensions
- Tag scenarios with `@core`, `@error`, `@backtest`, `@universe`, etc.
- Pick a FA Pro icon and add it to comments if user did not do that
---
By adhering to these principles, we ensure every story is understandable, testable, and traceable to real user needs.
