TypeScript SDK Testing

@solwyn/sdk/testing provides an in-process FakeControlPlane that speaks the same strict wire models as the production control plane. It opens no socket and never needs a Solwyn credential.

The fake replaces only the Solwyn control-plane boundary. Provider calls are separate: use a mock provider when an allowed call can reach provider dispatch, or use the exported denial-only sentinel when the test must prove that a hard denial happens before dispatch.

Test a hard denial

import { BudgetExceededError } from "@solwyn/sdk";
import {
  denialOnlyOpenAIClient,
  FakeControlPlane,
} from "@solwyn/sdk/testing";
import { expect, test } from "vitest";

test("a hard denial never reaches the provider", async () => {
  const plane = new FakeControlPlane();
  plane.denyNext();

  const client = plane.wrap(denialOnlyOpenAIClient(), {
    leaseEnabled: false,
    model: "gpt-4o",
  });

  try {
    await expect(client.chat.completions.create()).rejects.toBeInstanceOf(
      BudgetExceededError,
    );
  } finally {
    await client.close();
  }

  expect(plane.checks).toHaveLength(1);
  expect(plane.denialReceipts).toHaveLength(1);
  expect(plane.unmatchedRequests).toEqual([]);
});

denialOnlyOpenAIClient() throws if provider dispatch is reached. Do not use it for an allowed or fail-open call; supply your own provider-shaped mock for those tests.

Inspect recorded traffic

Each plane exposes the parsed requests it accepted:

stoppedRuns returns the run IDs currently stopped with stopRun() and their reasons.

The fake validates request and response shapes, reservation identity, lease generations, duplicate settlement, and ingest behavior. It enforces the server's 1,000-event metadata batch limit, the 100-report untracked batch limit, the 256 KiB untracked body limit, unique untracked keys within a batch, and project matching for breaker reports, and returns indexed rejected and duplicates arrays. It does not compute prices or decrement a running dollar budget. Constructor values such as budgetLimit, currentUsage, and remainingBudget are fixed state that you provide.

plane.wrap(client, options) builds a Solwyn wrapper wired to the fake. It rejects apiKey, apiUrl, and fetch options with TypeError, neutralizes any SOLWYN_* environment values, and defaults budgetCheckCacheTtl to 0.

Call resetRecording() to clear recorded arrays without replacing the plane's scripted state. Create a fresh FakeControlPlane for each test when you need complete isolation.

Script scenarios

Windowed scenario methods such as outage() and slow() return a ScenarioWindow with end() and Symbol.dispose. Most accept a requests count and, where relevant, an endpoint path. Omit the count to keep the scenario active until it is ended. denyNext(), denyRun(), and stopRun() update scripted state and return void.

Use clearDenials(), clearStop(runId), expireReservations(), and expireLeases() to move the fake into a recovery or expiry state.

const plane = new FakeControlPlane();
const outage = plane.outage({
  requests: 1,
  path: "/api/v1/budgets/check",
});

try {
  // This call observes the configured failOpen behavior.
  await client.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello" }],
  });
} finally {
  outage.end();
}

Because the example can proceed to provider dispatch, client must wrap a caller-owned mock or a provider client intended for that test.

Test an operator stop

Run-scoped scenarios need an active Node run context:

import { RunStoppedError } from "@solwyn/sdk";
import { currentRun, run } from "@solwyn/sdk/node";
import {
  denialOnlyOpenAIClient,
  FakeControlPlane,
} from "@solwyn/sdk/testing";
import { expect, test } from "vitest";

test("an operator stop blocks the exact run", async () => {
  const plane = new FakeControlPlane();
  const client = plane.wrap(denialOnlyOpenAIClient(), {
    leaseEnabled: false,
    model: "gpt-4o",
  });

  try {
    await run("operator-stop", async () => {
      const runId = currentRun()?.agentRunId;
      if (runId === undefined) throw new Error("missing run context");

      plane.stopRun(runId);
      await expect(client.chat.completions.create()).rejects.toBeInstanceOf(
        RunStoppedError,
      );
    });
  } finally {
    await client.close();
  }
});

The testing entry itself is edge-safe. Run-context APIs—run(), createRun(), currentRun(), currentRunContext(), and RunHandle—require the Node entry.

Reserved magic models

The fake reserves seven model names for concise end-to-end scenarios:

Unknown names under solwyn-test/ fail fast. The three run-scoped models fail fast when no active run() or RunHandle.activate() context exists.

Contract probes

The testing entry exports reusable probes for a caller-selected fetch, base URL, and API key:

import {
  assertCheckContract,
  assertConfirmContract,
  assertLeaseContract,
  assertReceiptIngestContract,
  assertRunControlContract,
} from "@solwyn/sdk/testing";

• assertCheckContract() checks monthly, stopped-run, tag, agent-run, and allow verdicts.
• assertConfirmContract() checks reservation settlement and replay behavior.
• assertLeaseContract() checks grant, renewal, lease settlement, refusal, and surrender shapes.
• assertRunControlContract() checks opted-in, legacy, stopped, and unstopped responses. It also requires a stoppedRunId for a run you have already stopped on the target.
• assertReceiptIngestContract() checks a server denial receipt and an aggregate replay.

The probes assert a prepared contract; they do not create server state. In a fake test, script the required state on FakeControlPlane first. In a live contract test, provision isolated server state yourself and deliberately pass a live fetch and credentials. Probes preserve any gateway path prefix in apiUrl. Calling a live endpoint is never an implicit part of the offline test path.

Test-runner integration

The package does not auto-register a Vitest plugin and has no runtime dependency on Vitest. Keep fixtures in your own suite and opt in explicitly. A reliable teardown should close the client and assert that plane.unmatchedRequests is empty, even when the test fails.

Related

• TypeScript SDK Runs
• TypeScript SDK Budgets
• TypeScript SDK Errors
• TypeScript SDK Privacy