@fabricorg/databricks-testkit 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,301 @@
+import { T as TableFixture } from './fixtures-CAWhzIHu.js';
+export { F as FixtureColumn, p as parseFixtureColumns, r as resolveFixtureRows } from './fixtures-CAWhzIHu.js';
+import { DatabricksRestClient } from '@fabric-harness/databricks';
+export { waitForDatabricksRun, waitForDatabricksStatement } from '@fabric-harness/databricks';
+import { LakebasePoolFactory, LakebaseDatabaseProvider } from '@fabricorg/experiments-db-pool';
+
+type TestProfile = 'local' | 'live';
+/**
+ * One SQL surface, two engines (ADR-0006). `local` executes on DuckDB
+ * in-process; `live` executes on a Databricks SQL warehouse via the SQL
+ * Statement Execution API. Params are positional `?` in both profiles — the
+ * workspace context transparently rewrites them to the named markers the
+ * Statement Execution API requires.
+ */
+interface ExecutionContext {
+    readonly profile: TestProfile;
+    /** Execute a statement, discarding any result. */
+    exec(sql: string, params?: readonly unknown[]): Promise<void>;
+    /** Execute a query and return normalized row objects (bigint→number, timestamps→ISO). */
+    query(sql: string, params?: readonly unknown[]): Promise<Record<string, unknown>[]>;
+    /** Create + seed a table from a declarative fixture. */
+    loadFixture(fixture: TableFixture): Promise<void>;
+    /** Qualify a bare table name for this context (schema/catalog scoping). */
+    qual(table: string): string;
+    close(): Promise<void>;
+}
+declare function resolveProfile(env?: Record<string, string | undefined>): TestProfile;
+interface CreateContextOptions {
+    profile?: TestProfile;
+    env?: Record<string, string | undefined>;
+    /** local profile: schema to create + qualify tables with. live profile: schema within the catalog. */
+    schema?: string;
+    /** Live profile only: observe each submitted SQL statement. */
+    onStatement?: (statement: {
+        sql: string;
+        statementId?: string;
+    }) => void;
+}
+/** Profile-dispatched factory. Lazy-imports each engine so the unused one stays out of the bundle. */
+declare function createExecutionContext(options?: CreateContextOptions): Promise<ExecutionContext>;
+
+interface DuckDbContextOptions {
+    /** Database file path; ':memory:' (default) for a throwaway in-process db. */
+    path?: string;
+    /** Optional schema to create + qualify tables with. */
+    schema?: string;
+    /** Injectable for tests of this module itself. */
+    connectionFactory?: (path: string) => Promise<DuckDbConnectionLike>;
+}
+/** Structural slice of the lazily-imported @duckdb/node-api connection. */
+interface DuckDbConnectionLike {
+    run(sql: string, values?: unknown[]): Promise<unknown>;
+    runAndReadAll(sql: string, values?: unknown[]): Promise<{
+        getRowObjects(): Record<string, unknown>[];
+    }>;
+    closeSync(): void;
+}
+/**
+ * Hermetic local execution context on DuckDB — the `local` profile of the
+ * testing pyramid. No workspace, no credentials, sub-second.
+ */
+declare function createDuckDbContext(options?: DuckDbContextOptions): Promise<ExecutionContext>;
+/**
+ * Normalize DuckDB values to plain JSON-ish values so assertions and golden
+ * files are engine-portable: bigint→number, TIMESTAMP→`YYYY-MM-DD HH:MM:SS`
+ * (UTC, microseconds trimmed), DECIMAL→number.
+ */
+declare function normalizeRow(row: Record<string, unknown>): Record<string, unknown>;
+
+/** Structural slice of DatabricksRestClient the workspace context uses (injectable in tests). */
+interface WorkspaceClientLike {
+    get<T>(path: string, query?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    post<T>(path: string, body?: unknown, query?: Record<string, string | number | boolean | undefined>, options?: unknown): Promise<T>;
+}
+interface WorkspaceContextOptions {
+    env?: Record<string, string | undefined>;
+    /** Schema within the catalog used by qual(); defaults to DBX_TEST_SCHEMA. */
+    schema?: string;
+    /** Injectable client for hermetic tests; defaults to a DatabricksRestClient from env auth. */
+    client?: WorkspaceClientLike;
+    /** Injectable fetch for the OAuth M2M exchange. */
+    fetchImpl?: typeof fetch;
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+    /** Drop tables seeded by this context on close. Defaults to true. */
+    cleanupFixtures?: boolean;
+    /** Observe submitted statements for redacted failure evidence. */
+    onStatement?: (statement: {
+        sql: string;
+        statementId?: string;
+    }) => void;
+}
+interface StatementResponse {
+    statement_id?: string;
+    status?: {
+        state?: string;
+        error?: {
+            message?: string;
+        };
+    };
+    manifest?: {
+        schema?: {
+            columns?: {
+                name: string;
+                type_name?: string;
+                position?: number;
+            }[];
+        };
+    };
+    result?: {
+        data_array?: (string | null)[][];
+    };
+}
+/**
+ * Live execution context on a Databricks SQL warehouse via the SQL Statement
+ * Execution API (/api/2.0/sql/statements). The Statement Execution API takes
+ * NAMED parameter markers, so positional `?` params are rewritten to
+ * `:p1..:pn` — the ExecutionContext surface stays identical to the local
+ * profile.
+ */
+declare function createWorkspaceContext(options?: WorkspaceContextOptions): Promise<ExecutionContext>;
+/** Rewrite positional `?` markers to the named `:pN` markers the Statement Execution API requires. */
+declare function toNamedParameters(sql: string, params: readonly unknown[]): {
+    statement: string;
+    parameters: {
+        name: string;
+        value: string | null;
+    }[];
+};
+/** Map a terminal statement response to normalized row objects. */
+declare function parseStatementRows(response: StatementResponse): Record<string, unknown>[];
+/**
+ * Auth precedence (ADR-0006): DATABRICKS_BEARER (pre-minted, CI) →
+ * DATABRICKS_CLIENT_ID/SECRET (OAuth M2M) → DATABRICKS_TOKEN (PAT).
+ */
+declare function createClientFromEnv(env: Record<string, string | undefined>, fetchImpl?: typeof fetch): DatabricksRestClient;
+declare function resolveTokenProvider(host: string, env: Record<string, string | undefined>, fetchImpl?: typeof fetch): string | (() => Promise<string>);
+
+/**
+ * Framework-free table assertions — they throw plain Errors so they work
+ * under vitest, cucumber-js steps, or the live check runner alike.
+ */
+declare function expectTable(ctx: ExecutionContext, table: string): {
+    toHaveRowCount(expected: number): Promise<void>;
+    /** Every partial row must match at least one table row on its own keys. */
+    toContainRows(partials: readonly Record<string, unknown>[]): Promise<void>;
+    /**
+     * Compare `SELECT * ORDER BY <orderBy>` against a committed golden JSON
+     * file. Set DBX_TEST_UPDATE_GOLDEN=1 to (re)write the golden instead —
+     * a reviewable, versioned event.
+     */
+    toMatchGolden(goldenPath: string, options?: {
+        orderBy?: string;
+    }): Promise<void>;
+};
+/** Compare query results (not a whole table) against a golden file. */
+declare function expectQueryToMatchGolden(ctx: ExecutionContext, sql: string, params: readonly unknown[], goldenPath: string): Promise<void>;
+
+/**
+ * Golden-result files: committed JSON snapshots of query results that every
+ * engine and every refactor must reproduce exactly — the frozen-vector
+ * pattern from @fabricorg/experiments-testkit generalized to warehouse rows.
+ */
+declare function compareToGolden(goldenPath: string, actual: readonly Record<string, unknown>[], label: string, env?: Record<string, string | undefined>): Promise<void>;
+
+/**
+ * Framework-free fake of the Databricks REST client surface, for unit tests
+ * of orchestration logic (submit → poll → terminal). Queue responses per
+ * (method, path-prefix); every call is recorded for assertions. Works under
+ * vitest without vi.fn so it is equally usable from cucumber-js worlds.
+ */
+interface RecordedCall {
+    method: 'GET' | 'POST';
+    path: string;
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+}
+interface MockDatabricksClient {
+    get<T>(path: string, query?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    post<T>(path: string, body?: unknown, query?: Record<string, string | number | boolean | undefined>, options?: unknown): Promise<T>;
+    /** Queue the next response for calls whose path starts with `pathPrefix`. FIFO per prefix. */
+    queue(method: 'GET' | 'POST', pathPrefix: string, response: unknown): MockDatabricksClient;
+    /** Queue an error for the next matching call. */
+    queueError(method: 'GET' | 'POST', pathPrefix: string, error: Error): MockDatabricksClient;
+    readonly calls: readonly RecordedCall[];
+    callsTo(method: 'GET' | 'POST', pathPrefix: string): RecordedCall[];
+}
+declare function createMockDatabricksClient(): MockDatabricksClient;
+
+type LiveCheckStatus = 'pass' | 'fail' | 'not-configured';
+interface LiveCheckContext {
+    env: Record<string, string | undefined>;
+    warehouse: ExecutionContext;
+    client: WorkspaceClientLike;
+}
+interface LiveCheck {
+    id: string;
+    description: string;
+    configured?: (env: Record<string, string | undefined>) => boolean;
+    run(context: LiveCheckContext): Promise<unknown>;
+}
+interface LiveCheckResult {
+    id: string;
+    description: string;
+    status: LiveCheckStatus;
+    durationMs: number;
+    details?: unknown;
+    error?: string;
+}
+interface LiveEvidence {
+    schemaVersion: 1;
+    kind: 'databricks-live-suite';
+    startedAt: string;
+    finishedAt: string;
+    success: boolean;
+    required: string[];
+    results: LiveCheckResult[];
+}
+interface LiveSuiteSpec {
+    checks: readonly LiveCheck[];
+    required?: readonly string[];
+    evidencePath?: string;
+    junitPath?: string;
+    env?: Record<string, string | undefined>;
+}
+interface LiveSuiteRuntime {
+    warehouse?: ExecutionContext;
+    client?: WorkspaceClientLike;
+}
+interface DefinedLiveSuite {
+    run(runtime?: LiveSuiteRuntime): Promise<LiveEvidence | undefined>;
+}
+/**
+ * Define an explicitly gated live suite. Without DBX_TEST_LIVE=1, run() is a
+ * silent no-op so the same command is safe in ordinary CI matrices.
+ */
+declare function defineLiveSuite(spec: LiveSuiteSpec): DefinedLiveSuite;
+declare function runLiveSuite(spec: LiveSuiteSpec, runtime?: LiveSuiteRuntime): Promise<LiveEvidence | undefined>;
+declare function renderJUnit(evidence: LiveEvidence): string;
+
+declare function sqlRoundTripCheck(): LiveCheck;
+interface DeltaColumnContract {
+    name: string;
+    type?: string;
+}
+declare function assertDeltaContract(table: string, rows: readonly Record<string, unknown>[], columns: readonly DeltaColumnContract[]): void;
+declare function deltaContractCheck(tableEnv?: string, columns?: readonly DeltaColumnContract[]): LiveCheck;
+declare function unityCatalogAccessCheck(): LiveCheck;
+declare function jobRunCheck(): LiveCheck;
+/** Trigger the deployed Lakeflow pipeline and require a completed update. */
+declare function pipelineRefreshCheck(): LiveCheck;
+declare function notebookSubmitCheck(): LiveCheck;
+declare function dbtBuildCheck(): LiveCheck;
+/** Wrap product-specific checks such as Auto Loader, Lakebase, notebooks, or dbt. */
+declare function customLiveCheck(id: string, description: string, run: LiveCheck['run'], configured?: LiveCheck['configured']): LiveCheck;
+
+interface LakebaseCheckOptions {
+    fetchImpl?: typeof fetch;
+    poolFactory?: LakebasePoolFactory;
+}
+declare function createLakebaseTestProvider(env: Record<string, string | undefined>, options?: LakebaseCheckOptions): LakebaseDatabaseProvider;
+/** Verify the workspace identity can exchange a short-lived Lakebase credential. */
+declare function lakebaseCredentialCheck(options?: LakebaseCheckOptions): LiveCheck;
+/** Exercise the production provider before and after an explicit credential/pool refresh. */
+declare function lakebaseRoundTripCheck(options?: LakebaseCheckOptions): LiveCheck;
+
+/** Assert secret key metadata only; values are never requested. */
+declare function secretScopeCheck(): LiveCheck;
+interface AppHealthCheckOptions {
+    fetchImpl?: typeof fetch;
+}
+/** Verify app state, resource bindings, and the gateway-authenticated application health route. */
+declare function appHealthCheck(options?: AppHealthCheckOptions): LiveCheck;
+
+interface VolumeIOCheckOptions {
+    fetchImpl?: typeof fetch;
+    randomId?: () => string;
+}
+declare function normalizeVolumeRoot(value: string): string;
+declare function ensureVolumeDirectory(env: Record<string, string | undefined>, directory: string, fetchImpl?: typeof fetch): Promise<void>;
+declare function uploadVolumeFile(env: Record<string, string | undefined>, path: string, body: BodyInit | Uint8Array, fetchImpl?: typeof fetch): Promise<void>;
+declare function deleteVolumeFile(env: Record<string, string | undefined>, path: string, fetchImpl?: typeof fetch): Promise<void>;
+/** Upload, download, and delete a small probe through the Databricks Files API. */
+declare function volumeIOCheck(options?: VolumeIOCheckOptions): LiveCheck;
+
+interface AutoLoaderCheckOptions {
+    fetchImpl?: typeof fetch;
+    fixtureBody?: Uint8Array;
+    randomId?: () => string;
+}
+/** Exercise Files API -> isolated Lakeflow pipeline -> Delta output. */
+declare function autoLoaderIngestionCheck(options?: AutoLoaderCheckOptions): LiveCheck;
+
+interface PollOptions {
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+declare function waitForPipelineUpdate(client: WorkspaceClientLike, pipelineId: string, updateId: string, options?: PollOptions): Promise<Record<string, unknown>>;
+
+export { type AppHealthCheckOptions, type AutoLoaderCheckOptions, type CreateContextOptions, type DefinedLiveSuite, type DeltaColumnContract, type DuckDbConnectionLike, type DuckDbContextOptions, type ExecutionContext, type LakebaseCheckOptions, type LiveCheck, type LiveCheckContext, type LiveCheckResult, type LiveCheckStatus, type LiveEvidence, type LiveSuiteRuntime, type LiveSuiteSpec, type MockDatabricksClient, type PollOptions, type RecordedCall, TableFixture, type TestProfile, type VolumeIOCheckOptions, type WorkspaceClientLike, type WorkspaceContextOptions, appHealthCheck, assertDeltaContract, autoLoaderIngestionCheck, compareToGolden, createClientFromEnv, createDuckDbContext, createExecutionContext, createLakebaseTestProvider, createMockDatabricksClient, createWorkspaceContext, customLiveCheck, dbtBuildCheck, defineLiveSuite, deleteVolumeFile, deltaContractCheck, ensureVolumeDirectory, expectQueryToMatchGolden, expectTable, jobRunCheck, lakebaseCredentialCheck, lakebaseRoundTripCheck, normalizeRow, normalizeVolumeRoot, notebookSubmitCheck, parseStatementRows, pipelineRefreshCheck, renderJUnit, resolveProfile, resolveTokenProvider, runLiveSuite, secretScopeCheck, sqlRoundTripCheck, toNamedParameters, unityCatalogAccessCheck, uploadVolumeFile, volumeIOCheck, waitForPipelineUpdate };