@mmapp/player-core 0.1.0-alpha.1

package/src/testing/test-compiler.ts

@@ -0,0 +1,278 @@
+/**
+ * Test Compiler — converts TestProgram → PlayerWorkflowDefinition.
+ *
+ * The test program IS a Blueprint. This compiler takes the ergonomic
+ * TestProgram format (scenarios, steps, assertions) and produces a
+ * standard PlayerWorkflowDefinition that any Player can execute.
+ *
+ * The compiled Blueprint uses test-specific action types (__test_*)
+ * in on_enter hooks. The Player executes these via registered action
+ * handlers — which are platform-specific (in-process, API, cross-platform).
+ *
+ * Structure of a compiled scenario Blueprint:
+ *   __setup (START) → on_enter creates instances
+ *   __step_0 (REGULAR) → on_enter performs action + assertions
+ *   __step_1 (REGULAR) → ...
+ *   __pass (END) → test passed
+ *   __fail (CANCELLED) → test failed
+ *
+ * Transitions: all named 'next' with different from states.
+ * The runner drives by calling sm.transition('next') in a loop.
+ * On failure: sm.transition('abort') → __fail.
+ */
+
+import type {
+  PlayerWorkflowDefinition,
+  PlayerStateDefinition,
+  PlayerTransitionDefinition,
+  PlayerAction,
+} from '../state-machine/types';
+import type { TestProgram, TestScenario, TestStep } from './types';
+
+/**
+ * Compile a single TestScenario into a PlayerWorkflowDefinition (Blueprint).
+ *
+ * The compiled Blueprint can be:
+ * - Stored in the database
+ * - Serialized to JSON / .mm file
+ * - Executed on any Player (browser, iOS, server)
+ * - Generated by an LLM
+ */
+export function compileTestScenario(
+  scenario: TestScenario,
+  definitions: Record<string, unknown>,
+  scenarioIndex = 0,
+): PlayerWorkflowDefinition {
+  const states: PlayerStateDefinition[] = [];
+  const transitions: PlayerTransitionDefinition[] = [];
+  const stepCount = scenario.steps.length;
+
+  // =========================================================================
+  // __idle (START): empty state. StateMachine constructor doesn't fire
+  // on_enter for START, so we need a separate setup state.
+  // =========================================================================
+
+  states.push({
+    name: '__idle',
+    type: 'START',
+  });
+
+  // =========================================================================
+  // __setup: create and start all test instances (on_enter fires on transition)
+  // =========================================================================
+
+  const setupActions: PlayerAction[] = [
+    {
+      type: '__test_init',
+      config: {
+        scenarioName: scenario.name,
+        scenarioIndex,
+        definitions: Object.keys(definitions),
+        connectEventBuses: scenario.connectEventBuses ?? false,
+      },
+    },
+  ];
+
+  if (scenario.instances?.length) {
+    for (const inst of scenario.instances) {
+      setupActions.push({
+        type: '__test_create_instance',
+        config: {
+          testId: inst.id,
+          definitionSlug: inst.definitionSlug,
+          initialData: inst.initialData ?? {},
+        },
+      });
+    }
+  } else {
+    // Single-instance: use the first definition
+    const firstSlug = Object.keys(definitions)[0];
+    if (firstSlug) {
+      setupActions.push({
+        type: '__test_create_instance',
+        config: {
+          testId: 'default',
+          definitionSlug: firstSlug,
+          initialData: {},
+        },
+      });
+    }
+  }
+
+  states.push({
+    name: '__setup',
+    type: 'REGULAR',
+    on_enter: setupActions,
+  });
+
+  // =========================================================================
+  // Step states: one per test step
+  // =========================================================================
+
+  for (let i = 0; i < stepCount; i++) {
+    const step = scenario.steps[i];
+    states.push({
+      name: `__step_${i}`,
+      type: 'REGULAR',
+      on_enter: compileStepActions(step, i),
+    });
+  }
+
+  // =========================================================================
+  // Terminal states
+  // =========================================================================
+
+  states.push({
+    name: '__pass',
+    type: 'END',
+    on_enter: [
+      { type: '__test_report', config: { passed: true } },
+    ],
+  });
+
+  states.push({
+    name: '__fail',
+    type: 'CANCELLED',
+    on_enter: [
+      { type: '__test_report', config: { passed: false } },
+    ],
+  });
+
+  // =========================================================================
+  // Transitions: 'next' advances through steps, 'abort' goes to __fail
+  // =========================================================================
+
+  // setup: __idle → __setup (fires on_enter to create instances)
+  transitions.push({
+    name: 'setup',
+    from: ['__idle'],
+    to: '__setup',
+  });
+
+  // next: __setup → __step_0 (or __pass if no steps)
+  transitions.push({
+    name: 'next',
+    from: ['__setup'],
+    to: stepCount > 0 ? '__step_0' : '__pass',
+  });
+
+  // next: __step_N → __step_N+1 (or __pass for the last step)
+  for (let i = 0; i < stepCount; i++) {
+    transitions.push({
+      name: 'next',
+      from: [`__step_${i}`],
+      to: i < stepCount - 1 ? `__step_${i + 1}` : '__pass',
+    });
+  }
+
+  // abort: any step → __fail
+  const abortFromStates = ['__setup', ...Array.from({ length: stepCount }, (_, i) => `__step_${i}`)];
+  transitions.push({
+    name: 'abort',
+    from: abortFromStates,
+    to: '__fail',
+  });
+
+  return {
+    id: `__test_scenario_${scenarioIndex}`,
+    slug: `__test_scenario_${scenarioIndex}`,
+    states,
+    transitions,
+  };
+}
+
+/**
+ * Compile all scenarios in a TestProgram into Blueprints.
+ */
+export function compileTestProgram(
+  program: TestProgram,
+): PlayerWorkflowDefinition[] {
+  return program.scenarios.map((scenario, i) =>
+    compileTestScenario(scenario, program.definitions, i),
+  );
+}
+
+// =============================================================================
+// Internals
+// =============================================================================
+
+function compileStepActions(step: TestStep, stepIndex: number): PlayerAction[] {
+  const actions: PlayerAction[] = [];
+  const defaultTestId = step.instanceId ?? 'default';
+
+  // 1. Begin step tracking
+  actions.push({
+    type: '__test_step_begin',
+    config: { stepName: step.name, stepIndex },
+  });
+
+  // 2. Perform the action
+  switch (step.action.type) {
+    case 'transition':
+      actions.push({
+        type: '__test_transition',
+        config: {
+          testId: defaultTestId,
+          transitionName: step.action.name,
+          data: step.action.data,
+        },
+      });
+      break;
+
+    case 'set_field':
+      actions.push({
+        type: '__test_set_field',
+        config: {
+          testId: defaultTestId,
+          field: step.action.field,
+          value: step.action.value,
+        },
+      });
+      break;
+
+    case 'publish_event':
+      actions.push({
+        type: '__test_publish_event',
+        config: {
+          topic: step.action.topic,
+          payload: step.action.payload ?? {},
+        },
+      });
+      break;
+
+    case 'assert_only':
+      // No action — assertions only
+      break;
+  }
+
+  // 3. Settle: wait for cross-instance EventRouter reactions
+  actions.push({
+    type: '__test_settle',
+    config: {},
+  });
+
+  // 4. Assertions
+  for (let a = 0; a < step.assertions.length; a++) {
+    const assertion = step.assertions[a];
+    actions.push({
+      type: '__test_assert',
+      config: {
+        testId: assertion.instanceId ?? defaultTestId,
+        target: assertion.target,
+        path: assertion.path,
+        operator: assertion.operator,
+        expected: assertion.expected,
+        label: assertion.label,
+        assertionIndex: a,
+      },
+    });
+  }
+
+  // 5. End step tracking
+  actions.push({
+    type: '__test_step_end',
+    config: { stepIndex },
+  });
+
+  return actions;
+}

