@mmapp/player-core 0.1.0-alpha.1

package/src/testing/test-actions.ts

@@ -0,0 +1,645 @@
+/**
+ * Test Action Handlers — pluggable capabilities for test Blueprints.
+ *
+ * The test Blueprint uses __test_* action types. Which action handlers
+ * are registered determines HOW the test executes:
+ *
+ * - In-process: creates StateMachines in memory, sub-millisecond
+ * - API: makes HTTP calls to a running NestJS backend (MM Server Player)
+ * - Cross-platform (future): orchestrates across multiple Players
+ *
+ * Same Blueprint → different capabilities → same results.
+ *
+ * Architecture (API mode):
+ *   Player (browser/iOS) executes Test Blueprint
+ *     → __test_transition action handler
+ *       → HTTP POST /workflow/instances/:id/transitions/:name
+ *         → NestJS Backend (MM Server Player)
+ *           → EventRouter handles cross-instance reactions
+ */
+
+import { StateMachine } from '../state-machine/interpreter';
+import { EventBus } from '../events/event-bus';
+import { createEvaluator, WEB_FAILURE_POLICIES } from '../expression';
+import type { Evaluator, ExpressionContext } from '../expression/types';
+import type { PlayerWorkflowDefinition, ActionHandler, PlayerAction } from '../state-machine/types';
+import type {
+  ApiTestAdapter,
+  StepResult,
+  AssertionResult,
+  TestAssertion,
+} from './types';
+
+// =============================================================================
+// Shared result collector (used by both in-process and API handlers)
+// =============================================================================
+
+export interface TestActionState {
+  /** All step results collected during execution */
+  stepResults: StepResult[];
+  /** Whether any step has failed */
+  failed: boolean;
+  /** Current step tracking */
+  currentStep: {
+    name: string;
+    index: number;
+    startTime: number;
+    assertions: AssertionResult[];
+    error?: string;
+  } | null;
+  /** Set field on the orchestrator StateMachine (bound after creation) */
+  setOrchestratorField: (field: string, value: unknown) => void;
+}
+
+function createTestState(): TestActionState {
+  return {
+    stepResults: [],
+    failed: false,
+    currentStep: null,
+    setOrchestratorField: () => {},
+  };
+}
+
+// =============================================================================
+// In-Process Action Handlers
+// =============================================================================
+
+/**
+ * Create action handlers for in-process test execution.
+ *
+ * Test instances are StateMachines running in memory.
+ * Cross-instance reactions via shared EventBus.
+ * Sub-millisecond execution.
+ */
+export function createInProcessTestActions(
+  definitions: Record<string, PlayerWorkflowDefinition>,
+): { handlers: Map<string, ActionHandler>; state: TestActionState } {
+  const testState = createTestState();
+  const handlers = new Map<string, ActionHandler>();
+
+  // Shared resources
+  const evaluator = createEvaluator({
+    functions: [],
+    failurePolicy: WEB_FAILURE_POLICIES.EVENT_REACTION,
+  });
+  const machines = new Map<string, StateMachine>();
+  let eventBus: EventBus | null = null;
+
+  // ---- Lifecycle actions ----
+
+  handlers.set('__test_init', (action: PlayerAction) => {
+    const config = action.config as { connectEventBuses?: boolean };
+    if (config.connectEventBuses) {
+      eventBus = new EventBus();
+    }
+  });
+
+  handlers.set('__test_create_instance', (action: PlayerAction) => {
+    const { testId, definitionSlug, initialData } = action.config as {
+      testId: string;
+      definitionSlug: string;
+      initialData: Record<string, unknown>;
+    };
+
+    const def = definitions[definitionSlug];
+    if (!def) {
+      throw new Error(`Definition not found: "${definitionSlug}"`);
+    }
+
+    const smHandlers = createInstanceActionHandlers(def, evaluator);
+    const sm = new StateMachine(def, initialData, { evaluator, actionHandlers: smHandlers });
+    machines.set(testId, sm);
+
+    // Wire EventBus for cross-instance reactions
+    if (eventBus) {
+      wireOnEventSubscriptions(sm, eventBus, evaluator);
+    }
+  });
+
+  // ---- Step tracking ----
+
+  handlers.set('__test_step_begin', (action: PlayerAction) => {
+    const { stepName, stepIndex } = action.config as { stepName: string; stepIndex: number };
+    testState.currentStep = {
+      name: stepName,
+      index: stepIndex,
+      startTime: performance.now(),
+      assertions: [],
+    };
+  });
+
+  handlers.set('__test_step_end', (_action: PlayerAction) => {
+    if (!testState.currentStep) return;
+
+    const step = testState.currentStep;
+    const passed = !step.error && step.assertions.every(a => a.passed);
+    if (!passed) testState.failed = true;
+
+    testState.stepResults.push({
+      stepName: step.name,
+      passed,
+      assertionResults: step.assertions,
+      durationMs: performance.now() - step.startTime,
+      error: step.error,
+    });
+
+    // Signal to the orchestrator
+    testState.setOrchestratorField('__test_step_failed', !passed);
+    testState.currentStep = null;
+  });
+
+  // ---- Test actions ----
+
+  handlers.set('__test_transition', async (action: PlayerAction) => {
+    const { testId, transitionName, data } = action.config as {
+      testId: string;
+      transitionName: string;
+      data?: Record<string, unknown>;
+    };
+
+    const sm = machines.get(testId);
+    if (!sm) {
+      if (testState.currentStep) {
+        testState.currentStep.error = `Instance not found: "${testId}"`;
+      }
+      return;
+    }
+
+    const result = await sm.transition(transitionName, data);
+    if (!result.success) {
+      if (testState.currentStep) {
+        testState.currentStep.error = `Transition failed: ${result.error}`;
+      }
+    }
+  });
+
+  handlers.set('__test_set_field', (action: PlayerAction) => {
+    const { testId, field, value } = action.config as {
+      testId: string;
+      field: string;
+      value: unknown;
+    };
+
+    const sm = machines.get(testId);
+    if (!sm) {
+      if (testState.currentStep) {
+        testState.currentStep.error = `Instance not found: "${testId}"`;
+      }
+      return;
+    }
+
+    sm.setField(field, value);
+  });
+
+  handlers.set('__test_publish_event', async (action: PlayerAction) => {
+    const { topic, payload } = action.config as {
+      topic: string;
+      payload: Record<string, unknown>;
+    };
+
+    if (eventBus) {
+      await eventBus.publish(topic, payload);
+    }
+  });
+
+  // ---- Settle (no-op for in-process, EventBus is synchronous) ----
+
+  handlers.set('__test_settle', () => {});
+
+  // ---- Assertions ----
+
+  handlers.set('__test_assert', (action: PlayerAction) => {
+    const { testId, target, path, operator, expected, label } = action.config as {
+      testId: string;
+      target: TestAssertion['target'];
+      path?: string;
+      operator: TestAssertion['operator'];
+      expected: unknown;
+      label?: string;
+    };
+
+    const sm = machines.get(testId);
+    if (!sm) {
+      testState.currentStep?.assertions.push({
+        passed: false,
+        assertion: { target, path, operator, expected, label },
+        actual: undefined,
+        error: `Instance not found: "${testId}"`,
+      });
+      return;
+    }
+
+    const actual = getInProcessTarget(target, path, sm);
+    const passed = compareValues(actual, operator, expected);
+
+    testState.currentStep?.assertions.push({
+      passed,
+      assertion: { target, path, operator, expected, label },
+      actual,
+    });
+  });
+
+  // ---- Report ----
+
+  handlers.set('__test_report', () => {});
+
+  // ---- Standard handlers (set_field on orchestrator) ----
+
+  handlers.set('set_field', (action: PlayerAction) => {
+    testState.setOrchestratorField(
+      action.config.field as string,
+      action.config.value,
+    );
+  });
+
+  return { handlers, state: testState };
+}
+
+// =============================================================================
+// API Action Handlers
+// =============================================================================
+
+/**
+ * Create action handlers for API test execution.
+ *
+ * Test instances are real DB-backed workflow instances on the NestJS backend.
+ * The backend's EventRouter handles cross-instance reactions automatically.
+ * Settle delay allows async reactions to complete before assertions.
+ */
+export function createApiTestActions(
+  adapter: ApiTestAdapter,
+  options?: { settleDelayMs?: number },
+): { handlers: Map<string, ActionHandler>; state: TestActionState } {
+  const testState = createTestState();
+  const handlers = new Map<string, ActionHandler>();
+  const settleDelayMs = options?.settleDelayMs ?? 200;
+
+  // Map test instance IDs → server instance IDs
+  const instanceMap = new Map<string, string>();
+  const createdIds: string[] = [];
+
+  // ---- Lifecycle ----
+
+  handlers.set('__test_init', () => {
+    // EventRouter on server handles cross-instance wiring automatically
+  });
+
+  handlers.set('__test_create_instance', async (action: PlayerAction) => {
+    const { testId, definitionSlug, initialData } = action.config as {
+      testId: string;
+      definitionSlug: string;
+      initialData: Record<string, unknown>;
+    };
+
+    const snapshot = await adapter.createInstance({
+      definitionSlug,
+      stateData: Object.keys(initialData).length > 0 ? initialData : undefined,
+    });
+    instanceMap.set(testId, snapshot.id);
+    createdIds.push(snapshot.id);
+
+    // Start the instance (PENDING → ACTIVE)
+    await adapter.startInstance(snapshot.id);
+  });
+
+  // ---- Step tracking (same as in-process) ----
+
+  handlers.set('__test_step_begin', (action: PlayerAction) => {
+    const { stepName, stepIndex } = action.config as { stepName: string; stepIndex: number };
+    testState.currentStep = {
+      name: stepName,
+      index: stepIndex,
+      startTime: performance.now(),
+      assertions: [],
+    };
+  });
+
+  handlers.set('__test_step_end', (_action: PlayerAction) => {
+    if (!testState.currentStep) return;
+
+    const step = testState.currentStep;
+    const passed = !step.error && step.assertions.every(a => a.passed);
+    if (!passed) testState.failed = true;
+
+    testState.stepResults.push({
+      stepName: step.name,
+      passed,
+      assertionResults: step.assertions,
+      durationMs: performance.now() - step.startTime,
+      error: step.error,
+    });
+
+    testState.setOrchestratorField('__test_step_failed', !passed);
+    testState.currentStep = null;
+  });
+
+  // ---- Test actions (via HTTP) ----
+
+  handlers.set('__test_transition', async (action: PlayerAction) => {
+    const { testId, transitionName, data } = action.config as {
+      testId: string;
+      transitionName: string;
+      data?: Record<string, unknown>;
+    };
+
+    const serverId = instanceMap.get(testId);
+    if (!serverId) {
+      if (testState.currentStep) {
+        testState.currentStep.error = `Instance not found: "${testId}"`;
+      }
+      return;
+    }
+
+    const result = await adapter.triggerTransition(serverId, transitionName, data);
+    if (!result.success) {
+      if (testState.currentStep) {
+        testState.currentStep.error = `Transition failed: ${result.error ?? 'unknown'}`;
+      }
+    }
+  });
+
+  handlers.set('__test_set_field', async (action: PlayerAction) => {
+    const { testId, field, value } = action.config as {
+      testId: string;
+      field: string;
+      value: unknown;
+    };
+
+    const serverId = instanceMap.get(testId);
+    if (!serverId) {
+      if (testState.currentStep) {
+        testState.currentStep.error = `Instance not found: "${testId}"`;
+      }
+      return;
+    }
+
+    await adapter.updateStateData(serverId, { [field]: value });
+  });
+
+  handlers.set('__test_publish_event', async (_action: PlayerAction) => {
+    // In API mode, events flow automatically via the backend's EventRouter.
+    // publish_event is effectively a no-op — use transition actions to trigger events.
+    if (testState.currentStep) {
+      testState.currentStep.error =
+        'publish_event not supported in API mode. Events flow via EventRouter when transitions fire.';
+    }
+  });
+
+  // ---- Settle: wait for backend EventRouter to process reactions ----
+
+  handlers.set('__test_settle', async () => {
+    if (settleDelayMs > 0) {
+      await new Promise(resolve => setTimeout(resolve, settleDelayMs));
+    }
+  });
+
+  // ---- Assertions (via HTTP GET) ----
+
+  handlers.set('__test_assert', async (action: PlayerAction) => {
+    const { testId, target, path, operator, expected, label } = action.config as {
+      testId: string;
+      target: TestAssertion['target'];
+      path?: string;
+      operator: TestAssertion['operator'];
+      expected: unknown;
+      label?: string;
+    };
+
+    const serverId = instanceMap.get(testId);
+    if (!serverId) {
+      testState.currentStep?.assertions.push({
+        passed: false,
+        assertion: { target, path, operator, expected, label },
+        actual: undefined,
+        error: `Instance not found: "${testId}"`,
+      });
+      return;
+    }
+
+    const snapshot = await adapter.getInstance(serverId);
+    const actual = getApiTarget(target, path, snapshot);
+    const passed = compareValues(actual, operator, expected);
+
+    testState.currentStep?.assertions.push({
+      passed,
+      assertion: { target, path, operator, expected, label },
+      actual,
+    });
+  });
+
+  // ---- Report ----
+
+  handlers.set('__test_report', () => {});
+
+  // ---- Standard handlers ----
+
+  handlers.set('set_field', (action: PlayerAction) => {
+    testState.setOrchestratorField(
+      action.config.field as string,
+      action.config.value,
+    );
+  });
+
+  return {
+    handlers,
+    state: testState,
+    // Expose for cleanup
+    getCreatedInstanceIds: () => createdIds,
+    getInstanceMap: () => instanceMap,
+  } as { handlers: Map<string, ActionHandler>; state: TestActionState };
+}
+
+// =============================================================================
+// Helpers shared between modes
+// =============================================================================
+
+function getInProcessTarget(
+  target: TestAssertion['target'],
+  path: string | undefined,
+  sm: StateMachine,
+): unknown {
+  switch (target) {
+    case 'state':
+      return sm.currentState;
+    case 'status':
+      return sm.status;
+    case 'state_data':
+      if (!path) return sm.stateData;
+      return getNestedValue(sm.stateData, path);
+    case 'available_transitions':
+      return sm.getAvailableTransitions().map(t => t.name);
+    default:
+      throw new Error(`Unknown assertion target: "${target}"`);
+  }
+}
+
+function getApiTarget(
+  target: TestAssertion['target'],
+  path: string | undefined,
+  snapshot: { currentState: string; status: string; stateData: Record<string, unknown>; availableTransitions: string[] },
+): unknown {
+  switch (target) {
+    case 'state':
+      return snapshot.currentState;
+    case 'status':
+      return snapshot.status;
+    case 'state_data':
+      if (!path) return snapshot.stateData;
+      return getNestedValue(snapshot.stateData, path);
+    case 'available_transitions':
+      return snapshot.availableTransitions;
+    default:
+      throw new Error(`Unknown assertion target: "${target}"`);
+  }
+}
+
+function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+  const parts = path.split('.');
+  let current: unknown = obj;
+  for (const part of parts) {
+    if (current == null || typeof current !== 'object') return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+function compareValues(
+  actual: unknown,
+  operator: TestAssertion['operator'],
+  expected: unknown,
+): boolean {
+  switch (operator) {
+    case 'eq':
+      return deepEqual(actual, expected);
+    case 'neq':
+      return !deepEqual(actual, expected);
+    case 'gt':
+      return typeof actual === 'number' && typeof expected === 'number' && actual > expected;
+    case 'gte':
+      return typeof actual === 'number' && typeof expected === 'number' && actual >= expected;
+    case 'lt':
+      return typeof actual === 'number' && typeof expected === 'number' && actual < expected;
+    case 'lte':
+      return typeof actual === 'number' && typeof expected === 'number' && actual <= expected;
+    case 'contains': {
+      if (Array.isArray(actual)) return actual.includes(expected);
+      if (typeof actual === 'string' && typeof expected === 'string')
+        return actual.includes(expected);
+      return false;
+    }
+    case 'truthy':
+      return Boolean(actual);
+    case 'falsy':
+      return !actual;
+    default:
+      return false;
+  }
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a == null || b == null) return false;
+  if (typeof a !== typeof b) return false;
+
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    return a.every((v, i) => deepEqual(v, b[i]));
+  }
+
+  if (typeof a === 'object' && typeof b === 'object') {
+    const keysA = Object.keys(a as Record<string, unknown>);
+    const keysB = Object.keys(b as Record<string, unknown>);
+    if (keysA.length !== keysB.length) return false;
+    return keysA.every(k =>
+      deepEqual(
+        (a as Record<string, unknown>)[k],
+        (b as Record<string, unknown>)[k],
+      ),
+    );
+  }
+
+  return false;
+}
+
+// =============================================================================
+// Instance action handlers (for in-process test instances)
+// =============================================================================
+
+function createInstanceActionHandlers(
+  _def: PlayerWorkflowDefinition,
+  _evaluator: Evaluator,
+): Map<string, ActionHandler> {
+  const handlers = new Map<string, ActionHandler>();
+  let smRef: StateMachine | null = null;
+
+  handlers.set('set_field', (action: PlayerAction) => {
+    if (smRef && typeof action.config.field === 'string') {
+      smRef.setField(action.config.field, action.config.value);
+    }
+  });
+
+  handlers.set('set_memory', (action: PlayerAction) => {
+    if (smRef && typeof action.config.key === 'string') {
+      smRef.setMemory(action.config.key, action.config.value);
+    }
+  });
+
+  // The smRef will be set after StateMachine creation via closure
+  // This is a known pattern — see test-runner.ts
+  (handlers as any).__bindSm = (sm: StateMachine) => {
+    smRef = sm;
+  };
+
+  return handlers;
+}
+
+function wireOnEventSubscriptions(
+  sm: StateMachine,
+  eventBus: EventBus,
+  evaluator: Evaluator,
+): void {
+  const unsubs: Array<() => void> = [];
+
+  function subscribeCurrentState(): void {
+    for (const unsub of unsubs) unsub();
+    unsubs.length = 0;
+
+    const stateDef = sm.getCurrentStateDefinition();
+    if (!stateDef?.on_event?.length) return;
+
+    for (const sub of stateDef.on_event) {
+      const unsub = eventBus.subscribe(sub.match, async (event) => {
+        const ctx: ExpressionContext = {
+          ...sm.stateData,
+          state_data: sm.stateData,
+          event: event.payload,
+          current_state: sm.currentState,
+          status: sm.status,
+        };
+
+        if (sub.conditions?.length) {
+          for (const condition of sub.conditions) {
+            const result = evaluator.evaluate<boolean>(condition, ctx);
+            if (!result.value) return;
+          }
+        }
+
+        for (const action of sub.actions) {
+          if (action.type === 'set_field' && typeof action.config.field === 'string') {
+            sm.setField(action.config.field, action.config.value);
+          } else if (action.type === 'set_memory' && typeof action.config.key === 'string') {
+            sm.setMemory(action.config.key, action.config.value);
+          }
+        }
+      });
+      unsubs.push(unsub);
+    }
+  }
+
+  subscribeCurrentState();
+  sm.on((event) => {
+    if (event.type === 'state_enter') {
+      subscribeCurrentState();
+    }
+  });
+}