@fabricorg/databricks-testkit

Testing toolkit for Databricks artifacts (ADR-0006). One ExecutionContext, two profiles:

• local — DuckDB in-process (@duckdb/node-api, optional peer). No workspace, no credentials, sub-second. The default.
• live — a real Databricks SQL warehouse via the SQL Statement Execution API, built on @fabric-harness/databricks. Always gated by DBX_TEST_LIVE=1.

Positional ? params work in both profiles — the live context transparently rewrites them to the named markers the Statement Execution API requires.

import { createExecutionContext, expectTable } from '@fabricorg/databricks-testkit';

const ctx = await createExecutionContext(); // DBX_TEST_PROFILE=local|live
await ctx.loadFixture({
  table: 'conversions',
  schema: 'subject_id STRING, value DOUBLE, "at" TIMESTAMP',
  rows: [['s1', 49, '2026-07-01T12:00:00Z']],
});
await expectTable(ctx, 'conversions').toHaveRowCount(1);
await ctx.close();

Cross-engine parity suites

// vitest file — import from the /parity subpath
import { defineParitySuite } from '@fabricorg/databricks-testkit/parity';

defineParitySuite({
  name: 'aggregate-attribution',
  sql: aggregateSql,
  params,
  fixtures: [...],
  golden: 'golden/aggregate-attribution.json',
});

DuckDB must reproduce the committed golden rows on every run; with DBX_TEST_LIVE=1 the same statement also runs on Databricks and both engines must agree. Create/refresh goldens with DBX_TEST_UPDATE_GOLDEN=1 and commit the diff. See src/parity.dogfood.test.ts for the canonical example (it locks the product's own aggregate SQL).

Unit-testing orchestration logic

createMockDatabricksClient() is a framework-free fake of the REST client surface — queue responses per (method, path-prefix) to drive submit → poll → terminal state machines without a workspace.

Live environment

DBX_TEST_LIVE=1
DATABRICKS_HOST=https://<workspace>.cloud.databricks.com
DATABRICKS_HTTP_PATH=/sql/1.0/warehouses/<id>   # or DATABRICKS_WAREHOUSE_ID
DBX_TEST_CATALOG=fx_test
DBX_TEST_SCHEMA=scenarios
# Seeded live tables are replaced on load and dropped on close. For debugging only:
# DBX_TEST_KEEP_FIXTURES=1
# auth precedence: DATABRICKS_BEARER → DATABRICKS_CLIENT_ID/SECRET (OAuth M2M) → DATABRICKS_TOKEN (PAT)

Databricks workload checks

The live suite includes SQL, Delta contracts, Unity Catalog access, Jobs, Lakeflow pipelines, Lakebase credential exchange and provider refresh, Unity Catalog Volume I/O, Databricks Apps/resource health, secret metadata, isolated Auto Loader ingestion, notebook submit, and dbt build. Checks are independently configured and report pass | fail | not-configured; only IDs listed in DBX_TEST_REQUIRED_CHECKS gate a run.

Auto Loader full refreshes require a distinct DBX_TEST_AUTOLOADER_PIPELINE_ID. The check refuses to use DBX_TEST_PIPELINE_ID, protecting production telemetry.

Typed target packs

Target packs bind a workload adapter, offline unit tests, live checks, documentation, certification scope, and Quality Center metadata into one versioned contract. Built-in packs cover SQL/Delta, Lakeflow ingestion, Jobs/code, Unity Catalog storage, Apps operations, Lakeflow Jobs orchestration, advanced streaming/CDC, AI/BI and Genie, MLflow, feature engineering, Model Serving and AI Gateway, Vector Search/RAG/agents, federation/sharing/Clean Rooms, and security/cost/DR.

import {
  builtinTargetPacks,
  createTargetPackRegistry,
  doctorTargetPack,
  runTargetPack,
} from '@fabricorg/databricks-testkit';

const pack = createTargetPackRegistry(builtinTargetPacks).get('lakeflow-jobs');
if (!pack) throw new Error('lakeflow-jobs target pack is not installed');
const diagnosis = doctorTargetPack(pack, process.env);
if (!diagnosis.ready) throw new Error(diagnosis.missing.join(', '));

const evidence = await runTargetPack(pack, {
  env: process.env,
  live: true,
});

The Lakeflow Jobs adapter models notebook, wheel, JAR, Spark Python, submit, pipeline, SQL, dbt, nested-job, condition, and for-each tasks, including graph validation, cancellation, repair, and task-level terminal-state assertions.

Advanced packs use DatabricksAdvancedWorkloadsAdapter, an injectable typed wrapper over the supported pipeline, Lakeview, Genie, MLflow, Unity Catalog, Online/Synced Table, Model Serving, Vector Search, federation, sharing, Clean Room, policy, and warehouse APIs. Pack-required request JSON and SQL assertions exercise the data plane; metadata-only probes are not enough to satisfy a certification-ready doctor result.

Docs: apps/docs/content/docs/testing/ · Plan: .weave/plans/databricks-testing.md · BDD layer: @fabricorg/databricks-bdd (Phase 2).