@fabricorg/databricks-testkit 0.2.0 → 0.2.2

package/dist/index.d.cts

@@ -332,4 +332,22 @@ interface PollOptions {
 }
 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 EphemeralLakebaseBranch, type ExecutionContext, type LakebaseBranchOptions, type LakebaseCheckOptions, type LakebaseControlClient, 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, createEphemeralLakebaseBranch, createExecutionContext, createLakebaseTestProvider, createMockDatabricksClient, createWorkspaceContext, customLiveCheck, dbtBuildCheck, defineLiveSuite, deleteEphemeralLakebaseBranch, deleteVolumeFile, deltaContractCheck, ensureVolumeDirectory, expectQueryToMatchGolden, expectTable, jobRunCheck, lakebaseCredentialCheck, lakebaseRoundTripCheck, normalizeRow, normalizeVolumeRoot, notebookSubmitCheck, parseStatementRows, pipelineRefreshCheck, renderJUnit, resolveLakebaseProject, resolveProfile, resolveTokenProvider, restrictedPrincipalCheck, runLiveSuite, secretScopeCheck, sqlRoundTripCheck, toLakebaseBranchId, toNamedParameters, unityCatalogAccessCheck, uploadVolumeFile, volumeIOCheck, waitForPipelineUpdate };
+/** Measure the real Statement Execution path and fail when its p95 exceeds the declared budget. */
+declare function performanceBudgetCheck(): LiveCheck;
+/** Prove a failed statement does not poison the session or the next workload. */
+declare function failureRecoveryCheck(): LiveCheck;
+/** Rotate a disposable secret key and remove it. Values are never returned or written to evidence. */
+interface SecretRotationCheckOptions {
+    randomId?: () => string;
+}
+declare function secretRotationCheck(options?: SecretRotationCheckOptions): LiveCheck;
+/** Exercise a complete Delta backup, destructive loss, and restore cycle in the scratch schema. */
+declare function backupRestoreCheck(): LiveCheck;
+/** Prove Delta time-travel rollback returns a corrupted scratch table to its known-good version. */
+declare function rollbackCheck(): LiveCheck;
+/** Certify that the configured SQL warehouse is serverless and usable by the test identity. */
+declare function serverlessComputeCheck(): LiveCheck;
+/** Launch a disposable classic job cluster and require the shared notebook probe to succeed. */
+declare function classicComputeCheck(): LiveCheck;
+
+export { type AppHealthCheckOptions, type AutoLoaderCheckOptions, type CreateContextOptions, type DefinedLiveSuite, type DeltaColumnContract, type DuckDbConnectionLike, type DuckDbContextOptions, type EphemeralLakebaseBranch, type ExecutionContext, type LakebaseBranchOptions, type LakebaseCheckOptions, type LakebaseControlClient, type LiveCheck, type LiveCheckContext, type LiveCheckResult, type LiveCheckStatus, type LiveEvidence, type LiveSuiteRuntime, type LiveSuiteSpec, type MockDatabricksClient, type PollOptions, type RecordedCall, type SecretRotationCheckOptions, TableFixture, type TestProfile, type VolumeIOCheckOptions, type WorkspaceClientLike, type WorkspaceContextOptions, appHealthCheck, assertDeltaContract, autoLoaderIngestionCheck, backupRestoreCheck, classicComputeCheck, compareToGolden, createClientFromEnv, createDuckDbContext, createEphemeralLakebaseBranch, createExecutionContext, createLakebaseTestProvider, createMockDatabricksClient, createWorkspaceContext, customLiveCheck, dbtBuildCheck, defineLiveSuite, deleteEphemeralLakebaseBranch, deleteVolumeFile, deltaContractCheck, ensureVolumeDirectory, expectQueryToMatchGolden, expectTable, failureRecoveryCheck, jobRunCheck, lakebaseCredentialCheck, lakebaseRoundTripCheck, normalizeRow, normalizeVolumeRoot, notebookSubmitCheck, parseStatementRows, performanceBudgetCheck, pipelineRefreshCheck, renderJUnit, resolveLakebaseProject, resolveProfile, resolveTokenProvider, restrictedPrincipalCheck, rollbackCheck, runLiveSuite, secretRotationCheck, secretScopeCheck, serverlessComputeCheck, sqlRoundTripCheck, toLakebaseBranchId, toNamedParameters, unityCatalogAccessCheck, uploadVolumeFile, volumeIOCheck, waitForPipelineUpdate };

