server-core/test-utils

Shared server-core test utility exports.

server-core/test-utils

packages/server/src/test-utils

Purpose

Shared server-core test utility exports.

Public surface

AwaitNotificationError

TypeAlias

export type AwaitNotificationError =
  | AwaitNotificationTimeoutError
  | AwaitNotificationClosedError;

Represents await notification error conditions.

awaitOneNotification

Function

export function awaitOneNotification<D extends AnyNotificationDefinition>(
  client: Pick<TestAgentClient, "subscribe">,
  definition: D,
  timeoutMs: number = DEFAULT_AWAIT_NOTIFICATION_TIMEOUT_MS,
): Effect.Effect<NotificationDelivery<D>, AwaitNotificationError>

Stream-based one-shot waiter. Consumes client.subscribe(def) via Stream.runHead, failing with AwaitNotificationTimeoutError on timeout and AwaitNotificationClosedError when the transport closed before a matching frame arrived. Distinguishing close from timeout keeps a dead connection from masquerading as a missing notification.

Returns: The await one notification result.

closeAllClients

Function

export function closeAllClients(): Effect.Effect<void>

Executes the close all clients operation.

Returns: The close all clients result.

ConnectedAgent

Interface

export interface ConnectedAgent {
  client: TestAgentClient;
  agentId: AgentId;
  apiKey: AgentKey;
  name: string;
}

Describes connected agent.

connectTestClient

Function

export function connectTestClient(opts: {
  agentId: AgentId;
  apiKey: AgentKey;
  wsUrl?: string;
}): Effect.Effect<TestAgentClient, Error>

Executes the connect test client operation.

Returns: The connect test client result.

CoreSchemaSqlLoadError

TypeAlias

export type CoreSchemaSqlLoadError =
  | CoreSchemaSqlAccessError
  | CoreSchemaSqlReadError;

Represents core schema sql load error conditions.

CoreTestDatabasePort

Interface

export interface CoreTestDatabasePort {
  execute(sql: string): PromiseLike<unknown>;
  reset(): PromiseLike<undefined>;
}

Database operations available to consumers of the published test harness.

CoreTestReadyOutcome

TypeAlias

export type CoreTestReadyOutcome =
  | { readonly _tag: "Ready" }

Represents core test ready outcome values.

CoreTestRuntimeServerHandle

Interface

export interface CoreTestRuntimeServerHandle {
  awaitAgentReady(
    agentId: AgentId,
    timeoutMs: number,
  ): Effect.Effect<CoreTestReadyOutcome>;
}

Process capabilities needed by in-process runtime tests.

CoreTestServer

TypeAlias

export type CoreTestServer = CoreTestServerPort;

Canonical published handle for a running core test server.

CoreTestServerHandle

Interface

export interface CoreTestServerHandle {
  baseUrl: string;
  wsUrl: string;
  db: EffectKysely<Database>;
  coreApp: CoreApp;

  /**
   * Pre-wired server handle that reports readiness from the live
   * `ConnectionManager`. Out-of-process consumers construct their own handle
   * over the WebSocket connection they already hold.
   */
  runtimeServer: CoreTestRuntimeServerHandle;

  /**
   * The auto-wired `InMemorySpanExporter`, or `null` when the caller
   * supplied a custom `spanProcessor`. Tests that want to inspect OTel
   * spans call `getFinishedSpans()` on this exporter and map them via
   * their own package-specific projection.
   */
  readonly spanExporter: InMemorySpanExporter | null;

  /** Published projection that keeps persistence and tracing vendors private. */
  readonly testPort: CoreTestServerPort;
}

Describes core test server handle.

CoreTestServerPort

Interface

export interface CoreTestServerPort {
  readonly baseUrl: string;
  readonly wsUrl: string;
  readonly db: CoreTestDatabasePort;
  readonly runtimeServer: CoreTestRuntimeServerHandle;
  readonly spanExporter: CoreTestSpanExporterPort | null;
}

Published server handle composed only from server-owned test ports.

CoreTestSpan

Interface

export interface CoreTestSpan {
  readonly name: string;
  readonly attributes: Readonly<Record<string, unknown>>;
}

Stable projection of a finished server trace span.

CoreTestSpanExporterPort

Interface

export interface CoreTestSpanExporterPort {
  getFinishedSpans(): readonly CoreTestSpan[];
  reset(): void;
}

Trace-capture operations available to test-harness consumers.

createTestAgent

Function

export function createTestAgent(
  name: string,
  opts?: CreateTestAgentOptions,
): Effect.Effect<TestAgent>

Creates test agent.

Returns: The created test agent.

DEFAULT_TEST_ADMIN_USER_ID

Variable

export const DEFAULT_TEST_ADMIN_USER_ID: UserIdValue = Schema.decodeUnknownSync(
  userId,
)("00000000-0000-4000-8000-00000000ad00")

