@mmapp/player-core 0.1.0-alpha.1

package/src/__tests__/state-machine.test.ts

@@ -0,0 +1,450 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { StateMachine } from '../state-machine/interpreter';
+import { createEvaluator, WEB_FAILURE_POLICIES, clearExpressionCache } from '../expression';
+import type { PlayerWorkflowDefinition, PlayerAction } from '../state-machine/types';
+import type { Evaluator, ExpressionContext } from '../expression/types';
+
+function makeDefinition(overrides: Partial<PlayerWorkflowDefinition> = {}): PlayerWorkflowDefinition {
+  return {
+    id: 'test-def-1',
+    slug: 'test-workflow',
+    states: [
+      { name: 'start', type: 'START' },
+      { name: 'step1', type: 'REGULAR' },
+      { name: 'step2', type: 'REGULAR' },
+      { name: 'done', type: 'END' },
+    ],
+    transitions: [
+      { name: 'begin', from: ['start'], to: 'step1' },
+      { name: 'advance', from: ['step1'], to: 'step2' },
+      { name: 'finish', from: ['step2'], to: 'done' },
+    ],
+    ...overrides,
+  };
+}
+
+describe('StateMachine', () => {
+  let evaluator: Evaluator;
+
+  beforeEach(() => {
+    clearExpressionCache();
+    evaluator = createEvaluator({
+      functions: [],
+      failurePolicy: WEB_FAILURE_POLICIES.VIEW_BINDING,
+    });
+  });
+
+  describe('Initialization', () => {
+    it('starts in the START state', () => {
+      const sm = new StateMachine(makeDefinition(), {}, { evaluator });
+      expect(sm.currentState).toBe('start');
+      expect(sm.status).toBe('ACTIVE');
+    });
+
+    it('throws if no START state found', () => {
+      expect(() => {
+        new StateMachine(
+          makeDefinition({ states: [{ name: 'x', type: 'REGULAR' }] }),
+          {},
+          { evaluator },
+        );
+      }).toThrow('No START state');
+    });
+
+    it('accepts initial data', () => {
+      const sm = new StateMachine(makeDefinition(), { key: 'value' }, { evaluator });
+      expect(sm.stateData.key).toBe('value');
+    });
+  });
+
+  describe('Transitions', () => {
+    it('executes a valid transition', async () => {
+      const sm = new StateMachine(makeDefinition(), {}, { evaluator });
+      const result = await sm.transition('begin');
+      expect(result.success).toBe(true);
+      expect(result.from_state).toBe('start');
+      expect(result.to_state).toBe('step1');
+      expect(sm.currentState).toBe('step1');
+    });
+
+    it('rejects invalid transition from current state', async () => {
+      const sm = new StateMachine(makeDefinition(), {}, { evaluator });
+      const result = await sm.transition('advance'); // not valid from 'start'
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('not valid from state');
+    });
+
+    it('rejects transition on non-ACTIVE instance', async () => {
+      const def = makeDefinition({
+        transitions: [{ name: 'end_now', from: ['start'], to: 'done' }],
+      });
+      const sm = new StateMachine(def, {}, { evaluator });
+      await sm.transition('end_now'); // moves to 'done' (END state)
+      expect(sm.status).toBe('COMPLETED');
+
+      const result = await sm.transition('begin');
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('COMPLETED');
+    });
+
+    it('merges transition data into state_data', async () => {
+      const sm = new StateMachine(makeDefinition(), {}, { evaluator });
+      await sm.transition('begin', { extra: 42 });
+      expect(sm.stateData.extra).toBe(42);
+    });
+
+    it('chains through multiple transitions', async () => {
+      const sm = new StateMachine(makeDefinition(), {}, { evaluator });
+      await sm.transition('begin');
+      await sm.transition('advance');
+      await sm.transition('finish');
+      expect(sm.currentState).toBe('done');
+      expect(sm.status).toBe('COMPLETED');
+    });
+  });
+
+  describe('Conditions', () => {
+    it('blocks transition when condition fails', async () => {
+      const def = makeDefinition({
+        transitions: [
+          { name: 'guarded', from: ['start'], to: 'step1', conditions: ['gt(count, 10)'] },
+        ],
+      });
+      const sm = new StateMachine(def, { count: 5 }, { evaluator });
+      const result = await sm.transition('guarded');
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('condition not met');
+    });
+
+    it('allows transition when condition passes', async () => {
+      const def = makeDefinition({
+        transitions: [
+          { name: 'guarded', from: ['start'], to: 'step1', conditions: ['gt(count, 3)'] },
+        ],
+      });
+      const sm = new StateMachine(def, { count: 5 }, { evaluator });
+      const result = await sm.transition('guarded');
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('Auto-transitions', () => {
+    it('drains auto-transitions after a manual transition', async () => {
+      const def = makeDefinition({
+        transitions: [
+          { name: 'begin', from: ['start'], to: 'step1' },
+          { name: 'auto_advance', from: ['step1'], to: 'step2', auto: true },
+        ],
+      });
+      const sm = new StateMachine(def, {}, { evaluator });
+      await sm.transition('begin');
+      expect(sm.currentState).toBe('step2'); // auto-transitioned
+    });
+
+    it('chains multiple auto-transitions', async () => {
+      const def = makeDefinition({
+        transitions: [
+          { name: 'begin', from: ['start'], to: 'step1' },
+          { name: 'auto1', from: ['step1'], to: 'step2', auto: true },
+          { name: 'auto2', from: ['step2'], to: 'done', auto: true },
+        ],
+      });
+      const sm = new StateMachine(def, {}, { evaluator });
+      await sm.transition('begin');
+      expect(sm.currentState).toBe('done');
+      expect(sm.status).toBe('COMPLETED');
+    });
+
+    it('evaluates auto-transition conditions', async () => {
+      const def = makeDefinition({
+        transitions: [
+          { name: 'begin', from: ['start'], to: 'step1' },
+          { name: 'auto_guarded', from: ['step1'], to: 'step2', auto: true, conditions: ['gt(count, 10)'] },
+        ],
+      });
+      const sm = new StateMachine(def, { count: 5 }, { evaluator });
+      await sm.transition('begin');
+      expect(sm.currentState).toBe('step1'); // condition not met, stays
+    });
+
+    it('stops at MAX_AUTO_CHAIN depth', async () => {
+      // Create a circular auto-transition (A→B→A→B→...)
+      const def: PlayerWorkflowDefinition = {
+        id: 'loop',
+        slug: 'loop-workflow',
+        states: [
+          { name: 'A', type: 'START' },
+          { name: 'B', type: 'REGULAR' },
+        ],
+        transitions: [
+          { name: 'start_loop', from: ['A'], to: 'B' },
+          { name: 'loop_back', from: ['B'], to: 'A', auto: true },
+          { name: 'loop_fwd', from: ['A'], to: 'B', auto: true },
+        ],
+      };
+      const sm = new StateMachine(def, {}, { evaluator });
+      await sm.transition('start_loop');
+      // Should stop after 10 auto-transitions, not infinite loop
+      expect(['A', 'B']).toContain(sm.currentState);
+    });
+  });
+
+  describe('Terminal States', () => {
+    it('sets COMPLETED on END state', async () => {
+      const sm = new StateMachine(
+        makeDefinition({ transitions: [{ name: 'end', from: ['start'], to: 'done' }] }),
+        {},
+        { evaluator },
+      );
+      await sm.transition('end');
+      expect(sm.status).toBe('COMPLETED');
+    });
+
+    it('sets CANCELLED on CANCELLED state', async () => {
+      const def = makeDefinition({
+        states: [
+          { name: 'start', type: 'START' },
+          { name: 'cancelled', type: 'CANCELLED' },
+        ],
+        transitions: [{ name: 'cancel', from: ['start'], to: 'cancelled' }],
+      });
+      const sm = new StateMachine(def, {}, { evaluator });
+      await sm.transition('cancel');
+      expect(sm.status).toBe('CANCELLED');
+    });
+  });
+
+  describe('Actions', () => {
+    it('executes on_enter actions', async () => {
+      const actions: PlayerAction[] = [];
+      const def = makeDefinition({
+        states: [
+          { name: 'start', type: 'START' },
+          { name: 'step1', type: 'REGULAR', on_enter: [{ type: 'log', config: { message: 'entered' } }] },
+          { name: 'done', type: 'END' },
+        ],
+      });
+
+      const sm = new StateMachine(def, {}, {
+        evaluator,
+        actionHandlers: new Map([['log', (action) => { actions.push(action); }]]),
+      });
+
+      const result = await sm.transition('begin');
+      expect(result.actions_executed).toHaveLength(1);
+      expect(result.actions_executed[0].type).toBe('log');
+      expect(actions).toHaveLength(1);
+    });
+
+    it('executes on_exit actions', async () => {
+      const exitCalled = vi.fn();
+      const def = makeDefinition({
+        states: [
+          { name: 'start', type: 'START', on_exit: [{ type: 'cleanup', config: {} }] },
+          { name: 'step1', type: 'REGULAR' },
+          { name: 'done', type: 'END' },
+        ],
+      });
+
+      const sm = new StateMachine(def, {}, {
+        evaluator,
+        actionHandlers: new Map([['cleanup', exitCalled]]),
+      });
+
+      await sm.transition('begin');
+      expect(exitCalled).toHaveBeenCalledOnce();
+    });
+
+    it('executes transition actions', async () => {
+      const def = makeDefinition({
+        transitions: [
+          { name: 'begin', from: ['start'], to: 'step1', actions: [{ type: 'notify', config: { msg: 'hi' } }] },
+        ],
+      });
+      const notified = vi.fn();
+      const sm = new StateMachine(def, {}, {
+        evaluator,
+        actionHandlers: new Map([['notify', notified]]),
+      });
+
+      await sm.transition('begin');
+      expect(notified).toHaveBeenCalledOnce();
+    });
+
+    it('skips actions whose condition fails', async () => {
+      const handler = vi.fn();
+      const def = makeDefinition({
+        states: [
+          { name: 'start', type: 'START' },
+          {
+            name: 'step1', type: 'REGULAR',
+            on_enter: [{ type: 'conditional', config: {}, condition: 'eq(count, 999)' }],
+          },
+          { name: 'done', type: 'END' },
+        ],
+      });
+
+      const sm = new StateMachine(def, { count: 1 }, {
+        evaluator,
+        actionHandlers: new Map([['conditional', handler]]),
+      });
+
+      await sm.transition('begin');
+      expect(handler).not.toHaveBeenCalled();
+    });
+
+    it('continues after action errors', async () => {
+      const def = makeDefinition({
+        states: [
+          { name: 'start', type: 'START' },
+          {
+            name: 'step1', type: 'REGULAR',
+            on_enter: [
+              { type: 'failing', config: {} },
+              { type: 'succeeding', config: {} },
+            ],
+          },
+          { name: 'done', type: 'END' },
+        ],
+      });
+
+      const succeeding = vi.fn();
+      const sm = new StateMachine(def, {}, {
+        evaluator,
+        actionHandlers: new Map([
+          ['failing', () => { throw new Error('boom'); }],
+          ['succeeding', succeeding],
+        ]),
+      });
+
+      await sm.transition('begin');
+      expect(succeeding).toHaveBeenCalledOnce();
+      expect(sm.currentState).toBe('step1');
+    });
+  });
+
+  describe('Events', () => {
+    it('emits state_exit, state_enter, and transition events', async () => {
+      const events: string[] = [];
+      const sm = new StateMachine(makeDefinition(), {}, { evaluator });
+      sm.on((e) => events.push(e.type));
+
+      await sm.transition('begin');
+      expect(events).toEqual(['state_exit', 'state_enter', 'transition']);
+    });
+
+    it('emits action_executed event', async () => {
+      const events: string[] = [];
+      const def = makeDefinition({
+        states: [
+          { name: 'start', type: 'START' },
+          { name: 'step1', type: 'REGULAR', on_enter: [{ type: 'log', config: {} }] },
+          { name: 'done', type: 'END' },
+        ],
+      });
+      const sm = new StateMachine(def, {}, {
+        evaluator,
+        actionHandlers: new Map([['log', () => {}]]),
+      });
+      sm.on((e) => events.push(e.type));
+
+      await sm.transition('begin');
+      expect(events).toContain('action_executed');
+    });
+
+    it('emits error event on action failure', async () => {
+      const errors: string[] = [];
+      const def = makeDefinition({
+        states: [
+          { name: 'start', type: 'START' },
+          { name: 'step1', type: 'REGULAR', on_enter: [{ type: 'bad', config: {} }] },
+          { name: 'done', type: 'END' },
+        ],
+      });
+      const sm = new StateMachine(def, {}, {
+        evaluator,
+        actionHandlers: new Map([['bad', () => { throw new Error('oops'); }]]),
+      });
+      sm.on((e) => { if (e.type === 'error' && e.error) errors.push(e.error); });
+
+      await sm.transition('begin');
+      expect(errors).toEqual(['oops']);
+    });
+
+    it('unsubscribe removes listener', async () => {
+      const events: string[] = [];
+      const sm = new StateMachine(makeDefinition(), {}, { evaluator });
+      const unsub = sm.on((e) => events.push(e.type));
+      unsub();
+
+      await sm.transition('begin');
+      expect(events).toHaveLength(0);
+    });
+
+    it('listener errors do not break state machine', async () => {
+      const sm = new StateMachine(makeDefinition(), {}, { evaluator });
+      sm.on(() => { throw new Error('listener boom'); });
+
+      const result = await sm.transition('begin');
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('Snapshot', () => {
+    it('returns an immutable snapshot', async () => {
+      const sm = new StateMachine(makeDefinition(), { x: 1 }, { evaluator });
+      const snap = sm.getSnapshot();
+      expect(snap.current_state).toBe('start');
+      expect(snap.state_data.x).toBe(1);
+
+      // Mutating snapshot should not affect state machine
+      (snap.state_data as Record<string, unknown>).x = 999;
+      expect(sm.stateData.x).toBe(1);
+    });
+  });
+
+  describe('Utility Methods', () => {
+    it('getAvailableTransitions returns non-auto transitions from current state', () => {
+      const sm = new StateMachine(makeDefinition(), {}, { evaluator });
+      const available = sm.getAvailableTransitions();
+      expect(available).toHaveLength(1);
+      expect(available[0].name).toBe('begin');
+    });
+
+    it('getCurrentStateDefinition returns the current state', () => {
+      const sm = new StateMachine(makeDefinition(), {}, { evaluator });
+      const state = sm.getCurrentStateDefinition();
+      expect(state?.name).toBe('start');
+      expect(state?.type).toBe('START');
+    });
+
+    it('setField updates state_data', () => {
+      const sm = new StateMachine(makeDefinition(), {}, { evaluator });
+      sm.setField('newField', 'value');
+      expect(sm.stateData.newField).toBe('value');
+    });
+
+    it('setMemory updates memory', () => {
+      const sm = new StateMachine(makeDefinition(), {}, { evaluator });
+      sm.setMemory('key', 'val');
+      const snap = sm.getSnapshot();
+      expect(snap.memory.key).toBe('val');
+    });
+
+    it('registerAction adds a handler at runtime', async () => {
+      const handler = vi.fn();
+      const def = makeDefinition({
+        states: [
+          { name: 'start', type: 'START' },
+          { name: 'step1', type: 'REGULAR', on_enter: [{ type: 'dynamic', config: {} }] },
+          { name: 'done', type: 'END' },
+        ],
+      });
+      const sm = new StateMachine(def, {}, { evaluator });
+      sm.registerAction('dynamic', handler);
+
+      await sm.transition('begin');
+      expect(handler).toHaveBeenCalledOnce();
+    });
+  });
+});