ihsm 0.0.21 → 0.0.22

package/lib/cjs/internal/hsm.d.ts

@@ -1,4 +1,4 @@
-import { DispatchErrorCallback, PostedEvent, EventPayload, ServiceResponse, ServiceName, ServiceRequest, StateClass, TraceLevel, TraceWriter } from '../';
+import { Disposable, DispatchErrorCallback, EventObserver, PostedEvent, EventPayload, ServiceResponse, ServiceName, ServiceRequest, StateClass, TraceLevel, TraceWriter } from '../';
 import { HsmWithTracing, Instance, Task, Transition } from './defs.private';
 /** @internal */
 export declare class HsmObject<Context, Protocol extends {} | undefined> implements HsmWithTracing<Context, Protocol> {
@@ -14,6 +14,7 @@ export declare class HsmObject<Context, Protocol extends {} | undefined> impleme
     _transitionState?: StateClass<Context, Protocol>;
     _currentEventName?: string;
     _currentEventPayload?: any[];
+    private _observers?;
     dispatchErrorCallback: DispatchErrorCallback<Context, Protocol>;
     private _traceLevel;
     private _traceDomainStack;
@@ -22,6 +23,8 @@ export declare class HsmObject<Context, Protocol extends {} | undefined> impleme
     constructor(TopState: StateClass<Context, Protocol>, instance: Instance<Context, Protocol>, traceWriter: TraceWriter, traceLevel: TraceLevel, dispatchErrorCallback: DispatchErrorCallback<Context, Protocol>, initialize: boolean);
     get ctx(): Context;
     set ctx(ctx: Context);
+    /** Outbound boundary supplied to (or defaulted by) the factory (see {@link makeHsm}); never `undefined` at runtime. */
+    get port(): unknown;
     get eventName(): string;
     get eventPayload(): any[];
     get currentStateName(): string;
@@ -29,6 +32,9 @@ export declare class HsmObject<Context, Protocol extends {} | undefined> impleme
     set currentState(newState: StateClass<Context, Protocol>);
     post<EventName extends keyof Protocol>(eventName: PostedEvent<Protocol, EventName>, ...eventPayload: EventPayload<Protocol, EventName>): void;
     postNow<EventName extends keyof Protocol>(eventName: PostedEvent<Protocol, EventName>, ...eventPayload: EventPayload<Protocol, EventName>): void;
+    /** Register a test-only observer; returns a Disposable that removes it. See {@link TestActor.subscribe}. */
+    subscribe(observer: EventObserver): Disposable;
+    private _notifyObservers;
     deferredPost<EventName extends keyof Protocol>(millis: number, eventName: PostedEvent<Protocol, EventName>, ...eventPayload: EventPayload<Protocol, EventName>): void;
     transition(nextState: StateClass<Context, Protocol>): void;
     unhandled(): never;

package/lib/cjs/internal/hsm.js

@@ -41,6 +41,7 @@ class HsmObject {
     _transitionState;
     _currentEventName;
     _currentEventPayload;
+    _observers;
     dispatchErrorCallback;
     _traceLevel;
     _traceDomainStack;
@@ -75,15 +76,46 @@ class HsmObject {
     set ctx(ctx) {
         this._instance.ctx = ctx;
     }
+    /** Outbound boundary supplied to (or defaulted by) the factory (see {@link makeHsm}); never `undefined` at runtime. */
+    get port() {
+        return this._instance.portRef;
+    }
     get eventName() { return this._currentEventName; }
     get eventPayload() { return this._currentEventPayload; }
     get currentStateName() { return (0, utils_1.getStateName)(Object.getPrototypeOf(this._instance).constructor); }
     get currentState() { return Object.getPrototypeOf(this._instance).constructor; }
     set currentState(newState) { Object.setPrototypeOf(this._instance, newState.prototype); }
-    post(eventName, ...eventPayload) { this.pushTask(this._createEventDispatchTask(this, eventName, ...eventPayload)); }
-    postNow(eventName, ...eventPayload) { this.pushHiPriorityTask(this._createEventDispatchTask(this, eventName, ...eventPayload)); }
+    post(eventName, ...eventPayload) { this._notifyObservers(eventName, eventPayload); this.pushTask(this._createEventDispatchTask(this, eventName, ...eventPayload)); }
+    postNow(eventName, ...eventPayload) { this._notifyObservers(eventName, eventPayload); this.pushHiPriorityTask(this._createEventDispatchTask(this, eventName, ...eventPayload)); }
+    /** Register a test-only observer; returns a Disposable that removes it. See {@link TestActor.subscribe}. */
+    subscribe(observer) {
+        if (this._observers === undefined)
+            this._observers = new Set();
+        this._observers.add(observer);
+        return {
+            dispose: () => {
+                this._observers?.delete(observer);
+            },
+        };
+    }
+    _notifyObservers(eventName, eventPayload) {
+        if (this._observers === undefined || this._observers.size === 0)
+            return;
+        const message = { event: String(eventName), payload: [...eventPayload] };
+        for (const observer of this._observers)
+            observer(message);
+    }
     deferredPost(millis, eventName, ...eventPayload) {
-        setTimeout(() => this.pushTask(this._createEventDispatchTask(this, eventName, ...eventPayload)), millis);
+        const enqueue = () => { this.pushTask(this._createEventDispatchTask(this, eventName, ...eventPayload)); };
+        // Use the port's timer service when available (Port / TestPort always provide setTimeout);
+        // fall back to global setTimeout for bare BasePort subclasses that omit it.
+        const port = this._instance.portRef;
+        if (port !== undefined && typeof port.setTimeout === 'function') {
+            port.setTimeout(enqueue, millis);
+        }
+        else {
+            setTimeout(enqueue, Math.max(0, millis));
+        }
     }
     transition(nextState) { this._transitionState = nextState; }
     unhandled() { throw new __1.UnhandledEventError(this); }
@@ -172,6 +204,7 @@ class HsmObject {
         return `${this._traceDomainStack.length === 0 ? '' : this._traceDomainStack.join('|') + '|'}`;
     }
     call(eventName, ...eventPayload) {
+        this._notifyObservers(eventName, eventPayload);
         return new Promise((resolve, reject) => {
             const taskFactory = this._createEventDispatchTask;
             this.pushTask(taskFactory(this, eventName, ...[resolve, reject, ...eventPayload]));

package/lib/cjs/internal/hsm.js.map

@@ -1 +1 @@
-{"version":3,"file":"hsm.js","sourceRoot":"","sources":["../../../src/internal/hsm.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hsm.js","sourceRoot":"","sources":["../../../src/internal/hsm.ts"],"names":[],"mappings":"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"}

package/lib/cjs/internal/lookup.d.ts

@@ -0,0 +1,15 @@
+import { HsmWithTracing } from './defs.private';
+/**
+ * Canonical event-handler lookup shared by every dispatch mode (production, debug, verbose).
+ *
+ * Walks the **state-class constructor chain** starting at `hsm.currentState` and going up to and
+ * **including** {@link TopState}, returning the first state that defines `eventName` as an **own**
+ * prototype property. Stopping at `TopState` keeps resolution inside the user's state hierarchy: it
+ * never falls through to `State.prototype` / `Object.prototype`, so a posted event can never
+ * accidentally resolve to a runtime method (`post`, `transition`, `toString`, …). Returns
+ * `undefined` when no state owns the handler — the caller then routes the event to `onUnhandled`.
+ *
+ * The verbose-trace dispatcher narrates this exact algorithm step by step; sharing it here
+ * guarantees production / debug / verbose dispatch all resolve handlers identically (proposal T6).
+ */
+export declare function lookupEventHandler<Context, Protocol extends {} | undefined>(hsm: HsmWithTracing<Context, Protocol>, eventName: PropertyKey): ((...args: any[]) => unknown) | undefined;

package/lib/cjs/internal/lookup.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lookupEventHandler = lookupEventHandler;
+/** @internal */
+const __1 = require("../");
+/**
+ * Canonical event-handler lookup shared by every dispatch mode (production, debug, verbose).
+ *
+ * Walks the **state-class constructor chain** starting at `hsm.currentState` and going up to and
+ * **including** {@link TopState}, returning the first state that defines `eventName` as an **own**
+ * prototype property. Stopping at `TopState` keeps resolution inside the user's state hierarchy: it
+ * never falls through to `State.prototype` / `Object.prototype`, so a posted event can never
+ * accidentally resolve to a runtime method (`post`, `transition`, `toString`, …). Returns
+ * `undefined` when no state owns the handler — the caller then routes the event to `onUnhandled`.
+ *
+ * The verbose-trace dispatcher narrates this exact algorithm step by step; sharing it here
+ * guarantees production / debug / verbose dispatch all resolve handlers identically (proposal T6).
+ */
+function lookupEventHandler(hsm, eventName) {
+    let state = hsm.currentState;
+    while (true) {
+        const prototype = state.prototype;
+        if (Object.prototype.hasOwnProperty.call(prototype, eventName)) {
+            return prototype[eventName];
+        }
+        if (state === __1.TopState) {
+            return undefined;
+        }
+        state = Object.getPrototypeOf(state);
+    }
+}
+//# sourceMappingURL=lookup.js.map

package/lib/cjs/internal/lookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup.js","sourceRoot":"","sources":["../../../src/internal/lookup.ts"],"names":[],"mappings":";;AAkBA,gDAYC;AA9BD,gBAAgB;AAChB,2BAA2C;AAI3C;;;;;;;;;;;;GAYG;AACH,SAAgB,kBAAkB,CAA2C,GAAsC,EAAE,SAAsB;IAC1I,IAAI,KAAK,GAAkC,GAAG,CAAC,YAAY,CAAC;IAC5D,OAAO,IAAI,EAAE,CAAC;QACb,MAAM,SAAS,GAAG,KAAK,CAAC,SAAoD,CAAC;QAC7E,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC;YAChE,OAAO,SAAS,CAAC,SAAS,CAAgC,CAAC;QAC5D,CAAC;QACD,IAAK,KAAiB,KAAK,YAAQ,EAAE,CAAC;YACrC,OAAO,SAAS,CAAC;QAClB,CAAC;QACD,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAkC,CAAC;IACvE,CAAC;AACF,CAAC"}

package/lib/cjs/testing.d.ts

@@ -0,0 +1,279 @@
+/**
+ * `ihsm/testing` — deterministic-simulation testing utilities for ihsm.
+ *
+ * This entry point is **separate from the core runtime** (`ihsm`): the mock-port machinery,
+ * the manual virtual clock, and the full-access test actor live here so they are never bundled
+ * into production code that only imports `ihsm`. Import test helpers from `ihsm/testing`:
+ *
+ * ```ts
+ * import { makeHsm, TopState } from 'ihsm';            // production code
+ * import { makeTestActor, mock, TestPort } from 'ihsm/testing'; // tests only
+ * ```
+ *
+ * For convenience this module also re-exports the entire core API, so a test file may import
+ * everything it needs from `ihsm/testing` alone.
+ *
+ * @packageDocumentation
+ */
+import { Any, ActorOptions, BasePort, Disjoint, Dispatch, Disposable, EventObserver, Hsm, MachinePort, PortHandle, RandomService, TimerHandle, TopStateArg, TracedMessage } from './index';
+export * from './index';
+/**
+ * Full-access view returned by {@link makeTestActor} for **deterministic testing**.
+ *
+ * Exposes the merged {@link Dispatch} protocol — so a test can drive internal events
+ * (`onSpawn`, `onExit`, …) directly without a live port — **plus** typed access to the
+ * machine's `port` for asserting outbound calls or pushing observations.
+ *
+ * @typeParam Context - Domain context
+ * @typeParam Protocol - Public protocol
+ * @typeParam InternalProtocol - Internal (port-driven) protocol
+ * @typeParam P - Port type
+ *
+ * @category State machine
+ */
+export type TestActor<Context = Any, Protocol extends {} | undefined = undefined, InternalProtocol extends {} = {}, P = undefined> = Hsm<Context, Dispatch<Protocol, InternalProtocol>> & {
+    readonly port: P;
+    /**
+     * Observe **every** event as it is posted through this machine — a capability unique to the
+     * test surface (it is intentionally absent from {@link Actor} / {@link Hsm}).
+     *
+     * The observer fires synchronously at post time with the event name and payload, capturing
+     * client posts, handler self-posts, and port-driven internal events alike. Wire it to
+     * {@link TestPort.record} when you want a golden trace on the port under test.
+     *
+     * @param observer - Callback receiving each {@link TracedMessage}
+     * @returns A {@link Disposable} that stops the observation
+     */
+    subscribe(observer: EventObserver): Disposable;
+};
+export declare class TestPort<T = Any> extends BasePort<T> implements RandomService {
+    private readonly _messages;
+    private readonly _preloads;
+    private _now;
+    private _timerSeq;
+    private readonly _timers;
+    private readonly _cancelled;
+    private readonly _randomQueue;
+    private readonly _cryptoRandomQueue;
+    private readonly _uuidQueue;
+    private readonly _byteQueue;
+    /**
+     * Append an entry to the recorded message log (for assertions / golden traces).
+     *
+     * Callable both from inside the mock (e.g. a port method logging its outbound call) and from a
+     * test (e.g. a `Disposable.dispose` closure recording its own teardown into the trace).
+     *
+     * @param event - Event name or free-form label (e.g. `'connect'`, `'attempt 1: ok'`)
+     * @param payload - Optional values associated with the entry
+     */
+    record(event: string, ...payload: unknown[]): void;
+    private _slot;
+    /** @internal Set the persistent implementation for a stubbed method (used by `method.default`). */
+    _stubDefault(name: string, impl: (...args: unknown[]) => unknown): void;
+    /** @internal Queue a one-shot implementation for a stubbed method (used by `method.once`). */
+    _stubOnce(name: string, impl: (...args: unknown[]) => unknown): void;
+    /** @internal Clear a stubbed method's queued/persistent implementations and recorded calls (`method.reset`). */
+    _stubReset(name: string): void;
+    /** @internal The live, typed list of argument tuples a stubbed method was called with (`method.calls`). */
+    _stubCalls(name: string): unknown[][];
+    /**
+     * @internal Consume the next implementation for a stubbed method. Installed as the body of every
+     * `@`{@link mock}-stubbed method by {@link makeTestPort}; not called directly.
+     *
+     * The call is recorded first (globally in {@link trace} and in the method's {@link Stubbed.calls}),
+     * then one-shot stubs (queued via `method.once`) are consumed in order; otherwise the persistent
+     * `method.default` implementation runs. With neither set, a {@link PreloadError} naming the method
+     * is thrown.
+     *
+     * @param name - Port method name
+     * @param args - Arguments the machine passed to the method
+     * @throws {@link PreloadError} if nothing was stubbed for `name`
+     */
+    _consumePreload(name: string, args: unknown[]): unknown;
+    /** Every recorded message, in order. */
+    get messages(): readonly TracedMessage[];
+    /** Just the recorded event names, in order. */
+    get events(): readonly string[];
+    /** Rendered `event` / `event:arg,arg` strings — convenient for `deep.equal` / `include`. */
+    get trace(): readonly string[];
+    /** The most recently recorded message, or `undefined`. */
+    get last(): TracedMessage | undefined;
+    /** Number of recorded messages. */
+    get count(): number;
+    /** Clear the recorded message log. */
+    clear(): void;
+    private _sortTimers;
+    /** @inheritdoc Port.setTimeout — backed by the virtual clock; fire with {@link TestPort.advance | advance}. */
+    setTimeout(callback: () => void, millis?: number): TimerHandle;
+    /** @inheritdoc Port.clearTimeout */
+    clearTimeout(id: TimerHandle | undefined): void;
+    /** @inheritdoc Port.setInterval — backed by the virtual clock; fire with {@link TestPort.advance | advance}. */
+    setInterval(callback: () => void, millis?: number): TimerHandle;
+    /** @inheritdoc Port.clearInterval */
+    clearInterval(id: TimerHandle | undefined): void;
+    /**
+     * Advance the virtual clock by `millis`, firing every timer whose deadline is reached, in
+     * deadline order. Timers scheduled by a fired callback within the same window are **not** run
+     * until a later `advance` — mirroring how a deferred re-schedule lands on the next run-to-completion turn.
+     *
+     * @param millis - Virtual milliseconds to advance (negative values are clamped to `0`)
+     */
+    advance(millis: number): void;
+    /** Current virtual time, in milliseconds since construction. */
+    get now(): number;
+    /** Number of timers still pending (not yet fired or disposed). */
+    get pending(): number;
+    /** Queue values returned by successive {@link TestPort.random | random} calls (FIFO). */
+    feedRandom(...values: number[]): void;
+    /** Queue values returned by successive {@link TestPort.cryptoRandom | cryptoRandom} calls (FIFO). */
+    feedCryptoRandom(...values: number[]): void;
+    /** Queue values returned by successive {@link TestPort.randomUUID | randomUUID} calls (FIFO). */
+    feedUUID(...values: string[]): void;
+    /** Queue bytes used to fill arrays in successive {@link TestPort.getRandomValues | getRandomValues} calls (FIFO). */
+    feedRandomBytes(...bytes: number[]): void;
+    /** Clear all scripted random queues ({@link TestPort.feedRandom | feedRandom} / {@link TestPort.feedCryptoRandom | feedCryptoRandom} / …). */
+    resetRandom(): void;
+    /** @inheritdoc RandomService.random — queued values only; returns `0` when empty (never calls `Math.random`). */
+    random(): number;
+    /** @inheritdoc RandomService.cryptoRandom — queued values only; returns `0` when empty (never calls `crypto.random`). */
+    cryptoRandom(): number;
+    /** @inheritdoc RandomService.randomUUID — queued values only; never calls `crypto.randomUUID`. */
+    randomUUID(): string;
+    /** @inheritdoc RandomService.getRandomValues — queued bytes only; never calls `crypto.getRandomValues`. */
+    getRandomValues<T extends ArrayBufferView>(array: T): T;
+}
+/**
+ * Thrown when an abstract `@`{@link mock} port method is called but the test scripted no
+ * implementation for it. The message names the method so the fix is obvious.
+ *
+ * @category Testing
+ */
+export declare class PreloadError extends Error {
+    constructor(method: string);
+}
+/**
+ * A scriptable abstract port method on a {@link makeTestPort} mock — the per-method analogue of
+ * `jest.fn()` / Sinon stubs, fully typed from the machine's {@link TopState}.
+ *
+ * It stays **callable with the port method's exact signature** (so the machine invokes it normally),
+ * and carries the scripting + introspection surface a test drives:
+ *
+ * - `default(impl)` — set the **persistent** implementation (every call runs it until replaced).
+ * - `once(impl)` — queue a **one-shot** implementation, consumed by the next call; queue several to
+ *   script a sequence. One-shots are consumed before the persistent `default`.
+ * - `reset()` — clear queued/persistent implementations **and** the recorded {@link calls}.
+ * - `calls` — the live, typed list of argument tuples this method was called with (`Parameters<F>[]`).
+ *
+ * Both `default` and `once` take a closure with the **same parameters and return type** as the port
+ * method, so scripts stay type-safe. Pushing internal events *inward* remains the separate
+ * {@link BasePort.send | send} channel.
+ *
+ * @typeParam A - The method's argument tuple (`Parameters<F>`)
+ * @typeParam R - The method's return type (`ReturnType<F>`)
+ *
+ * @category Testing
+ */
+export interface Stubbed<A extends unknown[], R> {
+    (...args: A): R;
+    /** Set the persistent implementation run for every call (until replaced). Returns `this` for chaining. */
+    default(impl: (...args: A) => R): this;
+    /** Queue a one-shot implementation, consumed by the next call (FIFO). Returns `this` for chaining. */
+    once(impl: (...args: A) => R): this;
+    /** Clear all queued/persistent implementations and the recorded {@link calls}. Returns `this` for chaining. */
+    reset(): this;
+    /** Argument tuples this method was called with, in order — typed exactly as the port method's parameters. */
+    readonly calls: readonly A[];
+}
+/**
+ * The fully-wired mock type returned by {@link makeTestPort}: the mock class `P` itself, with each
+ * **port method** (inferred from the machine's {@link TopState} via {@link MachinePort}) upgraded to
+ * a scriptable, introspectable {@link Stubbed} method.
+ *
+ * @typeParam P - The mock port class instance type
+ * @typeParam T - The machine's root {@link TopState} subclass
+ *
+ * @category Testing
+ */
+export type Mock<P, T> = P & {
+    [K in keyof MachinePort<T>]: MachinePort<T>[K] extends (...args: infer A) => infer R ? Stubbed<A, R> : MachinePort<T>[K];
+};
+/**
+ * Class decorator that turns an **abstract** {@link TestPort} subclass into a preloadable mock.
+ *
+ * Declare each port method as an `abstract` member whose **signature matches the real port**, and
+ * decorate the class with `@`{@link mock}. Instances (built with {@link makeTestPort}) then expose
+ * every abstract method as a scriptable {@link Stubbed} method: it records each call and returns
+ * whatever the test scripted with `method.default(...)` / `method.once(...)`. You never write a
+ * method body — the behavior lives in the test, so one mock serves many scenarios.
+ *
+ * Concrete members (public fields holding device state, helper methods) are left untouched; only the
+ * abstract port methods are auto-stubbed.
+ *
+ * @example
+ * ```ts
+ * @ihsmTest.mock
+ * abstract class WatcherMock extends ihsmTest.TestPort<WatcherTop> {
+ *   abstract watch(path: string): ihsm.ResultWithSubscription<number>; // signature matches the port
+ * }
+ *
+ * const port = ihsmTest.makeTestPort(WatcherMock);
+ * port.watch.default(path => ({ value: 1, subscription: { dispose: () => port.record('dispose') } }));
+ * ```
+ *
+ * @category Testing
+ */
+export declare function mock<C extends abstract new (...args: Any[]) => TestPort<Any>>(Ctor: C): C;
+/**
+ * Instantiate an `@`{@link mock}-decorated mock class — the canonical way to build a test port.
+ *
+ * Pass the mock **class**; you get back a typed instance whose abstract port methods (inferred from
+ * the machine's {@link TopState}) are scriptable {@link Stubbed} methods, ready for
+ * `port.method.default(...)`. The port's `actor` is still bound lazily when you hand the instance to
+ * {@link makeActor} / {@link makeTestActor}.
+ *
+ * @typeParam P - The mock class instance type (a {@link TestPort} subclass)
+ * @param PortClass - The `@mock`-decorated mock class
+ * @returns A scriptable {@link Mock} instance
+ * @throws If `PortClass` was not decorated with `@`{@link mock}
+ *
+ * @example
+ * ```ts
+ * const port = ihsmTest.makeTestPort(WatcherMock);
+ * port.watch.default(() => ({ value: 1, subscription: { dispose: () => port.send('onClosed') } }));
+ * const sm = ihsmTest.makeTestActor(WatcherTop, new WatcherCtx(), port);
+ * ```
+ *
+ * @category Testing
+ */
+export declare function makeTestPort<P extends TestPort<Any>>(PortClass: abstract new () => P): Mock<P, P extends {
+    readonly __topState: infer T;
+} ? T : never>;
+/**
+ * Creates a **full-access** actor for deterministic tests: merged protocol + typed `port`.
+ *
+ * Identical construction to {@link makeActor} (same three mandatory arguments + {@link ActorOptions}),
+ * but the returned {@link TestActor} exposes the merged {@link Dispatch} protocol — so tests can
+ * drive internal events directly (no live port required) — and grants typed access to `port` for
+ * asserting outbound interactions or pushing observations.
+ *
+ * Unlike {@link makeActor}, `traceLevel` defaults to {@link TraceLevel.VERBOSE_DEBUG} so a failing
+ * test is fully readable; opt down explicitly via `options.traceLevel` only when you need a quiet run.
+ *
+ * @typeParam Context - Domain context type
+ * @typeParam Public - Public protocol
+ * @typeParam Internal - Internal protocol
+ * @typeParam P - Port type
+ * @param topState - Root state class; `Context` / `Public` / `Internal` are inferred from it (see {@link TopStateArg})
+ * @param ctx - Mutable domain object shared by all states
+ * @param port - Outbound {@link Port} instance (its `actor` is bound by the factory)
+ * @param options - Optional tuning: `initialize` / `traceLevel` / `traceWriter` / … (see {@link ActorOptions})
+ * @returns A {@link TestActor} handle with full event + port access
+ *
+ * @example
+ * ```ts
+ * const sm = makeTestActor(ConnTop, new ConnCtx(), ihsmTest.makeTestPort(ConnMock));
+ * ```
+ *
+ * @category Factory
+ */
+export declare function makeTestActor<Context, Public extends undefined | {}, Internal extends {} = {}, P extends PortHandle<Context, Internal> = TestPort>(topState: TopStateArg<Context, Public, Internal>, ctx: Context, port: P, options?: ActorOptions<Context, Public, Internal>, ..._disjointGuard: Disjoint<Public, Internal> extends true ? [] : [error: Disjoint<Public, Internal>]): TestActor<Context, Public, Internal, P>;