@mmapp/player-core 0.1.0-alpha.1

package/src/testing/types.ts

@@ -0,0 +1,231 @@
+/**
+ * Testing OS Types — test declarations for the player-core engine.
+ *
+ * All types are JSON-serializable, enabling:
+ * - LLM generation of test programs
+ * - Database storage of test suites
+ * - Cross-platform execution (browser, iOS, Node)
+ */
+
+import type { PlayerWorkflowDefinition } from '../state-machine/types';
+import type { ActionHandlerFn } from '../actions/types';
+
+// =============================================================================
+// Static Analysis
+// =============================================================================
+
+/** A node in the workflow state graph */
+export interface StateNode {
+  name: string;
+  type: 'START' | 'REGULAR' | 'END' | 'CANCELLED';
+  reachable: boolean;
+  hasOnEvent: boolean;
+  hasOnEnter: boolean;
+  hasOnExit: boolean;
+}
+
+/** An edge (transition) in the workflow state graph */
+export interface TransitionEdge {
+  name: string;
+  from: string;
+  to: string;
+  auto: boolean;
+  hasConditions: boolean;
+}
+
+/** A path through the state graph */
+export interface GraphPath {
+  states: string[];
+  transitions: string[];
+}
+
+/** Summary statistics for a workflow definition */
+export interface AnalysisSummary {
+  totalStates: number;
+  totalTransitions: number;
+  reachableStates: number;
+  terminalPaths: number;
+  cycles: number;
+  unreachableStates: number;
+  deadEndStates: number;
+}
+
+/** Full static analysis result for a workflow definition */
+export interface AnalysisResult {
+  states: StateNode[];
+  edges: TransitionEdge[];
+  terminalPaths: GraphPath[];
+  cycles: GraphPath[];
+  unreachableStates: string[];
+  deadEndStates: string[];
+  summary: AnalysisSummary;
+}
+
+// =============================================================================
+// Test Program (JSON-serializable, LLM-generable, DB-storable)
+// =============================================================================
+
+/** A complete test program with scenarios */
+export interface TestProgram {
+  name: string;
+  definitionSlug: string;
+  definitions: Record<string, PlayerWorkflowDefinition>;
+  scenarios: TestScenario[];
+}
+
+/** Instance declaration for multi-instance scenarios */
+export interface TestInstance {
+  id: string;
+  definitionSlug: string;
+  initialData?: Record<string, unknown>;
+}
+
+/** A test scenario with steps */
+export interface TestScenario {
+  name: string;
+  tags?: string[];
+  instances?: TestInstance[];
+  connectEventBuses?: boolean;
+  steps: TestStep[];
+}
+
+/** A single test step: action + assertions */
+export interface TestStep {
+  name: string;
+  instanceId?: string;
+  action:
+    | { type: 'transition'; name: string; data?: Record<string, unknown> }
+    | { type: 'set_field'; field: string; value: unknown }
+    | { type: 'publish_event'; topic: string; payload?: Record<string, unknown> }
+    | { type: 'assert_only' };
+  assertions: TestAssertion[];
+}
+
+/** A single assertion to verify after an action */
+export interface TestAssertion {
+  target: 'state' | 'status' | 'state_data' | 'available_transitions';
+  instanceId?: string;
+  path?: string;
+  operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'truthy' | 'falsy';
+  expected: unknown;
+  label?: string;
+}
+
+// =============================================================================
+// Results
+// =============================================================================
+
+/** Result of a single assertion */
+export interface AssertionResult {
+  passed: boolean;
+  assertion: TestAssertion;
+  actual: unknown;
+  error?: string;
+}
+
+/** Result of a single step */
+export interface StepResult {
+  stepName: string;
+  passed: boolean;
+  assertionResults: AssertionResult[];
+  durationMs: number;
+  error?: string;
+}
+
+/** Result of a single scenario */
+export interface ScenarioResult {
+  scenarioName: string;
+  passed: boolean;
+  stepResults: StepResult[];
+  durationMs: number;
+  error?: string;
+}
+
+/** Result of a complete test program */
+export interface TestProgramResult {
+  passed: boolean;
+  scenarioResults: ScenarioResult[];
+  durationMs: number;
+  analysis?: AnalysisResult;
+}
+
+// =============================================================================
+// Config
+// =============================================================================
+
+/** Configuration for the in-process test runner */
+export interface TestRunnerConfig {
+  actionHandlers?: Record<string, ActionHandlerFn>;
+  onStepComplete?: (scenarioIdx: number, step: StepResult) => void;
+  onScenarioComplete?: (result: ScenarioResult) => void;
+  abortSignal?: AbortSignal;
+}
+
+// =============================================================================
+// API Test Adapter — platform-agnostic interface for HTTP + WS
+// =============================================================================
+
+/** Snapshot of a server-side workflow instance */
+export interface ApiInstanceSnapshot {
+  id: string;
+  currentState: string;
+  status: string;
+  stateData: Record<string, unknown>;
+  availableTransitions: string[];
+}
+
+/** Result of triggering a transition via API */
+export interface ApiTransitionResult {
+  success: boolean;
+  fromState: string;
+  toState: string;
+  error?: string;
+}
+
+/**
+ * Adapter interface for the API test runner.
+ * Platform-agnostic — implement with fetch, axios, or any HTTP client.
+ * The server (NestJS backend) is the MM Player; the adapter is the client.
+ */
+export interface ApiTestAdapter {
+  // Instance lifecycle
+  createInstance(params: {
+    definitionSlug: string;
+    stateData?: Record<string, unknown>;
+    entityType?: string;
+    entityId?: string;
+  }): Promise<ApiInstanceSnapshot>;
+
+  startInstance(instanceId: string): Promise<ApiInstanceSnapshot>;
+
+  deleteInstance(instanceId: string): Promise<void>;
+
+  // Actions
+  triggerTransition(
+    instanceId: string,
+    transitionName: string,
+    data?: Record<string, unknown>,
+  ): Promise<ApiTransitionResult>;
+
+  updateStateData(
+    instanceId: string,
+    data: Record<string, unknown>,
+  ): Promise<ApiInstanceSnapshot>;
+
+  // Query
+  getInstance(instanceId: string): Promise<ApiInstanceSnapshot>;
+}
+
+/** Configuration for the API test runner */
+export interface ApiTestRunnerConfig {
+  adapter: ApiTestAdapter;
+  /** Delay (ms) after actions to let EventRouter settle cross-instance reactions. Default: 200 */
+  settleDelayMs?: number;
+  /** Delete instances after scenario completes. Default: true */
+  cleanupInstances?: boolean;
+  onStepComplete?: (scenarioIdx: number, step: StepResult) => void;
+  onScenarioComplete?: (result: ScenarioResult) => void;
+  /** Called when a real instance is created on the server */
+  onInstanceCreated?: (testInstanceId: string, serverId: string) => void;
+  abortSignal?: AbortSignal;
+}