package/src/testing/test-runner.ts

@@ -0,0 +1,444 @@
+/**
+ * Test Runner — executes test programs against the player-core engine.
+ *
+ * Runs test scenarios in-memory using StateMachine + EventBus.
+ * No database, no network, no UI — pure state machine execution.
+ *
+ * Exports:
+ * - runTestProgram(): Execute a full test program (all scenarios)
+ * - runScenario(): Execute a single scenario
+ */
+
+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 {
+  TestProgram,
+  TestScenario,
+  TestStep,
+  TestAssertion,
+  TestRunnerConfig,
+  TestProgramResult,
+  ScenarioResult,
+  StepResult,
+  AssertionResult,
+} from './types';
+
+/**
+ * Execute a complete test program (all scenarios).
+ */
+export async function runTestProgram(
+  program: TestProgram,
+  config?: TestRunnerConfig,
+): Promise<TestProgramResult> {
+  const start = performance.now();
+  const scenarioResults: ScenarioResult[] = [];
+  let allPassed = true;
+
+  for (let i = 0; i < program.scenarios.length; i++) {
+    if (config?.abortSignal?.aborted) {
+      break;
+    }
+
+    const result = await runScenario(program.scenarios[i], program.definitions, config);
+    scenarioResults.push(result);
+
+    if (!result.passed) allPassed = false;
+
+    config?.onScenarioComplete?.(result);
+  }
+
+  return {
+    passed: allPassed,
+    scenarioResults,
+    durationMs: performance.now() - start,
+  };
+}
+
+/**
+ * Execute a single test scenario.
+ */
+export async function runScenario(
+  scenario: TestScenario,
+  definitions: Record<string, PlayerWorkflowDefinition>,
+  config?: TestRunnerConfig,
+): Promise<ScenarioResult> {
+  const start = performance.now();
+
+  try {
+    // Create evaluator
+    const evaluator = createEvaluator({
+      functions: [],
+      failurePolicy: WEB_FAILURE_POLICIES.EVENT_REACTION,
+    });
+
+    // Create shared event bus (for multi-instance wiring)
+    const eventBus = scenario.connectEventBuses ? new EventBus() : null;
+
+    // Create instances
+    const instances = new Map<string, StateMachine>();
+
+    if (scenario.instances?.length) {
+      // Multi-instance scenario
+      for (const inst of scenario.instances) {
+        const def = definitions[inst.definitionSlug];
+        if (!def) {
+          return {
+            scenarioName: scenario.name,
+            passed: false,
+            stepResults: [],
+            durationMs: performance.now() - start,
+            error: `Definition not found: "${inst.definitionSlug}"`,
+          };
+        }
+
+        const sm = createStateMachine(def, inst.initialData ?? {}, evaluator, config);
+        instances.set(inst.id, sm);
+
+        // Wire on_event subscriptions to shared event bus
+        if (eventBus) {
+          wireOnEventSubscriptions(sm, eventBus, evaluator);
+        }
+      }
+    } else {
+      // Single-instance scenario — find the first definition
+      const defKeys = Object.keys(definitions);
+      if (defKeys.length === 0) {
+        return {
+          scenarioName: scenario.name,
+          passed: false,
+          stepResults: [],
+          durationMs: performance.now() - start,
+          error: 'No definitions provided',
+        };
+      }
+      const def = definitions[defKeys[0]];
+      const sm = createStateMachine(def, {}, evaluator, config);
+      instances.set('default', sm);
+
+      if (eventBus) {
+        wireOnEventSubscriptions(sm, eventBus, evaluator);
+      }
+    }
+
+    // Execute steps
+    const stepResults: StepResult[] = [];
+    let allPassed = true;
+
+    for (let i = 0; i < scenario.steps.length; i++) {
+      if (config?.abortSignal?.aborted) {
+        break;
+      }
+
+      const step = scenario.steps[i];
+      const stepResult = await executeStep(step, instances, eventBus, evaluator);
+      stepResults.push(stepResult);
+
+      if (!stepResult.passed) allPassed = false;
+
+      config?.onStepComplete?.(0, stepResult);
+    }
+
+    return {
+      scenarioName: scenario.name,
+      passed: allPassed,
+      stepResults,
+      durationMs: performance.now() - start,
+    };
+  } catch (error) {
+    return {
+      scenarioName: scenario.name,
+      passed: false,
+      stepResults: [],
+      durationMs: performance.now() - start,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+// =============================================================================
+// Internal helpers
+// =============================================================================
+
+function createStateMachine(
+  def: PlayerWorkflowDefinition,
+  initialData: Record<string, unknown>,
+  evaluator: Evaluator,
+  config?: TestRunnerConfig,
+): StateMachine {
+  const actionHandlers = new Map<string, ActionHandler>();
+
+  // Built-in set_field handler — acts on the StateMachine directly
+  // We'll set it up after creating the SM via a closure
+  let smRef: StateMachine | null = null;
+
+  actionHandlers.set('set_field', (action: PlayerAction) => {
+    if (smRef && typeof action.config.field === 'string') {
+      smRef.setField(action.config.field, action.config.value);
+    }
+  });
+
+  actionHandlers.set('set_memory', (action: PlayerAction) => {
+    if (smRef && typeof action.config.key === 'string') {
+      smRef.setMemory(action.config.key, action.config.value);
+    }
+  });
+
+  // Register custom action handlers from config
+  if (config?.actionHandlers) {
+    for (const [type, handler] of Object.entries(config.actionHandlers)) {
+      actionHandlers.set(type, (action: PlayerAction, ctx: ExpressionContext) => handler(action.config, ctx));
+    }
+  }
+
+  const sm = new StateMachine(def, initialData, { evaluator, actionHandlers });
+  smRef = sm;
+
+  return sm;
+}
+
+function wireOnEventSubscriptions(
+  sm: StateMachine,
+  eventBus: EventBus,
+  evaluator: Evaluator,
+): void {
+  const unsubs: Array<() => void> = [];
+
+  function subscribeCurrentState(): void {
+    // Clear previous subscriptions
+    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,
+        };
+
+        // Check conditions
+        if (sub.conditions?.length) {
+          for (const condition of sub.conditions) {
+            const result = evaluator.evaluate<boolean>(condition, ctx);
+            if (!result.value) return;
+          }
+        }
+
+        // Execute actions — directly invoke handlers on the state machine
+        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);
+          }
+          // Other action types (toast, play_sound, etc.) are no-ops in test mode
+        }
+      });
+      unsubs.push(unsub);
+    }
+  }
+
+  // Subscribe for initial state
+  subscribeCurrentState();
+
+  // Re-subscribe when state changes
+  sm.on((event) => {
+    if (event.type === 'state_enter') {
+      subscribeCurrentState();
+    }
+  });
+}
+
+async function executeStep(
+  step: TestStep,
+  instances: Map<string, StateMachine>,
+  eventBus: EventBus | null,
+  evaluator: Evaluator,
+): Promise<StepResult> {
+  const stepStart = performance.now();
+
+  try {
+    // Resolve target instance
+    const instanceId = step.instanceId ?? 'default';
+    const sm = instances.get(instanceId);
+
+    // Perform action
+    if (step.action.type !== 'assert_only') {
+      if (!sm && step.action.type !== 'publish_event') {
+        return {
+          stepName: step.name,
+          passed: false,
+          assertionResults: [],
+          durationMs: performance.now() - stepStart,
+          error: `Instance not found: "${instanceId}"`,
+        };
+      }
+
+      switch (step.action.type) {
+        case 'transition': {
+          const result = await sm!.transition(step.action.name, step.action.data);
+          if (!result.success) {
+            return {
+              stepName: step.name,
+              passed: false,
+              assertionResults: [],
+              durationMs: performance.now() - stepStart,
+              error: `Transition failed: ${result.error}`,
+            };
+          }
+          break;
+        }
+        case 'set_field': {
+          sm!.setField(step.action.field, step.action.value);
+          break;
+        }
+        case 'publish_event': {
+          if (eventBus) {
+            await eventBus.publish(step.action.topic, step.action.payload ?? {});
+          }
+          break;
+        }
+      }
+    }
+
+    // Evaluate assertions
+    const assertionResults = evaluateAssertions(step.assertions, instances, evaluator);
+    const passed = assertionResults.every(r => r.passed);
+
+    return {
+      stepName: step.name,
+      passed,
+      assertionResults,
+      durationMs: performance.now() - stepStart,
+    };
+  } catch (error) {
+    return {
+      stepName: step.name,
+      passed: false,
+      assertionResults: [],
+      durationMs: performance.now() - stepStart,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function evaluateAssertions(
+  assertions: TestAssertion[],
+  instances: Map<string, StateMachine>,
+  _evaluator: Evaluator,
+): AssertionResult[] {
+  return assertions.map(assertion => {
+    try {
+      const instanceId = assertion.instanceId ?? 'default';
+      const sm = instances.get(instanceId);
+      if (!sm) {
+        return {
+          passed: false,
+          assertion,
+          actual: undefined,
+          error: `Instance not found: "${instanceId}"`,
+        };
+      }
+
+      const actual = getAssertionTarget(assertion, sm);
+      const passed = compareValues(actual, assertion.operator, assertion.expected);
+
+      return { passed, assertion, actual };
+    } catch (error) {
+      return {
+        passed: false,
+        assertion,
+        actual: undefined,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  });
+}
+
+function getAssertionTarget(assertion: TestAssertion, sm: StateMachine): unknown {
+  switch (assertion.target) {
+    case 'state':
+      return sm.currentState;
+    case 'status':
+      return sm.status;
+    case 'state_data': {
+      if (!assertion.path) return sm.stateData;
+      return getNestedValue(sm.stateData, assertion.path);
+    }
+    case 'available_transitions':
+      return sm.getAvailableTransitions().map(t => t.name);
+    default:
+      throw new Error(`Unknown assertion target: "${assertion.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;
+}