databricks-notebook-testing

Files (1)

• SKILL.md

SKILL.md (first lines)

# Databricks Notebook Testing

Use this skill to plan, implement, or review testing and coverage for Databricks
Python-source notebooks and their supporting Python modules.

---

## Load Patterns and Solutions

Read these files for named notebook and resource contract checks:

- `../../catalogs/notebook-resource-contract-patterns.md`
- `../../catalogs/notebook-resource-contract-solutions.md`

---

## Test Boundaries

**Use when:** A workflow mixes pure rules, Spark transformations, notebook wiring, and managed-service I/O.

- Test pure rules, mappings, validators, and plans with ordinary unit tests.
- Test DataFrame transformations with synthetic local Spark inputs and explicit failure cases.
- Test stable notebook contracts from source when they cannot run locally.
- Test managed-runtime wiring only in an authorized, isolated non-production environment.
- Test ordinary Python modules by behavior, regardless of whether a notebook imports them.

---

## Local Spark Tests

**Use when:** A transformation accepts explicit DataFrames or values.

- Reuse one session-scoped local Spark session as the shared context owner with
  its UI disabled; do not mutate it in tests.
- Configure that session in its builder: a small `spark.sql.shuffle.partitions`
  (for example 1–4) for speed, and `spark.sql.ansi.enabled` pinned to the target
  runtime's value so ANSI cast, parse, and arithmetic failures surface locally.
- Derive a fresh session with `newSession()` per test and set its timezone explicitly.
- During teardown, clear shared caches and global temporary views, then discard
  the test-session reference; do not call `stop()` on either session because both
  own the same Spark context.
- Build minimal synthetic inputs for success, empty, null, boundary, and rejection cases relevant to the transformation.
- Compare DataFrames with `pyspark.testing.assertDataFrameEqual` and schemas with
  `assertSchemaEqual` (Spark 3.5+) instead of hand-rolled `collect()` comparisons;
  row order is ignored unless `checkRowOrder=True`; set `rtol`/`atol` for floats.
- Assert schemas, values, row-level invariants, and expected failures; do not assert incidental execution-plan details.
- Do not read production tables, storage, secrets, or external services from local tests.

---

## Coverage Scope

**Use when:** Configuring coverage or reviewing an omitted notebook or module.

- Include business decisions, transformations, validation, and error handling in coverage evidence regardless of file name.
- Exclude only unavoidable platform glue or truly constant-only code.
- For each exclusion, record its reason, alternate evidence, owner, and re-entry trigger.
- Require direct tests or extraction when an excluded region gains a decision, transformation, validation, or external-service branch.
- Report the collection command, included and excluded scope, line or branch policy, threshold, and report consumer; do not present a percentage without its scope.

---

## Source Contracts

**Use when:** A notebook contract must remain stable but managed-runtime execution is unavailable.

- Use source checks only for contracts already defined by the owning notebook, pipeline, or platform guidance.
- Assert stable, behavior-relevant signals from those contracts; avoid formatting, production paths, temporary names, and unrelated literals.
- Treat source checks as evidence for wiring contracts, not proof that managed services execute correctly.

---

## Managed Runtime Evidence

**Use when:** Verifying workspace utilities, storage, JDBC, secret managers, or other managed services.

- Do not claim local tests prove managed-runtime behavior.
- Add a managed smoke test only after inputs, outputs, credentials, and logs are isolated from production.
- Use synthetic or approved anonymized data with cleanup, failure handling, and an accountable owner.
- Keep managed smoke tests narrow; retain business-rule coverage in fast local tests.

---

## Environment Parity

**Use when:** Comparing local and CI results or diagnosing an environment-specific failure.

- Record Python, Java, Spark, resolved dependencies, environment-variable names,
  test command, and result for each environment.
- Record only allowlisted non-sensitive environment values; redact credentials,
  secrets, and tokens from reports and logs.
- Mark unavailable CI evidence as unavailable; do not infer equivalence from a shared test name.
- Measure total duration and slowest tests before introducing Spark-heavy checks; agree any enforcement threshold separately.

---

## Agent Output

**Use when:** An agent prepares a testing or coverage change.

- State the behavior, test boundary, fixture/data strategy, failure case, coverage scope, verification command, and managed-runtime assumptions.
- Apply the repository's coverage threshold and do not weaken it in skill output.
- Treat CI, governance, and package-source rules as optional local adapters.

From mabrosim/aet-content-pack, MIT.

More from mabrosim/aet-content-pack