databrickslabs 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@slowor@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