package/dist/index.d.ts

@@ -332,4 +332,22 @@ interface PollOptions {
 }
 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 EphemeralLakebaseBranch, type ExecutionContext, type LakebaseBranchOptions, type LakebaseCheckOptions, type LakebaseControlClient, 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, createEphemeralLakebaseBranch, createExecutionContext, createLakebaseTestProvider, createMockDatabricksClient, createWorkspaceContext, customLiveCheck, dbtBuildCheck, defineLiveSuite, deleteEphemeralLakebaseBranch, deleteVolumeFile, deltaContractCheck, ensureVolumeDirectory, expectQueryToMatchGolden, expectTable, jobRunCheck, lakebaseCredentialCheck, lakebaseRoundTripCheck, normalizeRow, normalizeVolumeRoot, notebookSubmitCheck, parseStatementRows, pipelineRefreshCheck, renderJUnit, resolveLakebaseProject, resolveProfile, resolveTokenProvider, restrictedPrincipalCheck, runLiveSuite, secretScopeCheck, sqlRoundTripCheck, toLakebaseBranchId, toNamedParameters, unityCatalogAccessCheck, uploadVolumeFile, volumeIOCheck, waitForPipelineUpdate };
+/** Measure the real Statement Execution path and fail when its p95 exceeds the declared budget. */
+declare function performanceBudgetCheck(): LiveCheck;
+/** Prove a failed statement does not poison the session or the next workload. */
+declare function failureRecoveryCheck(): LiveCheck;
+/** Rotate a disposable secret key and remove it. Values are never returned or written to evidence. */
+interface SecretRotationCheckOptions {
+    randomId?: () => string;
+}
+declare function secretRotationCheck(options?: SecretRotationCheckOptions): LiveCheck;
+/** Exercise a complete Delta backup, destructive loss, and restore cycle in the scratch schema. */
+declare function backupRestoreCheck(): LiveCheck;
+/** Prove Delta time-travel rollback returns a corrupted scratch table to its known-good version. */
+declare function rollbackCheck(): LiveCheck;
+/** Certify that the configured SQL warehouse is serverless and usable by the test identity. */
+declare function serverlessComputeCheck(): LiveCheck;
+/** Launch a disposable classic job cluster and require the shared notebook probe to succeed. */
+declare function classicComputeCheck(): LiveCheck;
+
+export { type AppHealthCheckOptions, type AutoLoaderCheckOptions, type CreateContextOptions, type DefinedLiveSuite, type DeltaColumnContract, type DuckDbConnectionLike, type DuckDbContextOptions, type EphemeralLakebaseBranch, type ExecutionContext, type LakebaseBranchOptions, type LakebaseCheckOptions, type LakebaseControlClient, type LiveCheck, type LiveCheckContext, type LiveCheckResult, type LiveCheckStatus, type LiveEvidence, type LiveSuiteRuntime, type LiveSuiteSpec, type MockDatabricksClient, type PollOptions, type RecordedCall, type SecretRotationCheckOptions, TableFixture, type TestProfile, type VolumeIOCheckOptions, type WorkspaceClientLike, type WorkspaceContextOptions, appHealthCheck, assertDeltaContract, autoLoaderIngestionCheck, backupRestoreCheck, classicComputeCheck, compareToGolden, createClientFromEnv, createDuckDbContext, createEphemeralLakebaseBranch, createExecutionContext, createLakebaseTestProvider, createMockDatabricksClient, createWorkspaceContext, customLiveCheck, dbtBuildCheck, defineLiveSuite, deleteEphemeralLakebaseBranch, deleteVolumeFile, deltaContractCheck, ensureVolumeDirectory, expectQueryToMatchGolden, expectTable, failureRecoveryCheck, jobRunCheck, lakebaseCredentialCheck, lakebaseRoundTripCheck, normalizeRow, normalizeVolumeRoot, notebookSubmitCheck, parseStatementRows, performanceBudgetCheck, pipelineRefreshCheck, renderJUnit, resolveLakebaseProject, resolveProfile, resolveTokenProvider, restrictedPrincipalCheck, rollbackCheck, runLiveSuite, secretRotationCheck, secretScopeCheck, serverlessComputeCheck, sqlRoundTripCheck, toLakebaseBranchId, toNamedParameters, unityCatalogAccessCheck, uploadVolumeFile, volumeIOCheck, waitForPipelineUpdate };

