Tests run against the Dockerized stack. This is not a preference — several suites need
a real Docker socket to spawn sibling Spark containers, and a bare pytest silently
degrades or fails them.
# 1. Build (the image bakes in the source, so a stale image tests old code)
docker compose -f docker-compose.test.yml build
# 2. Run
docker compose -f docker-compose.test.yml up --abort-on-container-exit --exit-code-from test-runner
# 3. Tear down
docker compose -f docker-compose.test.yml down -vOr the wrapper: bash scripts/run-tests-docker.sh.
Always rebuild after changing anything under
src/. The image copies the source at build time. Skipping the build is the most common way to spend an hour debugging a fix that was never running.
tests/conftest.py detects Compose mode via MINILAKE_DATA_DIR=/data and points the SDK at
http://minilake-test-server:8000 instead of spawning a local subprocess.
minilake-test-server is built from the main Dockerfile, which includes the frontend
stage — so tests/test_ui_assets.py exercises the real, served /ui. (Dockerfile.test
has no Node stage; those tests skip if the mount is missing rather than failing.)
The UI's own checks are separate and do not need Docker:
cd ui
pnpm install
pnpm lint
pnpm typecheck
pnpm test # vitest, over the pure helpers in src/lib
pnpm build # static export, also staged into src/minilake/ui_statictests/
├── conftest.py # shared fixtures (server, workspace_client, reset)
├── test_golden_path.py # serial end-to-end workflow
├── test_<service>.py # one file per service
├── unity_catalog/
│ ├── test_catalogs.py test_schemas.py test_tables.py test_volumes.py
│ ├── test_types.py # Databricks→DuckDB type translation
│ ├── test_delta_tables.py # real Delta files
│ └── test_spark_catalog_protocol.py # the wire contract Spark's connector needs
├── error_handling/ # 400 / 404 / 501 shapes
└── mcp_server/ # drives a real MCP ClientSession over Streamable HTTP
Markers: serial (mutates global state or spawns containers), crud, workflow, error.
New endpoints need a test that drives the real databricks-sdk against minilake, not a
handcrafted HTTP call. The SDK is the source of truth for what the API should look like, and
this is what catches request-parsing, response-shape and state-transition bugs that unit
tests miss.
def test_table_metadata_survives_the_round_trip(catalog_and_schema, workspace_client):
cat, schema = catalog_and_schema
created = workspace_client.tables.create(...)
fetched = workspace_client.tables.get(full_name=created.full_name)
assert fetched.properties == {"team": "data"}
assert [c.name for c in fetched.columns] == ["id", "nome"]Tests in tests/mcp_server/ use pytest.mark.anyio, not pytest.mark.asyncio —
pytest-asyncio finalizes async-generator fixtures in a different task than it creates them
in, which trips the MCP client's task group. They live in mcp_server/, not mcp/, because
the latter would shadow the SDK's top-level mcp package.
uv run ruff format src/ tests/
uv run ruff check src/ tests/Both run in CI on every push and PR.
services/<name>.py— a router plusget_state()/restore_state()/reset()models/<name>.py— Pydantic request/response models (not co-located with the service)- Register in
SERVICE_REGISTRYinservices/__init__.py - Implement the endpoints
tests/test_<name>.pywith the real SDK- Update FEATURES.md
If it should also be agent-reachable, add mcp/tools/<name>.py exporting
register(mcp, client) and key it into _TOOL_MODULES in mcp/server.py under its owning
service, so MINILAKE_SERVICES filtering applies automatically.
See CONTRIBUTING.md for the PR checklist.
tests/terraform/ runs the real Databricks Terraform provider against minilake:
apply → plan → destroy over a realistic 15-resource config, asserting that the
second plan is empty.
It needs two things the test image bakes in (see Dockerfile.test): the terraform
binary, and a local mirror of the provider at $MINILAKE_TF_PROVIDER_MIRROR, warmed at
build time so the suite needs no network. Running pytest on the host without terraform
installed skips these tests rather than failing; without the mirror, init falls
back to the registry, which works but needs network.
Both versions are pinned. A conformance test is only meaningful if it keeps testing the same provider — a floating version turns an upstream release into a mysterious CI failure.
The empty second plan is the assertion that earns its keep. A resource minilake accepts
but reports back differently is permanent drift, which is worse than a 501: it looks
like it works until someone runs plan twice. The first run of this test found three
such defects that every SDK-driven test in the suite had missed.