Testing on Databricks

Fabric Experiments ships a general-purpose Databricks testing framework for any team building on Databricks—not only users of the experimentation product. Start locally with no credentials, then run the same readable scenarios against an isolated workspace environment. It is delivered as two public npm packages:

• @fabricorg/databricks-testkit — execution contexts, fixtures, assertions, a live artifact-check runner, and poll-to-terminal helpers for long-running operations (job runs, DLT updates).
• @fabricorg/databricks-bdd — a Gherkin step library (cucumber-js) bound to the testkit, so the same .feature file runs against a local engine and a live workspace.

Status: Available. The published packages are exercised from a separate public consumer repository. Azure serverless and one Azure classic-compute configuration have live evidence; AWS and GCP are not certified targets. See the compatibility matrix for exact boundaries.

Choose your path

Run a first scenario

Copy, run, and understand a complete local BDD project in about ten minutes. Then move the same feature to an isolated Databricks schema.

Understand every CI check

Learn what full Linux, Windows, integration, browser, boundary, and BDD mean, which risk each layer covers, and the exact commands to reproduce them.

Evaluate against Behave

Compare hooks, World/context state, cleanup, parameters, reports, output capture, tags, parallelism, and the TypeScript migration model.

Design a production suite

Add domain steps, live checks, ephemeral resources, restricted identities, evidence, resilience checks, and CI promotion gates.

Run a Databricks target pack

Discover the shipped packs, validate configuration, run live checks, use the typed Lakeflow Jobs adapter, and publish evidence to Quality Center.

Browse every shipped step

Use the generated wording catalog for SQL, tables, golden files, Jobs, Lakeflow, Volumes, Lakebase, notebooks, dbt, and governance.

The test pyramid

The design rule is one canonical SQL model, two engines. Analytical SQL is emitted from one shared representation and executed on DuckDB in development and CI, and on Databricks SQL warehouses in production—with a parity suite proving both return identical results.

Execution profiles

Every test binds to an ExecutionContext selected by DBX_TEST_PROFILE:

• local (default) — DuckDB in-process. No credentials, no network, sub-second.
• live — Databricks SQL Statement Execution API against a real workspace.

Scenarios that only make sense live (@jobs, @dlt, @lakebase, @live) are skipped automatically under the local profile.

Authentication (live profile)

In order of precedence:

1. DATABRICKS_BEARER — pre-minted token (CI; fetch via OAuth M2M in a prior step).
2. DATABRICKS_CLIENT_ID + DATABRICKS_CLIENT_SECRET — OAuth M2M against DATABRICKS_HOST.
3. DATABRICKS_TOKEN — personal access token.

Live suites are additionally gated by DBX_TEST_LIVE=1 and exit silently when it is unset, so they are safe to include in any CI matrix.

Use a dedicated scratch schema. The test identity needs CAN USE on the SQL warehouse, USE CATALOG, and ownership or fixture read/write privileges on that schema. The quickstart provides the exact checklist and troubleshooting table.

Where to go next

• BDD quickstart — install, run, inspect reports, and switch to live.
• Verification layers and commands — understand and run Linux, Windows, integration, browser, boundary, and BDD checks.
• What to test, per artifact — the coverage matrix.
• Local testing — DuckDB contexts, mocks, fixtures, parity.
• Behavior-driven testing — Gherkin features and the step library.
• Live artifact checks — gated suites against a real workspace.
• Databricks target packs — available packs, configuration, execution, evidence, and current boundaries.
• Ephemeral environments — per-PR schemas and CI wiring.
• Advanced Databricks BDD — extension and production patterns.
• Certification evidence — what has actually run, where, and when.