package/dist/index.js

@@ -9,7 +9,7 @@ import { dirname, resolve, basename } from 'path';
 import { waitForDatabricksRun } from '@fabric-harness/databricks';
 export { waitForDatabricksRun, waitForDatabricksStatement } from '@fabric-harness/databricks';
 import { LakebaseDatabaseProvider, exchangeLakebaseCredential } from '@fabricorg/experiments-db-pool';
-import { randomUUID } from 'crypto';
+import { randomUUID, randomBytes } from 'crypto';
 
 // src/context.ts
 function resolveProfile(env = process.env) {
@@ -839,7 +839,214 @@ function autoLoaderIngestionCheck(options = {}) {
     }
   };
 }
+function safeName(prefix) {
+  return `${prefix}_${randomUUID().replaceAll("-", "_")}`;
+}
+function performanceBudgetCheck() {
+  return {
+    id: "performance",
+    description: "SQL Statement Execution p95 stays within the configured latency budget",
+    configured: (env) => Boolean(env.DBX_TEST_PERFORMANCE_P95_MS),
+    async run({ env, warehouse }) {
+      const budgetMs = Number(env.DBX_TEST_PERFORMANCE_P95_MS);
+      const runs = Number(env.DBX_TEST_PERFORMANCE_RUNS ?? 7);
+      if (!Number.isFinite(budgetMs) || budgetMs <= 0) {
+        throw new Error("DBX_TEST_PERFORMANCE_P95_MS must be a positive number");
+      }
+      if (!Number.isInteger(runs) || runs < 3 || runs > 100) {
+        throw new Error("DBX_TEST_PERFORMANCE_RUNS must be an integer from 3 to 100");
+      }
+      await warehouse.query("SELECT 1 AS warmup");
+      const durations = [];
+      for (let index = 0; index < runs; index += 1) {
+        const started = performance.now();
+        await warehouse.query("SELECT 1 AS performance_probe");
+        durations.push(performance.now() - started);
+      }
+      durations.sort((left, right) => left - right);
+      const p95 = durations[Math.ceil(durations.length * 0.95) - 1] ?? 0;
+      if (p95 > budgetMs) {
+        throw new Error(`SQL p95 ${Math.round(p95)}ms exceeded ${budgetMs}ms budget`);
+      }
+      return {
+        runs,
+        p50Ms: Math.round(durations[Math.floor(durations.length * 0.5)] ?? 0),
+        p95Ms: Math.round(p95),
+        budgetMs
+      };
+    }
+  };
+}
+function failureRecoveryCheck() {
+  return {
+    id: "failure-recovery",
+    description: "A failed statement is isolated and a subsequent statement recovers",
+    async run({ warehouse }) {
+      let failedAsExpected = false;
+      try {
+        await warehouse.query("SELECT * FROM __fabric_experiments_expected_missing_table__");
+      } catch {
+        failedAsExpected = true;
+      }
+      if (!failedAsExpected) throw new Error("Injected failure unexpectedly succeeded");
+      const rows = await warehouse.query("SELECT 1 AS recovered");
+      if (Number(rows[0]?.recovered) !== 1) {
+        throw new Error("Statement execution did not recover after the injected failure");
+      }
+      return { injectedFailure: true, recovered: true };
+    }
+  };
+}
+function secretRotationCheck(options = {}) {
+  return {
+    id: "secret-rotation",
+    description: "Databricks secret put, overwrite, metadata verification, and cleanup",
+    configured: (env) => Boolean(env.DBX_TEST_ROTATION_SECRET_SCOPE),
+    async run({ env, client }) {
+      const scope = env.DBX_TEST_ROTATION_SECRET_SCOPE;
+      const key = options.randomId?.() ?? safeName("fx_rotation_probe");
+      const put = async (value) => client.post("/api/2.0/secrets/put", { scope, key, string_value: value });
+      try {
+        await put(randomBytes(32).toString("base64url"));
+        await put(randomBytes(32).toString("base64url"));
+        const listed = await client.get("/api/2.0/secrets/list", {
+          scope
+        });
+        if (!(listed.secrets ?? []).some((secret) => secret.key === key)) {
+          throw new Error(`Rotated secret metadata was not visible in scope ${scope}`);
+        }
+        return { scope, rotated: true, cleanedUp: true };
+      } finally {
+        await client.post("/api/2.0/secrets/delete", { scope, key }).catch(() => void 0);
+      }
+    }
+  };
+}
+function backupRestoreCheck() {
+  return {
+    id: "backup-restore",
+    description: "Delta DEEP CLONE backup restores a dropped scratch table",
+    async run({ warehouse }) {
+      const source = warehouse.qual(safeName("backup_source"));
+      const backup = warehouse.qual(safeName("backup_clone"));
+      try {
+        await warehouse.exec(`CREATE TABLE ${source} USING DELTA AS SELECT 7 AS value`);
+        await warehouse.exec(`CREATE TABLE ${backup} DEEP CLONE ${source}`);
+        await warehouse.exec(`DROP TABLE ${source}`);
+        await warehouse.exec(`CREATE TABLE ${source} DEEP CLONE ${backup}`);
+        const rows = await warehouse.query(`SELECT value FROM ${source}`);
+        if (Number(rows[0]?.value) !== 7) throw new Error("Restored Delta table lost its data");
+        return { restoredRows: rows.length, deepClone: true };
+      } finally {
+        await warehouse.exec(`DROP TABLE IF EXISTS ${source}`).catch(() => void 0);
+        await warehouse.exec(`DROP TABLE IF EXISTS ${backup}`).catch(() => void 0);
+      }
+    }
+  };
+}
+function rollbackCheck() {
+  return {
+    id: "rollback",
+    description: "Delta time-travel rollback restores a known-good table version",
+    async run({ warehouse }) {
+      const table = warehouse.qual(safeName("rollback_probe"));
+      try {
+        await warehouse.exec(`CREATE TABLE ${table} (value INT) USING DELTA`);
+        await warehouse.exec(`INSERT INTO ${table} VALUES (1)`);
+        const history = await warehouse.query(`DESCRIBE HISTORY ${table} LIMIT 1`);
+        const knownGoodVersion = Number(history[0]?.version);
+        if (!Number.isInteger(knownGoodVersion)) {
+          throw new Error("Delta history did not return a known-good version");
+        }
+        await warehouse.exec(`INSERT INTO ${table} VALUES (999)`);
+        await warehouse.exec(`RESTORE TABLE ${table} TO VERSION AS OF ${knownGoodVersion}`);
+        const rows = await warehouse.query(`SELECT value FROM ${table} ORDER BY value`);
+        if (rows.length !== 1 || Number(rows[0]?.value) !== 1) {
+          throw new Error("Delta rollback did not restore the known-good contents");
+        }
+        return { knownGoodVersion, restoredRows: rows.length };
+      } finally {
+        await warehouse.exec(`DROP TABLE IF EXISTS ${table}`).catch(() => void 0);
+      }
+    }
+  };
+}
+function serverlessComputeCheck() {
+  return {
+    id: "azure-serverless",
+    description: "Azure Databricks serverless SQL warehouse is enabled and executes SQL",
+    configured: (env) => Boolean(env.DATABRICKS_WAREHOUSE_ID),
+    async run({ env, client, warehouse }) {
+      const id = env.DATABRICKS_WAREHOUSE_ID;
+      const details = await client.get(`/api/2.0/sql/warehouses/${encodeURIComponent(id)}`);
+      if (details.enable_serverless_compute !== true) {
+        throw new Error(`SQL warehouse ${id} is not configured for serverless compute`);
+      }
+      const rows = await warehouse.query("SELECT current_catalog() AS catalog");
+      return { warehouseId: id, name: details.name, state: details.state, rows: rows.length };
+    }
+  };
+}
+function classicComputeCheck() {
+  return {
+    id: "azure-classic",
+    description: "Azure Databricks classic job cluster starts and completes a notebook workload",
+    configured: (env) => Boolean(
+      env.DBX_TEST_CLASSIC_SPARK_VERSION && env.DBX_TEST_CLASSIC_NODE_TYPE && env.DBX_TEST_NOTEBOOK_PATH
+    ),
+    async run({ env, client }) {
+      const numWorkers = Number(env.DBX_TEST_CLASSIC_WORKERS ?? 1);
+      const alternateNodeTypes = (env.DBX_TEST_CLASSIC_ALTERNATE_NODE_TYPES ?? "").split(",").map((value) => value.trim()).filter(Boolean);
+      const singleNode = numWorkers === 0;
+      const submitted = await client.post("/api/2.1/jobs/runs/submit", {
+        run_name: `fabric-experiments-classic-certification-${Date.now()}`,
+        tasks: [
+          {
+            task_key: "classic_notebook",
+            new_cluster: {
+              spark_version: env.DBX_TEST_CLASSIC_SPARK_VERSION,
+              node_type_id: env.DBX_TEST_CLASSIC_NODE_TYPE,
+              num_workers: numWorkers,
+              data_security_mode: env.DBX_TEST_CLASSIC_SECURITY_MODE ?? "SINGLE_USER",
+              ...env.DBX_TEST_CLASSIC_SINGLE_USER_NAME ? { single_user_name: env.DBX_TEST_CLASSIC_SINGLE_USER_NAME } : {},
+              ...singleNode ? {
+                spark_conf: {
+                  "spark.databricks.cluster.profile": "singleNode",
+                  "spark.master": "local[*]"
+                },
+                custom_tags: { ResourceClass: "SingleNode" }
+              } : {},
+              ...alternateNodeTypes.length ? {
+                worker_node_type_flexibility: {
+                  alternate_node_type_ids: alternateNodeTypes
+                },
+                driver_node_type_flexibility: {
+                  alternate_node_type_ids: alternateNodeTypes
+                }
+              } : {}
+            },
+            notebook_task: { notebook_path: env.DBX_TEST_NOTEBOOK_PATH }
+          }
+        ]
+      });
+      if (!submitted.run_id) throw new Error("Classic compute submit returned no run_id");
+      const run = await waitForDatabricksRun(client, submitted.run_id, {
+        timeoutMs: Number(env.DBX_TEST_CLASSIC_TIMEOUT_MS ?? 18e5),
+        pollIntervalMs: Number(env.DBX_TEST_POLL_INTERVAL_MS ?? 15e3)
+      });
+      const result = run.state?.result_state;
+      if (result !== "SUCCESS") {
+        throw new Error(`Classic compute run ended in ${result ?? "UNKNOWN"}`);
+      }
+      return {
+        runId: submitted.run_id,
+        sparkVersion: env.DBX_TEST_CLASSIC_SPARK_VERSION,
+        nodeType: env.DBX_TEST_CLASSIC_NODE_TYPE
+      };
+    }
+  };
+}
 
