Testing KDV v26.3+

KDV separates fast script tests from tests that need a running Kubling instance:

Use both levels in CI. Passing an isolated JavaScript test does not prove that the corresponding query, provider or transaction works in a running instance.

Run JavaScript tests

./kdv project test
./kdv project test tests/unit/functions.test.js
./kdv project test tests/unit --timeout 20
./kdv project test --format json

Without an explicit path, KDV discovers tests/**/*.test.js. Discovery is recursive and deterministic. Missing explicit paths, load errors, failed assertions and timeouts return a non-zero exit status. A project with no matching tests exits successfully and reports that no tests were found.

The timeout applies to each test file and defaults to 10 seconds.

Write a JavaScript test

Test files are ECMAScript modules. They can import project files with relative imports and use the test API supplied by KDV:

import { taskFixtures } from "../../module/data/tasks.js"
 
describe("task fixtures", () => {
  test("include the delivery task", () => {
    const tasks = taskFixtures()
 
    expect(tasks).toHaveLength(3)
    expect(tasks[1].id).toBe("task-2")
  })
})

The API provides:

• test and its it alias
• test.skip
• describe
• beforeEach and afterEach
• expect with equality, truthiness, containment, length, pattern and exception matchers
• .not for every matcher

Tests and hooks may use async/await or return a Promise.

Test Kubling scripts

Use kubling.loadFunction(path) for a complete SQL or template function script:

const taskLabel = kubling.loadFunction(
  "../../sql-functions/fn/task_label.js"
)
 
test("formats the label exposed to SQL", () => {
  expect(taskLabel({ id: "task-2", title: "Ship" }))
    .toBe("task-2: Ship")
})

Use kubling.runScript(path, bindings) for endpoint, authentication, scheduler and other imperative scripts. The bindings are normal JavaScript test doubles that define the context used by that test.

Test isolation

Every test file runs in a fresh, restricted JavaScript context:

• project files are available through a read-only project filesystem
• files outside the project are unavailable
• host classes and environment variables are unavailable
• tests cannot create processes, sockets or threads
• stdout and stderr are captured in the report

This keeps the fast test loop deterministic and makes external dependencies explicit at the Compose test level.

Run integration tests

An integration test is a normal service in compose.yaml with the KDV test label:

services:
  smoke:
    profiles: ["test"]
    build:
      context: .
      dockerfile: tests/curl.Dockerfile
    environment:
      KUBLING_BASE_URL: http://kubling:8282
    labels:
      com.kubling.kdv.role: test

Run one or more labelled services in the requested order:

./kdv project run --profile dev smoke
./kdv project run --profile ci smoke rbac transaction

ci is the default profile and does not accept --instance. The dev profile uses the dev instance unless another name is supplied. Services run sequentially and execution stops at the first non-zero service exit. The manifest’s runtime.testTimeout limits each Compose test service and defaults to 60 seconds.

Evidence and CI

Every project run writes an evidence directory below .kdv/reports/. It contains the run result, container logs, input hashes, runtime identity, service durations and any diagnostics or cleanup errors.

A direct CI sequence is:

./kdv project validate --environment local
./kdv project test --format json
./kdv project run --environment local --profile ci smoke rbac transaction

Generated projects expose the same workflow through make test, make integration and make ci.