Validates and decodes default test admin user id values.

getBaseUrl

Function

export function getBaseUrl(): string

Returns base url.

Returns: The get base url result.

getCoreDb

Function

export function getCoreDb(): EffectKysely<Database>

Returns core db.

Returns: The get core db result.

getWsUrl

Function

export function getWsUrl(): string

Returns ws url.

Returns: The get ws url result.

loadCoreSchemaSql

Function

export function loadCoreSchemaSql(): Effect.Effect<
  string,
  CoreSchemaSqlLoadError
>

Loads core schema sql.

Returns: The load core schema sql result.

makePgliteHarness

Function

export function makePgliteHarness(): Effect.Effect<
  PgliteHarness,
  PgliteHarnessError
>

Spin up a fresh PGlite instance with the core schema loaded.

Returns: The created pglite harness.

PGLITE_HOOK_TIMEOUT_MS

Variable

export const PGLITE_HOOK_TIMEOUT_MS = 30_000

Suggested timeout for pglite-backed beforeEach/afterEach hooks.

PgliteHarness

Interface

export interface PgliteHarness {
  /** Effect-Kysely-wrapped client. Yieldable as Effect via the toolkit. */
  readonly db: EffectKysely<Database>;

  /**
   * Run raw SQL. The harness uses this to load the schema; tests can use it
   * to seed extra rows after `make()` returns.
   */
  readonly exec: (sql: string) => Effect.Effect<unknown, PgliteExecError>;

  /** Tear down the in-memory instance. Call from `afterEach`. */
  readonly close: Effect.Effect<void, PgliteCloseError>;
}

Describes pglite harness.

PgliteHarnessError

TypeAlias

export type PgliteHarnessError =
  | CoreSchemaSqlLoadError
  | PgliteCreateError
  | PgliteExecError
  | PgliteCloseError;

Represents pglite harness error conditions.

postJson

Function

export function postJson(
  baseUrl: string,
  path: string,
  body: Record<string, unknown>,
): Effect.Effect<PostJsonResult, PostJsonError>

POST body as JSON to ${baseUrl}${path} and resolve with {status, json}. HTTP integration tests import this helper to avoid repeated request/JSON boilerplate.

Returns: The post json result.

registerAgent

Function

export function registerAgent(
  baseUrl: string,
  name: string,
  opts?: { description?: string; inviteCode?: string },
): Effect.Effect<TestAgent, Error>

Registers agent.

Returns: The register agent result.

registerAndConnect

Function

export function registerAndConnect(
  name: string,
): Effect.Effect<ConnectedAgent, Error>

Register and connect an agent. Tracked for automatic cleanup.

Returns: The register and connect result.

resetCoreTestDb

Function

export function resetCoreTestDb()

Executes the reset core test db operation.

Returns: The reset core test db result.

setupAgentGroup

Function

export function setupAgentGroup(
  count: number,
  opts?: { groupName?: string },
): Effect.Effect<
  {
    agents: ConnectedAgent[];
    conversationId?: ConversationId;
  },
  Error
>

Create N agents, all connected. Optionally create a group conversation.

Returns: The setup agent group result.

setupAgentPair

Function

export function setupAgentPair(): Effect.Effect<
  { alice: ConnectedAgent; bob: ConnectedAgent },
  Error
>

Create two agents, both connected.

Returns: The setup agent pair result.

startCoreTestServer

Function

export function startCoreTestServer(opts: StartCoreTestServerOptions = {})

Start a test server and expose its package-owned integration ports.

Returns: A promise for the running server’s integration ports.

startCoreTestServerEffect

Variable

export const startCoreTestServerEffect = Effect.fn("startCoreTestServer")(
  function* (opts: StartCoreTestServerOptions = {}) {
    yield* ensureNoCoreTestServerRunning();
    const db = yield* initializeTestDatabase();
    coreApp = createCoreTestApp(db, opts);
    yield* Effect.sleep(`${PGLITE_BOOT_DELAY_MS} millis`);
    return buildCoreTestServer(coreApp, db);
  },
)

Executes the start core test server effect operation.

startCoreTestServerFull

Function

export function startCoreTestServerFull(opts: StartCoreTestServerOptions = {})

Executes the start core test server full operation.

Returns: The start core test server full result.

StartCoreTestServerOptions

Interface

export interface StartCoreTestServerOptions {
  readonly pgHost?: string;
  readonly pgPort?: number;
  readonly registrationSecret?: string;
  readonly adminUserId?: UserId;
}

Configures start core test server.

stopCoreTestServer

Function

export function stopCoreTestServer()

Executes the stop core test server operation.

Returns: The stop core test server result.

trackClient

Function

export function trackClient(client: TestAgentClient): void

Executes the track client operation.

Files

• core-schema-sql.ts
• helpers.ts
• index.ts
• pglite-harness.ts
• ports.ts
• server.ts