Graphden documentation

Tests — the tests namespace convention

Graphden’s analogue of a unit-test suite (Roadmap Block 3.1). No new entity, field, or edge (PHILOSOPHY § “Tests are not a new entity or field”): a test is an ordinary fn, discovered by namespace convention, executed through the ordinary execute pipeline, its status derived from ordinary :fn-execution rows.

The convention

A test is a fn that:

A test passes when it executes without a throw.

Server predicate: graphden.crud.test-runs/test-ns-path?; JS mirror: isTestNsPath in editor-tests.js — keep the two in sync.

Assertion vocabulary (core.logic)

Neither takes a message slot (principle 6): the test’s NAME labels the invariant, the error data carries the operands — and an optional slot would surface as a free arg on every assert-composed test, breaking zero-arg runnability. Failing operands ride :error-data, never the visible message (secret-redaction rides the standard execute-pipeline scrub chain).

;; myproj.tests
{:name :sum-works
 :parent :assert-eq
 :args {:actual {:parent :add :args {:nums [2 2]}}
        :expected 4}}

Running and statuses

Both endpoints are branch-scoped (X-Graphden-Branch / per-branch routing) and auth-required. Core: src/graphden/crud/test_runs.clj; the HTTP face is the app/test-api package module (thin :_tests-run-apply / :_tests-status-apply boundary base-fns + graph composition).

Editor surfaces

Auto-run on writes (phase 2)

When a graph write lands, crud.entities/invalidate! already knows the affected fn-id seeds and branch; crud.test-autorun/ schedule-affected! rides that hook (a best-effort sibling of the service-restart blast):

  1. reverse transitive closure of the seeds over the ctx’s :compile-deps index (transitive-blast — the same walk the service restart uses), intersected with the branch’s tests;
  2. purity gate — only tests whose recorded effect closure is EMPTY auto-run; an effectful test (:network, :db, …) runs only from the explicit Run button. Unknown closure counts as NOT pure;
  3. the run executes under :allowed-effects #{} — a hidden effect the static closure missed throws :execution/forbidden-effect instead of silently firing (the tenancy-gate stance: don’t trust the static set);
  4. debounced per [org branch] (500 ms, bursts coalesce), capped at 25 tests per pass (*max-auto-run*; tests beyond the cap retain their previous status), off-switch *auto-run?*;
  5. the runner future conveys the writing request’s dynamic bindings — tests execute under the writer’s org, exactly as the writer would run them;
  6. on completion a best-effort test:updated NOTIFY nudges SSE listeners.

Cold ctx (:compile-deps nil — fresh boot, post-full-clear) → no-op, same contract as the service-restart blast; the Run button always works. Single-pod semantics: the hook fires on the pod that took the write; statuses land in shared storage either way.

Platform tests

The shipped packages carry their own tests, the same way a project does: core.tests, web.tests, app.common.tests (app-base), app.tests, app.registry.tests (registry) — and the external mathx.tests. Each is an ordinary tests module in its package (resources/packages/<pkg>/tests/fns.edn), synced into every instance with the rest of the package, :assert-eq / :assert over the package’s own fn-defs with inputs pinned. They are the graph-level analogue of the Clojure unit suite for the fn-def layer: a base-fn’s Clojure test pins the impl, a platform test pins the COMPOSITION a package builds on it.

Platform tests are tests like any other — discovered, listed under the ✓ tests filter with their status dots, runnable one at a time from the Inspector — with one explicit difference: an all-tests run skips them unless asked. POST /api/tests/run (and the MCP run-tests tool) take platform?; without it only the org’s own tests run, so a tenant’s [Run all] spends the org’s execution budget on the org’s tests. The ✓ chip counts the same set [Run all] runs. The status rows carry platform? (test-runs/platform-test-row? — packages.owned/owned-fn-id?, i.e. package-synced this boot; a property of the deployment, not a column).

Auto-run is unchanged for them: a platform test re-runs when something in its dependency closure is written — which, since platform fns are package-guarded, means a branch that deliberately shadows a platform fn. That is the case where you want them: change :add on a branch and the core.tests covering it go red there.

The gate is the Clojure anchor packages.platform-tests-test: it boots the full first-party bundle and runs {:platform? true} — every platform test must pass, none may be not-runnable. A red platform test lands nowhere. It costs ~9 min of the integration suite (360 tests, sequential, through the full pipeline) — the price of running them the way a user’s tests run, not through a shortcut.

Authoring rules for a tests module: pure subjects only (no :db / :network / :time / :env — those never auto-run and would need a live system in CI); one invariant per test, named after it; _-private helpers are scaffolding and must be referenced (bb graph-lint); verify through /mcp on a bb wt up stack before copying the EDN into the module (CLAUDE.md § Live graph verification).

Coverage of the fn-def and package layers

Tests that load the shipped app and exercise HTTP handlers through the graph belong in ^:integration graph-test namespaces, using the shared golden-app fixture. Keep direct small-graph mutation checks in the unit coverage suite. For example, view-save-graph-test checks HTTP Save through saved-function Run; view-save-test covers filter persistence, authorization, rollback and type publication under instrumentation. Both suites retain the normal abort-shield deadline; abort-shield-test also checks its timeout and interrupt contracts.

The local worktree landing gate runs plain unit tests. For release proof, dispatch CI on develop with expected_sha (all 40 hex characters) and a fresh request_id UUID; this run includes coverage. The guard rejects a moved ref, and release tooling waits for that exact successful run before changing pins.

Three different things are measured, and they answer different questions (bb coverage docstring + feedback_coverage_measurement):

The editor e2e suite at the gate

tools/browser-test/run-edit-tests.sh runs every edit-*.test.js against a live editor; the landing gate runs it through bb test-e2e with WTQ_FLAKE_STRICT=1. A passed retry is credited and every failed attempt remains in the log with its diagnostic signature. What remains red:

Per-file bookkeeping is kept cheap on purpose — one scope=index read per sample for both counts, executor memory from its cgroup — and the lesson walks settle each spotlight ring on the audit’s recorded key rather than a fixed sleep; see the runner’s header.

Known limitations