Test a Touba program

Test business results, authority enforcement and observed effects separately. A refused run may validate a security control without completing the business task.

Start without a model

Install the JavaScript SDK from the Touba distribution, then use batch.tb from the parallel processing tutorial. The following test executes that program through the installed CLI.

batch.test.mjs

import test from "node:test";
import { ToubaEngine } from "@touba/sdk";
import { assertRunSucceeded, assertRunRefused } from "@touba/sdk/testing";

const engine = new ToubaEngine({ projectRoot: process.cwd() });
const options = {
  source: "batch.tb",
  entryRef: "strategy:examples.parallel_batch/Run",
};

test("preserves input order and handles an empty batch", async () => {
  assertRunSucceeded(
    await engine.run({ ...options, inputs: { tickets: ["T-3", "T-1"] } }),
    ["Ticket: T-3", "Ticket: T-1"],
  );
  assertRunSucceeded(
    await engine.run({ ...options, inputs: { tickets: [] } }),
    [],
  );
});

test("refuses a batch above the declared limit", async () => {
  await assertRunRefused(
    () => engine.run({ ...options, inputs: { tickets: Array(9).fill("T") } }),
    "ParallelItemLimitExceeded",
  );
});

Run node --test batch.test.mjs from that directory. No handler, network or model is needed. A compile or launch failure cannot satisfy assertRunRefused: it requires a runtime refusal with the exact code.

With agents and tools

The @touba/sdk/testing submodule also provides createScriptedDecisionProvider and assertTraceEvents. A scripted provider fixes model proposals to test a flow deterministically; it replaces neither runtime controls nor tests with a real model. Check its expectations and call assertConsumed() to detect a partially exercised scenario.

A trace event alone does not prove an effect at a provider. With a handler, also observe the resulting file, database row or receipt in an isolated test environment.

Python equivalents

The Python SDK provides the same helpers in touba_sdk.testing. Scenarios, Touba contracts and expected codes remain the same.

JavaScript	Python
assertRunSucceeded	assert_run_succeeded
assertRunRefused	assert_run_refused
assertTraceEvents	assert_trace_events
createScriptedDecisionProvider	create_scripted_decision_provider
provider.assertConsumed()	provider.assert_consumed()

Cases to cover

• Exact result and input/output types.
• Empty collection, reached bound and exceeded bound.
• Undeclared capability and unauthorized caller.
• Rejected, expired or replayed approval.
• Pause/resumption without repeating an already confirmed effect.
• Concurrent runs with shared budgets.

The SDK guide details the four testing helpers. Diagnostics lists the codes to assert.