Testing on Databricks
A layered testing framework for Databricks artifacts — SQL, Delta tables, DLT pipelines, Jobs, Unity Catalog, Lakebase — with first-class BDD support.
Fabric Experiments ships a general-purpose Databricks testing framework, usable by any team building on Databricks — not just consumers of the experimentation platform. It is delivered as two 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.featurefile runs against a local engine and a live workspace.
Status: rolling out per the phases in
.weave/plans/databricks-testing.md. Pages in this section label each capability Available or Planned (Phase N).
The test pyramid
| Tier | Engine | Speed | Needs a workspace? |
|---|---|---|---|
| Unit (mocked client) | injected fake DatabricksRestClient | ms | No |
| Local SQL | DuckDB (delta extension) | ms–s | No |
| Contract / parity | DuckDB + golden fixtures (optionally live) | s | Optional |
| BDD scenarios | either profile | s–min | Optional |
| Live artifact checks | real workspace, gated | min | Yes |
| Ephemeral env (per PR) | scratch UC schema + Lakebase branch | min | Yes |
The design rule: one canonical SQL, two engines. Analytical SQL is emitted
from a single AST (see packages/warehouse)
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:
DATABRICKS_BEARER— pre-minted token (CI; fetch via OAuth M2M in a prior step).DATABRICKS_CLIENT_ID+DATABRICKS_CLIENT_SECRET— OAuth M2M againstDATABRICKS_HOST.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.
Where to go next
- 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.
- Ephemeral environments — per-PR schemas and CI wiring.