trellis-test/index.ts - Trellis TypeScript API documentation

Classes

c

TrellisTestEventCapture<

TContract extends TrellisTestEventSourceContract,

TSelectedEvent extends EventName<TContract>

>(args: { client: ConnectedClient; waitFor: EventCaptureRuntime["waitFor"]; onStop: (

client: ConnectedClient,

capture: TrellisTestEventCapture<TContract, TSelectedEvent>

Disposable helper that captures live decoded contract events in integration tests.

all(): ReadonlyArray<TrellisTestCapturedEvent<TContract, TSelectedEvent>>
Returns captured events, optionally filtered by event name.
clear(): void
Removes all events captured so far without stopping live listeners.
listenerSignal(): AbortSignal
record(event: TrellisTestCapturedEvent<TContract, TSelectedEvent>): void
stop(): Promise<void>
Stops live listeners and closes the synthetic capture client connection once.
waitFor<E extends TSelectedEvent>(
name: E,
predicate?: TrellisTestCapturedEventPredicate<TContract, E>,
opts?: WaitForOptions
): Promise<TrellisTestCapturedEvent<TContract, E>>
Waits for the first captured event with the requested name and optional predicate.

c

TrellisTestRuntime(args: { trellisUrl: string; workdir: string; deployment: string; keepWorkdir: boolean; timeouts: RuntimeTimeouts; nats: NatsTestContainer; controlPlane: TrellisProcessHandle; admin: TrellisTestAdminAutomation; })

Runs an isolated Trellis control plane and NATS server for integration tests.

captureEvents<
TContract extends TrellisTestEventSourceContract,
TEvents extends readonly EventName<TContract>[]
>(args: TrellisTestEventCaptureOptions<TContract, TEvents>): Promise<TrellisTestEventCapture<TContract, TEvents[number]>>
Captures live decoded contract events through a synthetic app participant.
clientAuth(key: TrellisTestClientKey): TrellisTestClientAuth
Returns auth options and admin-backed auth continuation for a registered app/client participant. Spread the result into TrellisClient.connect(...).
connectClient<TContract extends TrellisTestClientContract<TrellisAPI>>(args:
ClientOpts
& { name: string; contract: TContract; sessionKeySeed?: string; }
): Promise<TrellisTestConnectedClient<TContract>>
Connects an app/client participant through the public generated client surface.
contracts: { approve(args: { deployment?: string; contract: RuntimeContract; allowPlanClassifications?: readonly TrellisTestAuthorityPlanClassification[]; }): Promise<TrellisTestContractApproval>; }
deployments: { create(args: { id?: string; mutableDev?: boolean; }): Promise<void>; reconcile(deployment: string): Promise<void>; waitReady(deployment: string): Promise<void>; }
drain(): Promise<void>
Drains the underlying NATS connection.
flush(): Promise<void>
Flushes the underlying NATS connection.
natsUrl: string
registerClient(args: { name: string; contract: TrellisTestClientContract; sessionKeySeed?: string; }): Promise<TrellisTestClientKey>
Creates app/client session-key material for public TrellisClient.connect calls.
registerService(args: { name: string; contract: RuntimeContract; deployment?: string; sessionKeySeed?: string; }): Promise<TrellisTestServiceKey>
Registers a service contract and creates a service instance key.
services: { createInstance(args: { deployment?: string; name: string; contract: RuntimeContract; sessionKeySeed?: string; }): Promise<TrellisTestServiceKey>; }
sqliteMemoryUrl(): string
Returns the SQLite in-memory URL used by service-owned tests.
start(options: TrellisTestRuntimeStartOptions): Promise<TrellisTestRuntime>
Starts an isolated Trellis test runtime.
stop(): Promise<void>
Stops clients, control plane, NATS, and the temp directory.
tempSqlitePath(name?: string): Promise<string>
Returns a service-owned SQLite path under this runtime workdir.
trellisUrl: string
waitFor<T>(
fn: () =>
T
| null
| undefined
| false
| Promise<T | null | undefined | false>,
opts?: WaitForOptions
): Promise<T>
Polls until fn returns a truthy value.
workdir: string

Functions

f

assertCapturedEventContext<TEvent extends TrellisTestAssertionCapturedEvent>(

expected?: TrellisTestCapturedEventContextExpectation

Validates standard Trellis captured-event context metadata and returns the event.

f

assertEventCaptured(

capture: TrellisTestAssertionEventCapture,

eventName: string,

predicate?: unknown,

options?: WaitForOptions

): Promise<TrellisTestAssertionCapturedEvent>

Waits for a captured event and fails with captured-event context when it is absent.

f

assertEventsCaptured(

capture: TrellisTestAssertionEventCapture,

expectations: readonly TrellisTestEventExpectation[],

options?: TrellisTestAssertEventsCapturedOptions

): Promise<TrellisTestAssertionCapturedEvent[]>

Waits for several captured-event expectations.

f

assertJobCompleted<TTerminal extends TrellisTestJobTerminal>(

TTerminal
| { readonly id?: string; wait(): TrellisTestTerminalWaitResult<TTerminal>; },

expectedResult?: TrellisTestDeepPartial<TrellisTestJobTerminalResult<TTerminal>>

): Promise<TTerminal>

Asserts that a job reference or terminal job completed successfully.

f

assertNoEventCaptured<

TEvent extends TrellisTestAssertionCapturedEvent,

TEventName extends TEvent["event"]

capture: TrellisTestAssertionEventCapture<TEvent>,

eventName: TEventName,

predicate?: TrellisTestAssertionEventPredicate<TrellisTestEventByName<TEvent, TEventName>>,

options?: { readonly message?: string; }

): Promise<void>

Asserts that no matching event has been captured so far.

f

assertNoEventDuring<

TEvent extends TrellisTestAssertionCapturedEvent,

TEventName extends TEvent["event"]

capture: TrellisTestAssertionEventCapture<TEvent>,

eventName: TEventName,

predicateOrOptions:

TrellisTestAssertionEventPredicate<TrellisTestEventByName<TEvent, TEventName>>
| TrellisTestAssertNoEventDuringOptions
| undefined,

options?: TrellisTestAssertNoEventDuringOptions

): Promise<void>

Asserts that no matching event is captured during an explicit observation window.

f

assertOperationCompleted<TProgress, TOutput>(

TerminalOperation<TProgress, TOutput>
| TrellisTestWaitableOperation<TProgress, TOutput>,

expectedOutput?: TrellisTestDeepPartial<TOutput>

TerminalOperation<TProgress, TOutput>
& { state: "completed"; }

Asserts that an operation reference or terminal operation completed successfully.

f

assertRpcErr<T, E extends BaseError>(

resultLike: MaybeAsync<T, E>,

expectedErrorNameOrCtor?: string | TrellisTestErrorConstructor<E>

Asserts that a Trellis RPC-style result is Err and returns the error.

f

assertRpcEventuallyOk<T, E extends BaseError>(

runtimeOrWaitFor: TrellisTestWaitForSource,

rpcCallFn: () => MaybeAsync<T, E>,

expected?: TrellisTestDeepPartial<T>,

options?: TrellisTestAssertRpcEventuallyOkOptions

Polls a Trellis RPC-style call until it returns Ok and optional expected output matches.

f

assertRpcOk<T, E extends BaseError>(

resultLike: MaybeAsync<T, E>,

expected?: TrellisTestDeepPartial<T>

Asserts that a Trellis RPC-style result is Ok and returns the Ok value.

f

sqliteMemoryUrl(): string

Returns the SQLite in-memory URL used by service-owned tests.

f

tempSqlitePath(name?: string): Promise<string>

Returns a fresh path suitable for a service-owned SQLite database.

f

T
| null
| undefined
| false
| Promise<T | null | undefined | false>,

opts?: WaitForOptions

Polls until fn returns a truthy value, preserving the last thrown error on timeout.

Type Aliases

T

TrellisTestAssertEventsCapturedOptions = WaitForOptions & { readonly ordered?: boolean; }

Options for assertEventsCaptured.

T

TrellisTestAssertionCapturedEvent<TEventName extends string = string, TPayload = unknown> = { readonly event: TEventName; readonly payload: TPayload; readonly context: unknown; readonly receivedAt: unknown; }

Minimal captured-event shape accepted by the generic event assertion helpers.

context: unknown
Trellis listener metadata for the captured event.
event: TEventName
Contract event name captured by the test listener.
payload: TPayload
Decoded event payload.
receivedAt: unknown
Wall-clock time when the test capture observed the event.

T

TrellisTestAssertionEventCapture<

TEvent extends TrellisTestAssertionCapturedEvent = TrellisTestAssertionCapturedEvent

> = { all(): ReadonlyArray<TEvent>; }

Structural event capture accepted by Trellis test event assertion helpers.

all(): ReadonlyArray<TEvent>
Returns events captured so far in capture order.

T

TrellisTestAssertionEventPredicate<

TEvent extends TrellisTestAssertionCapturedEvent = TrellisTestAssertionCapturedEvent

> = (event: TEvent) => MaybePromise<boolean>

Predicate used by event assertion helpers to select a captured event.

T

TrellisTestAssertNoEventDuringOptions = { readonly durationMs: number; readonly intervalMs?: number; }

Options for assertNoEventDuring.

durationMs: number
Duration to observe for newly captured events.
intervalMs: number
Poll interval while observing. Defaults to 10ms.

T

TrellisTestAssertRpcEventuallyOkOptions = WaitForOptions

Options for assertRpcEventuallyOk.

T

TrellisTestAuthorityPlanClassification = "update" | "migration"

Authority plan classifications the test runtime may approve automatically.

T

TrellisTestCapturedEvent<

TContract extends TrellisTestEventSourceContract,

E extends EventName<TContract>

> = [K in E]: { readonly event: K; readonly payload: EventType<TContract, K>; readonly context: TrellisTestCapturedEventContext; readonly receivedAt: Date; }[E]

A decoded contract event observed by a TrellisTestEventCapture.

T

TrellisTestCapturedEventContext = { readonly id: string; readonly time: Date; readonly mode: "ephemeral"; }

Transport-neutral listener metadata captured with a test event.

id: string
Stable event id from the Trellis event header.
mode: "ephemeral"
Runtime listener mode that delivered the event.
time: Date
Event creation time from the Trellis event header.

T

TrellisTestCapturedEventContextExpectation = { readonly id?: string; readonly time?: Date; readonly mode?: "ephemeral"; readonly receivedAt?: Date; }

Expected captured event context fields for assertCapturedEventContext.

id: string
Expected Trellis event id.
mode: "ephemeral"
Expected listener mode. Defaults to ephemeral.
receivedAt: Date
Expected capture receipt time.
time: Date
Expected Trellis event creation time.

T

TrellisTestCapturedEventPredicate<

TContract extends TrellisTestEventSourceContract,

E extends EventName<TContract>

> = (event: TrellisTestCapturedEvent<TContract, E>) => boolean | Promise<boolean>

Predicate used by TrellisTestEventCapture.waitFor.

T

TrellisTestClientAuth = { auth: ClientAuthOptions; onAuthRequired(ctx: ClientAuthRequiredContext): Promise<ClientAuthContinuation>; }

Authentication options for connecting a test app/client participant.

T

TrellisTestClientContract<TApi extends TrellisAPI = TrellisAPI> = { CONTRACT: TrellisContractV1; CONTRACT_DIGEST?: string; API: { owned?: TApi; trellis?: TApi; }; }

Contract value accepted by app/client helpers.

T

TrellisTestClientKey = { seed: string; sessionKey: string; }

Session-key material returned for a registered app/client participant.

T

TrellisTestConnectedClient<TContract> = ConnectedTrellisClient<

TContract
& { API: { trellis: ApiForTestClientContract<TContract>; }; }

Connected app/client type returned by TrellisTestRuntime.connectClient.

T

TrellisTestContract = ContractModule<string, TrellisApiLike, TrellisApiLike, TrellisApiLike>

Contract value accepted by the Trellis test runtime.

T

TrellisTestContractApproval = { planId: string; classification: TrellisTestAuthorityPlanClassification; }

Result returned when a contract authority plan is approved by the test runtime.

T

TrellisTestDeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? readonly [K in keyof T]?: TrellisTestDeepPartial<T[K]> : T

Recursive subset expectation used by Trellis test assertion helpers.

T

TrellisTestErrorConstructor<TError extends Error = Error> =

(new (...args: never[]) => TError)
& { readonly name: string; }

Error constructor or class object accepted by assertRpcErr.

T

TrellisTestEventByName<

TEvent extends TrellisTestAssertionCapturedEvent,

TEventName extends TEvent["event"]

> = TEvent extends TrellisTestAssertionCapturedEvent ? TEventName extends TEvent["event"] ? TEvent & { readonly event: TEventName; } : never : never

Captured-event variant selected by event name when the event type is a union.

T

TrellisTestEventCaptureOptions<

TContract extends TrellisTestEventSourceContract,

TEvents extends readonly EventName<TContract>[]

ClientOpts
& { name: string; contract: TContract; events: TEvents; }

Options for starting a live decoded contract event capture.

T

TrellisTestEventExpectation<

TEvent extends TrellisTestAssertionCapturedEvent = TrellisTestAssertionCapturedEvent

> = TEvent["event"] | TrellisTestEventExpectationObject<TEvent>

Event expectation accepted by assertEventsCaptured.

T

TrellisTestEventExpectationObject<

TEvent extends TrellisTestAssertionCapturedEvent = TrellisTestAssertionCapturedEvent

> = [TEventName in TEvent["event"]]: { readonly event: TEventName; readonly predicate?: TrellisTestAssertionEventPredicate<TrellisTestEventByName<TEvent, TEventName>>; }[TEvent["event"]]

Event expectation object accepted by assertEventsCaptured.

T

TrellisTestEventSourceContract = EventSourceContract

Contract value accepted by TrellisTestRuntime.captureEvents.

T

TrellisTestJobTerminal<TResult = unknown> = { readonly id?: string; readonly state: string; readonly result?: TResult; }

Minimal terminal job snapshot accepted by assertJobCompleted.

id: string
Trellis job id, when available from the source snapshot.
result: TResult
Job result payload, present for completed jobs that produce a result.
state: string
Terminal job state.

T

TrellisTestOrThrowWaitResult<TTerminal> = { orThrow(): MaybePromise<TTerminal>; }

Generated-style wait result exposing an orThrow() terminal unwrap.

orThrow(): MaybePromise<TTerminal>
Returns the terminal snapshot or throws the underlying failure.

T

TrellisTestRuntimeStartOptions = { nats?: "container"; keepWorkdir?: boolean; deployment?: string; trellis: TrellisTestRuntimeTrellisOptions; authority?: { autoAccept?: readonly TrellisTestAuthorityPlanClassification[]; }; timeouts?: { startupMs?: number; reconciliationMs?: number; waitForMs?: number; shutdownMs?: number; }; }

Options for starting an isolated Trellis test runtime.

T

TrellisTestServiceKey = { seed: string; sessionKey: string; }

Session-key material returned for a registered service.

T

TrellisTestTerminalWaitResult<TTerminal, E extends BaseError = BaseError> =

MaybeAsync<TTerminal, E>
| TrellisTestOrThrowWaitResult<TTerminal>
| Promise<TrellisTestOrThrowWaitResult<TTerminal> | TTerminal>
| TTerminal

Wait result shape accepted by terminal job and operation assertions.

T

TrellisTestWaitableJob<TPayload = unknown, TResult = unknown> = { readonly id?: string; wait(): TrellisTestTerminalWaitResult<TrellisTestJobTerminal<TResult>>; }

Structural Trellis job reference accepted by assertJobCompleted.

id: string
Trellis job id, when available from the source reference.
wait(): TrellisTestTerminalWaitResult<TrellisTestJobTerminal<TResult>>
Waits for the job to reach a terminal state.

T

TrellisTestWaitableOperation<TProgress = unknown, TOutput = unknown> = { wait(): TrellisTestTerminalWaitResult<TerminalOperation<TProgress, TOutput>>; }

Structural Trellis operation reference accepted by assertOperationCompleted.

wait(): TrellisTestTerminalWaitResult<TerminalOperation<TProgress, TOutput>>
Waits for the operation to reach a terminal state.

T

TrellisTestWaitForFunction = <T>(

T
| null
| undefined
| false
| Promise<T | null | undefined | false>,

opts?: WaitForOptions

) => Promise<T>

Wait polling function accepted by eventual Trellis test assertion helpers.

T

TrellisTestWaitForSource =

TrellisTestWaitForFunction
| { readonly waitFor: TrellisTestWaitForFunction; }

Runtime-like object accepted by eventual Trellis test assertion helpers.

T

WaitForOptions = { timeoutMs?: number; intervalMs?: number; }

Polling options for waitFor and runtime readiness helpers.

Usage

import * as mod from "trellis-test/index.ts";