-export { appHealthCheck, assertDeltaContract, autoLoaderIngestionCheck, createEphemeralLakebaseBranch, createExecutionContext, createLakebaseTestProvider, createMockDatabricksClient, customLiveCheck, dbtBuildCheck, defineLiveSuite, deleteEphemeralLakebaseBranch, deleteVolumeFile, deltaContractCheck, ensureVolumeDirectory, expectQueryToMatchGolden, expectTable, jobRunCheck, lakebaseCredentialCheck, lakebaseRoundTripCheck, normalizeVolumeRoot, notebookSubmitCheck, pipelineRefreshCheck, renderJUnit, resolveLakebaseProject, resolveProfile, restrictedPrincipalCheck, runLiveSuite, secretScopeCheck, sqlRoundTripCheck, toLakebaseBranchId, unityCatalogAccessCheck, uploadVolumeFile, volumeIOCheck, waitForPipelineUpdate };
+export { appHealthCheck, assertDeltaContract, autoLoaderIngestionCheck, backupRestoreCheck, classicComputeCheck, createEphemeralLakebaseBranch, createExecutionContext, createLakebaseTestProvider, createMockDatabricksClient, customLiveCheck, dbtBuildCheck, defineLiveSuite, deleteEphemeralLakebaseBranch, deleteVolumeFile, deltaContractCheck, ensureVolumeDirectory, expectQueryToMatchGolden, expectTable, failureRecoveryCheck, jobRunCheck, lakebaseCredentialCheck, lakebaseRoundTripCheck, normalizeVolumeRoot, notebookSubmitCheck, performanceBudgetCheck, pipelineRefreshCheck, renderJUnit, resolveLakebaseProject, resolveProfile, restrictedPrincipalCheck, rollbackCheck, runLiveSuite, secretRotationCheck, secretScopeCheck, serverlessComputeCheck, sqlRoundTripCheck, toLakebaseBranchId, unityCatalogAccessCheck, uploadVolumeFile, volumeIOCheck, waitForPipelineUpdate };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map