@spine-event-engine/testing 2.0.0-snapshot.21 → 2.0.0-snapshot.23

package/dist/black-box/black-box.d.ts

@@ -1,8 +1,10 @@
+import type { HistoryPage, HistoryRead } from "@spine-event-engine/ai";
 import { type Message, type MessageShape } from "@bufbuild/protobuf";
 import type { GenMessage } from "@bufbuild/protobuf/codegenv2";
 import { type ClientRequest } from "@spine-event-engine/client-node";
-import { type TenantId, type ZoneId, type Command, type Event } from "@spine-event-engine/proto";
-import { BoundedContext, type BoundedContextBuilder } from "@spine-event-engine/server";
+import { type TenantId, type ZoneId, type Command, type Event, type EventId } from "@spine-event-engine/proto";
+import { BoundedContext, Agent, Repository, type BoundedContextBuilder, type ConcreteRepositoryEntityType, type RepositoryEntityId, type RepositoryEntityType, type RepositoryStateSchema } from "@spine-event-engine/server";
+import type { AgentHistoryEntry } from "@spine-event-engine/proto/agent";
 /**
  * Fixed configuration for one runner-neutral BlackBox session.
  */
@@ -54,6 +56,7 @@ export interface BlackBoxScope extends ClientRequest {
      * @param schema The schema of the event message.
      * @param message The event message to post.
      * @returns A promise that resolves after the event is posted.
+     * @typeParam Schema The domain schema that determines the accepted message shape.
      */
     postEvent<Schema extends GenMessage<Message>>(schema: Schema, message: MessageShape<Schema>): Promise<void>;
     /**
@@ -62,6 +65,7 @@ export interface BlackBoxScope extends ClientRequest {
      * @param schema The schema of the external event message.
      * @param message The external event message.
      * @returns A promise that resolves after external event admission.
+     * @typeParam Schema The domain schema that determines the accepted message shape.
      */
     postExternalEvent<Schema extends GenMessage<Message>>(schema: Schema, message: MessageShape<Schema>): Promise<void>;
 }
@@ -70,6 +74,15 @@ export interface BlackBoxScope extends ClientRequest {
  */
 export declare class BlackBox {
     #private;
+    /**
+     * Captures the server, client, test options, and produced-signal observation.
+     *
+     * @param context The bounded context under test.
+     * @param server The started local server.
+     * @param client The client connected to that server.
+     * @param options The validated tenant, zone, and wait settings.
+     * @param observation The optional produced-signal observer.
+     */
     private constructor();
     /**
      * Starts an ephemeral local server and public client for a context or builder.
@@ -104,6 +117,24 @@ export declare class BlackBox {
      * @returns The Events produced by this context.
      */
     assertEvents(): readonly Event[];
+    /**
+     * Reads complete retained Agent history through its opaque full-history cursor.
+     *
+     * @typeParam EntityType Generated Agent class registered in this Bounded Context.
+     * @param target Exact typed Agent repository or its generated class.
+     * @param entityId Typed Agent identifier.
+     * @param request Positive page size and optional prior cursor.
+     * @returns Provider-backed entries newest first, with an older-page cursor when present.
+     */
+    readAgentHistory<EntityType extends RepositoryEntityType & ConcreteRepositoryEntityType<EntityType>>(target: (Repository<EntityType> | EntityType) & (EntityType["prototype"] extends Agent<RepositoryEntityId<EntityType>, RepositoryStateSchema<EntityType>> ? unknown : never), entityId: NoInfer<RepositoryEntityId<EntityType>>, request: HistoryRead): Promise<HistoryPage<AgentHistoryEntry>>;
+    /**
+     * Reads original persisted System Event envelopes by exact IDs, in requested order.
+     * Missing IDs are omitted; repeated IDs return independent copies.
+     *
+     * @param ids Exact System Event IDs from retained Agent history.
+     * @returns Stored envelopes for this Bounded Context and fixed tenant.
+     */
+    readSystemEvents(ids: readonly EventId[]): Promise<readonly Event[]>;
     /**
      * Reads repeatedly until the predicate accepts or the bounded wait expires.
      *
@@ -111,14 +142,20 @@ export declare class BlackBox {
      * @param accept The predicate that accepts a produced value.
      * @param options Optional wait limits for this operation.
      * @returns The first accepted value.
+     * @typeParam Value The value type carried through reading or delivery.
      */
     eventually<Value>(read: () => Value | Promise<Value>, accept: (value: Value) => boolean, options?: Pick<BlackBoxOptions, "timeoutMs" | "intervalMs">): Promise<Value>;
     /**
-     * Stops admission, cancels owned subscriptions, and closes the client and server once.
+     * Stops admission, cancels registered subscriptions, and closes the client and server once.
      *
      * @returns A shared promise that resolves after cleanup completes.
      */
     close(): Promise<void>;
+    /**
+     * Stops admission and waits, cancels subscriptions, and closes the client and server.
+     *
+     * @returns Completion after all cleanup settles, or an aggregate of failures.
+     */
     private closeOnce;
 }
 /**
@@ -129,13 +166,13 @@ export interface BlackBoxTestAccess {
      * Creates a BlackBox with supplied closeable resources.
      *
      * @param resources The test client, server, and optional subscriptions.
-     * @returns A BlackBox that owns the supplied resources.
+     * @returns A BlackBox configured with the supplied resources.
      */
     create(resources: BlackBoxTestResources): BlackBox;
     /**
      * Returns a generic subscription-like handle for lifecycle regression tests.
      *
-     * @param blackBox The BlackBox that owns the handle.
+     * @param blackBox The BlackBox tracking the handle.
      * @param handle The cancelable async handle to track.
      * @returns The tracked handle.
      */

package/dist/black-box/black-box.d.ts.map

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