| name | bdd-features |
| description | This skill should be used when the user asks to "write Gherkin", "create feature files", "generate BDD scenarios", "write acceptance tests in Gherkin", "create Behave features", "write Given When Then tests", "BDD test cases for my pipeline", "Gherkin for Unity Catalog", or wants to translate requirements into Gherkin feature files for Databricks. |
| user-invocable | true |
BDD Features — Gherkin Feature File Generation
Generate well-structured Gherkin .feature files for Databricks workloads. Translate requirements, user stories, or existing code into behavior specifications using Given/When/Then syntax.
When to use
- Translating requirements or user stories into Gherkin acceptance criteria
- Creating feature files for Databricks pipelines, catalog permissions, jobs, or Apps
- Writing regression tests in Gherkin for existing functionality
- Generating Scenario Outlines for data-driven testing
Process
1. Identify the test subject
Determine what to test. Read the relevant code or ask the user:
- A Lakeflow SDP pipeline definition → pipeline behavior tests
- Unity Catalog grants/policies → permission verification tests
- A FastAPI Databricks App → API endpoint tests
- A notebook or job → execution and output validation tests
- SQL transformations → data quality and correctness tests
2. Write the feature file
Place feature files in the appropriate subdirectory under features/:
features/
├── catalog/permissions.feature
├── pipelines/events_pipeline.feature
├── apps/api_endpoints.feature
├── jobs/etl_notebook.feature
└── sql/data_quality.feature
Structure every feature file with:
- Tags —
@domain, @smoke/@regression/@integration, optional @slow or @wip
- Feature header — name + As a / I want / So that narrative
- Background — shared Given steps (workspace connection, test schema)
- Scenarios — one behavior per scenario, descriptive names
Refer to references/gherkin-patterns.md for Databricks-specific Gherkin patterns covering:
- Pipeline lifecycle (full refresh, incremental, failure handling)
- Unity Catalog grants, column masks, row filters
- App endpoint testing with SSO headers
- Job/notebook execution and output validation
- SQL data quality assertions
- Scenario Outlines for parameterized testing
3. Gherkin writing principles
Declarative, not imperative. Describe what the system should do, not how to click buttons:
# Good — declarative
When I grant SELECT on "catalog.schema.table" to group "readers"
Then the group "readers" should have SELECT permission
# Bad — imperative
When I open the Catalog Explorer
And I click on the table "catalog.schema.table"
And I click "Permissions"
And I click "Grant"
And I select "SELECT"
And I type "readers" in the group field
And I click "Save"
One behavior per scenario. If a scenario tests two independent things, split it.
Use Backgrounds for shared setup. Avoid repeating connection/schema steps across scenarios.
Scenario Outlines for data variations. When the same behavior is tested with different inputs, use Examples tables instead of duplicating scenarios.
Tag strategically:
@smoke — fast, critical-path tests (< 30 seconds each)@regression — thorough coverage (minutes)@integration — needs live workspace (skip in unit test CI)@slow — pipeline tests, job executions (> 2 minutes)
CRITICAL — Curly braces break step matching. Behave uses the parse library for step matching. {anything} in feature file text is interpreted as a capture group, not a literal. Never use {test_schema}.table_name in feature files — it will fail to match step definitions. Instead, use short table names ("customers") and resolve the schema in step code.
Trailing colons matter. When a step has an attached data table or docstring, the : at the end of the Gherkin line IS part of the step text. The step pattern must include it: @given('a table "{name}" with data:') — not with data (no colon).
4. Validate step coverage
After writing features, check that step definitions exist for all steps:
uv run behave --dry-run
Any undefined steps will be reported with suggested snippets. Hand those to the bdd-steps skill for implementation.
Additional resources
references/gherkin-patterns.md — Complete Databricks Gherkin pattern library with examples for every domain
