@mmapp/player-core 0.1.0-alpha.1

package/src/__tests__/blueprint-test-runner.test.ts

@@ -0,0 +1,680 @@
+/**
+ * Blueprint Test Runner — tests that the test IS a Blueprint running on a Player.
+ *
+ * Verifies:
+ * - TestProgram → Blueprint compilation
+ * - In-process execution via Blueprint runner
+ * - API execution via mock adapter
+ * - Same TestProgram, different modes, same results
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { compileTestScenario, compileTestProgram } from '../testing/test-compiler';
+import { runBlueprintTestProgram, runBlueprintScenario } from '../testing/blueprint-test-runner';
+import type { PlayerWorkflowDefinition } from '../state-machine/types';
+import type { TestProgram, TestScenario, ApiTestAdapter, ApiInstanceSnapshot } from '../testing/types';
+
+// =============================================================================
+// Fixtures: PM Blueprint definitions
+// =============================================================================
+
+const PM_TASK_DEFINITION: PlayerWorkflowDefinition = {
+  id: 'pm-task',
+  slug: 'pm-task',
+  states: [
+    {
+      name: 'todo',
+      type: 'START',
+      on_enter: [
+        { type: 'set_field', config: { field: 'status_label', value: 'To Do' } },
+      ],
+    },
+    {
+      name: 'in_progress',
+      type: 'REGULAR',
+      on_enter: [
+        { type: 'set_field', config: { field: 'status_label', value: 'In Progress' } },
+      ],
+    },
+    {
+      name: 'done',
+      type: 'END',
+      on_enter: [
+        { type: 'set_field', config: { field: 'status_label', value: 'Done' } },
+      ],
+    },
+    {
+      name: 'cancelled',
+      type: 'CANCELLED',
+      on_enter: [
+        { type: 'set_field', config: { field: 'status_label', value: 'Cancelled' } },
+      ],
+    },
+  ],
+  transitions: [
+    { name: 'start', from: ['todo'], to: 'in_progress' },
+    { name: 'complete', from: ['in_progress'], to: 'done' },
+    { name: 'cancel', from: ['todo', 'in_progress'], to: 'cancelled' },
+    { name: 'reopen', from: ['done', 'cancelled'], to: 'todo' },
+  ],
+};
+
+const PM_PROJECT_DEFINITION: PlayerWorkflowDefinition = {
+  id: 'pm-project',
+  slug: 'pm-project',
+  states: [
+    {
+      name: 'draft',
+      type: 'START',
+      on_enter: [
+        { type: 'set_field', config: { field: 'total_tasks', value: 0 } },
+        { type: 'set_field', config: { field: 'completed_tasks', value: 0 } },
+      ],
+    },
+    {
+      name: 'active',
+      type: 'REGULAR',
+      on_event: [
+        {
+          match: '*:*:pm-task:transition.completed',
+          actions: [
+            {
+              type: 'set_field',
+              config: { field: 'last_task_event', value: 'task_transitioned' },
+            },
+          ],
+        },
+      ],
+    },
+    { name: 'completed', type: 'END' },
+    { name: 'cancelled', type: 'CANCELLED' },
+  ],
+  transitions: [
+    { name: 'activate', from: ['draft'], to: 'active' },
+    {
+      name: 'auto_complete',
+      from: ['active'],
+      to: 'completed',
+      auto: true,
+      conditions: ['gt(completed_tasks, 0)', 'eq(completed_tasks, total_tasks)'],
+    },
+    { name: 'cancel', from: ['draft', 'active'], to: 'cancelled' },
+  ],
+};
+
+// =============================================================================
+// Compiler Tests
+// =============================================================================
+
+describe('Test Compiler', () => {
+  it('compiles a single-step scenario to a valid Blueprint', () => {
+    const scenario: TestScenario = {
+      name: 'Simple',
+      steps: [
+        {
+          name: 'Start task',
+          action: { type: 'transition', name: 'start' },
+          assertions: [{ target: 'state', operator: 'eq', expected: 'in_progress' }],
+        },
+      ],
+    };
+
+    const blueprint = compileTestScenario(scenario, { 'pm-task': PM_TASK_DEFINITION });
+
+    // Has required states
+    const stateNames = blueprint.states.map(s => s.name);
+    expect(stateNames).toContain('__idle');
+    expect(stateNames).toContain('__setup');
+    expect(stateNames).toContain('__step_0');
+    expect(stateNames).toContain('__pass');
+    expect(stateNames).toContain('__fail');
+
+    // START state is __idle (empty, no actions)
+    const startState = blueprint.states.find(s => s.type === 'START');
+    expect(startState?.name).toBe('__idle');
+
+    // __setup is REGULAR with on_enter actions
+    const setupState = blueprint.states.find(s => s.name === '__setup');
+    expect(setupState?.type).toBe('REGULAR');
+
+    // Has transitions (including setup: __idle → __setup)
+    expect(blueprint.transitions.length).toBeGreaterThan(0);
+    expect(blueprint.transitions.find(t => t.name === 'setup')).toBeDefined();
+
+    // Setup has __test_init and __test_create_instance actions
+    const setupActions = setupState!.on_enter!;
+    expect(setupActions.find(a => a.type === '__test_init')).toBeDefined();
+    expect(setupActions.find(a => a.type === '__test_create_instance')).toBeDefined();
+  });
+
+  it('compiles multi-step scenario with correct step count', () => {
+    const scenario: TestScenario = {
+      name: 'Multi-step',
+      steps: [
+        {
+          name: 'Step 1',
+          action: { type: 'transition', name: 'start' },
+          assertions: [{ target: 'state', operator: 'eq', expected: 'in_progress' }],
+        },
+        {
+          name: 'Step 2',
+          action: { type: 'transition', name: 'complete' },
+          assertions: [{ target: 'state', operator: 'eq', expected: 'done' }],
+        },
+      ],
+    };
+
+    const blueprint = compileTestScenario(scenario, { 'pm-task': PM_TASK_DEFINITION });
+
+    // Should have __idle, __setup, __step_0, __step_1, __pass, __fail = 6 states
+    expect(blueprint.states).toHaveLength(6);
+
+    // __step_0 on_enter should have: step_begin, transition, settle, assert, step_end
+    const step0 = blueprint.states.find(s => s.name === '__step_0');
+    expect(step0!.on_enter!.find(a => a.type === '__test_transition')).toBeDefined();
+    expect(step0!.on_enter!.find(a => a.type === '__test_assert')).toBeDefined();
+  });
+
+  it('compiles multi-instance scenario with separate create actions', () => {
+    const scenario: TestScenario = {
+      name: 'Multi-instance',
+      connectEventBuses: true,
+      instances: [
+        { id: 'project', definitionSlug: 'pm-project', initialData: { total_tasks: 1 } },
+        { id: 'task', definitionSlug: 'pm-task' },
+      ],
+      steps: [],
+    };
+
+    const blueprint = compileTestScenario(scenario, {
+      'pm-project': PM_PROJECT_DEFINITION,
+      'pm-task': PM_TASK_DEFINITION,
+    });
+
+    const setup = blueprint.states.find(s => s.name === '__setup');
+    const createActions = setup!.on_enter!.filter(a => a.type === '__test_create_instance');
+    expect(createActions).toHaveLength(2);
+    expect(createActions[0].config.testId).toBe('project');
+    expect(createActions[1].config.testId).toBe('task');
+
+    // Init should have connectEventBuses
+    const initAction = setup!.on_enter!.find(a => a.type === '__test_init');
+    expect(initAction!.config.connectEventBuses).toBe(true);
+  });
+
+  it('compileTestProgram produces one Blueprint per scenario', () => {
+    const program: TestProgram = {
+      name: 'Multi-scenario',
+      definitionSlug: 'pm-task',
+      definitions: { 'pm-task': PM_TASK_DEFINITION },
+      scenarios: [
+        { name: 'S1', steps: [] },
+        { name: 'S2', steps: [] },
+      ],
+    };
+
+    const blueprints = compileTestProgram(program);
+    expect(blueprints).toHaveLength(2);
+    expect(blueprints[0].slug).toBe('__test_scenario_0');
+    expect(blueprints[1].slug).toBe('__test_scenario_1');
+  });
+
+  it('step with assert_only has no test action, only assertions', () => {
+    const scenario: TestScenario = {
+      name: 'Assert only',
+      steps: [
+        {
+          name: 'Check state',
+          action: { type: 'assert_only' },
+          assertions: [{ target: 'state', operator: 'eq', expected: 'todo' }],
+        },
+      ],
+    };
+
+    const blueprint = compileTestScenario(scenario, { 'pm-task': PM_TASK_DEFINITION });
+    const step = blueprint.states.find(s => s.name === '__step_0');
+    const actions = step!.on_enter!;
+
+    // Should NOT have __test_transition, __test_set_field, etc.
+    expect(actions.find(a => a.type === '__test_transition')).toBeUndefined();
+    expect(actions.find(a => a.type === '__test_set_field')).toBeUndefined();
+
+    // Should HAVE __test_assert
+    expect(actions.find(a => a.type === '__test_assert')).toBeDefined();
+  });
+});
+
+// =============================================================================
+// Blueprint Runner — In-Process Mode
+// =============================================================================
+
+describe('Blueprint Runner (in-process)', () => {
+  it('runs PM-Task lifecycle through compiled Blueprint', async () => {
+    const program: TestProgram = {
+      name: 'PM-Task Lifecycle',
+      definitionSlug: 'pm-task',
+      definitions: { 'pm-task': PM_TASK_DEFINITION },
+      scenarios: [
+        {
+          name: 'Happy path',
+          steps: [
+            {
+              name: 'Start task',
+              action: { type: 'transition', name: 'start' },
+              assertions: [
+                { target: 'state', operator: 'eq', expected: 'in_progress' },
+                { target: 'status', operator: 'eq', expected: 'ACTIVE' },
+              ],
+            },
+            {
+              name: 'Complete task',
+              action: { type: 'transition', name: 'complete' },
+              assertions: [
+                { target: 'state', operator: 'eq', expected: 'done' },
+                { target: 'status', operator: 'eq', expected: 'COMPLETED' },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = await runBlueprintTestProgram(program, { mode: 'in-process' });
+
+    expect(result.passed).toBe(true);
+    expect(result.scenarioResults).toHaveLength(1);
+    expect(result.scenarioResults[0].passed).toBe(true);
+    expect(result.scenarioResults[0].stepResults).toHaveLength(2);
+    expect(result.durationMs).toBeLessThan(100);
+  });
+
+  it('reports failing assertion', async () => {
+    const program: TestProgram = {
+      name: 'Failing',
+      definitionSlug: 'pm-task',
+      definitions: { 'pm-task': PM_TASK_DEFINITION },
+      scenarios: [
+        {
+          name: 'Wrong state',
+          steps: [
+            {
+              name: 'Start then expect done',
+              action: { type: 'transition', name: 'start' },
+              assertions: [
+                { target: 'state', operator: 'eq', expected: 'done' },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = await runBlueprintTestProgram(program, { mode: 'in-process' });
+
+    expect(result.passed).toBe(false);
+    const step = result.scenarioResults[0].stepResults[0];
+    expect(step.passed).toBe(false);
+    expect(step.assertionResults[0].actual).toBe('in_progress');
+    expect(step.assertionResults[0].assertion.expected).toBe('done');
+  });
+
+  it('handles set_field action', async () => {
+    const program: TestProgram = {
+      name: 'Set field',
+      definitionSlug: 'pm-task',
+      definitions: { 'pm-task': PM_TASK_DEFINITION },
+      scenarios: [
+        {
+          name: 'Set field',
+          steps: [
+            {
+              name: 'Set priority',
+              action: { type: 'set_field', field: 'priority', value: 'high' },
+              assertions: [
+                { target: 'state_data', path: 'priority', operator: 'eq', expected: 'high' },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = await runBlueprintTestProgram(program, { mode: 'in-process' });
+    expect(result.passed).toBe(true);
+  });
+
+  it('handles assert_only step', async () => {
+    const program: TestProgram = {
+      name: 'Assert only',
+      definitionSlug: 'pm-task',
+      definitions: { 'pm-task': PM_TASK_DEFINITION },
+      scenarios: [
+        {
+          name: 'Check initial state',
+          steps: [
+            {
+              name: 'Verify todo state',
+              action: { type: 'assert_only' },
+              assertions: [
+                { target: 'state', operator: 'eq', expected: 'todo' },
+                { target: 'available_transitions', operator: 'contains', expected: 'start' },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = await runBlueprintTestProgram(program, { mode: 'in-process' });
+    expect(result.passed).toBe(true);
+  });
+
+  it('multi-instance with EventBus cross-reactions', async () => {
+    const program: TestProgram = {
+      name: 'Multi-instance',
+      definitionSlug: 'pm-project',
+      definitions: {
+        'pm-project': PM_PROJECT_DEFINITION,
+        'pm-task': PM_TASK_DEFINITION,
+      },
+      scenarios: [
+        {
+          name: 'Task completion updates project',
+          connectEventBuses: true,
+          instances: [
+            { id: 'project', definitionSlug: 'pm-project', initialData: { total_tasks: 2, completed_tasks: 0 } },
+            { id: 'task1', definitionSlug: 'pm-task' },
+          ],
+          steps: [
+            {
+              name: 'Activate project',
+              instanceId: 'project',
+              action: { type: 'transition', name: 'activate' },
+              assertions: [
+                { target: 'state', instanceId: 'project', operator: 'eq', expected: 'active' },
+              ],
+            },
+            {
+              name: 'Start task',
+              instanceId: 'task1',
+              action: { type: 'transition', name: 'start' },
+              assertions: [
+                { target: 'state', instanceId: 'task1', operator: 'eq', expected: 'in_progress' },
+              ],
+            },
+            {
+              name: 'Publish task completed event',
+              action: {
+                type: 'publish_event',
+                topic: 'stakeholder:s1:pm-task:transition.completed',
+                payload: { transition_name: 'complete' },
+              },
+              assertions: [
+                {
+                  target: 'state_data',
+                  instanceId: 'project',
+                  path: 'last_task_event',
+                  operator: 'eq',
+                  expected: 'task_transitioned',
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = await runBlueprintTestProgram(program, { mode: 'in-process' });
+
+    expect(result.passed).toBe(true);
+    expect(result.scenarioResults[0].stepResults).toHaveLength(3);
+  });
+
+  it('calls onStepComplete callback', async () => {
+    const onStepComplete = vi.fn();
+
+    const program: TestProgram = {
+      name: 'Callbacks',
+      definitionSlug: 'pm-task',
+      definitions: { 'pm-task': PM_TASK_DEFINITION },
+      scenarios: [
+        {
+          name: 'Two steps',
+          steps: [
+            {
+              name: 'Start',
+              action: { type: 'transition', name: 'start' },
+              assertions: [{ target: 'state', operator: 'eq', expected: 'in_progress' }],
+            },
+            {
+              name: 'Complete',
+              action: { type: 'transition', name: 'complete' },
+              assertions: [{ target: 'state', operator: 'eq', expected: 'done' }],
+            },
+          ],
+        },
+      ],
+    };
+
+    await runBlueprintTestProgram(program, { mode: 'in-process', onStepComplete });
+    expect(onStepComplete).toHaveBeenCalledTimes(2);
+  });
+
+  it('stops on first failed step', async () => {
+    const program: TestProgram = {
+      name: 'Fail early',
+      definitionSlug: 'pm-task',
+      definitions: { 'pm-task': PM_TASK_DEFINITION },
+      scenarios: [
+        {
+          name: 'Fails at step 1',
+          steps: [
+            {
+              name: 'Wrong assertion',
+              action: { type: 'transition', name: 'start' },
+              assertions: [{ target: 'state', operator: 'eq', expected: 'done' }],
+            },
+            {
+              name: 'Should not run',
+              action: { type: 'transition', name: 'complete' },
+              assertions: [{ target: 'state', operator: 'eq', expected: 'done' }],
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = await runBlueprintTestProgram(program, { mode: 'in-process' });
+    expect(result.passed).toBe(false);
+    // Only one step should have executed
+    expect(result.scenarioResults[0].stepResults).toHaveLength(1);
+  });
+});
+
+// =============================================================================
+// Blueprint Runner — API Mode (Mock Adapter)
+// =============================================================================
+
+describe('Blueprint Runner (API mode)', () => {
+  function createMockAdapter(): ApiTestAdapter & { instances: Map<string, any> } {
+    const instances = new Map<string, any>();
+    let nextId = 1;
+
+    return {
+      instances,
+
+      async createInstance({ definitionSlug, stateData }) {
+        const id = `mock-${nextId++}`;
+        instances.set(id, {
+          id,
+          definitionSlug,
+          currentState: 'todo', // simplified: assume START state
+          status: 'PENDING',
+          stateData: stateData ?? {},
+          availableTransitions: ['start', 'cancel'],
+        });
+        return instances.get(id)!;
+      },
+
+      async startInstance(instanceId) {
+        const inst = instances.get(instanceId);
+        if (inst) inst.status = 'ACTIVE';
+        return inst;
+      },
+
+      async deleteInstance(instanceId) {
+        instances.delete(instanceId);
+      },
+
+      async triggerTransition(instanceId, transitionName) {
+        const inst = instances.get(instanceId);
+        if (!inst) return { success: false, fromState: '', toState: '', error: 'Not found' };
+
+        // Simplified transition logic for mock
+        const fromState = inst.currentState;
+        const transitions: Record<string, Record<string, string>> = {
+          todo: { start: 'in_progress', cancel: 'cancelled' },
+          in_progress: { complete: 'done', cancel: 'cancelled' },
+          done: { reopen: 'todo' },
+          cancelled: { reopen: 'todo' },
+        };
+
+        const targetState = transitions[fromState]?.[transitionName];
+        if (!targetState) {
+          return { success: false, fromState, toState: fromState, error: `Invalid transition: ${transitionName} from ${fromState}` };
+        }
+
+        inst.currentState = targetState;
+        if (targetState === 'done') inst.status = 'COMPLETED';
+        if (targetState === 'cancelled') inst.status = 'CANCELLED';
+
+        return { success: true, fromState, toState: targetState };
+      },
+
+      async updateStateData(instanceId, data) {
+        const inst = instances.get(instanceId);
+        if (inst) inst.stateData = { ...inst.stateData, ...data };
+        return inst;
+      },
+
+      async getInstance(instanceId) {
+        const inst = instances.get(instanceId);
+        if (!inst) throw new Error(`Instance not found: ${instanceId}`);
+        return inst;
+      },
+    };
+  }
+
+  it('runs PM-Task lifecycle via mock API adapter', async () => {
+    const adapter = createMockAdapter();
+
+    const program: TestProgram = {
+      name: 'API Test',
+      definitionSlug: 'pm-task',
+      definitions: { 'pm-task': PM_TASK_DEFINITION },
+      scenarios: [
+        {
+          name: 'Happy path via API',
+          steps: [
+            {
+              name: 'Start task',
+              action: { type: 'transition', name: 'start' },
+              assertions: [
+                { target: 'state', operator: 'eq', expected: 'in_progress' },
+              ],
+            },
+            {
+              name: 'Complete task',
+              action: { type: 'transition', name: 'complete' },
+              assertions: [
+                { target: 'state', operator: 'eq', expected: 'done' },
+                { target: 'status', operator: 'eq', expected: 'COMPLETED' },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = await runBlueprintTestProgram(program, {
+      mode: 'api',
+      adapter,
+      settleDelayMs: 0, // No settle delay for tests
+    });
+
+    expect(result.passed).toBe(true);
+    expect(result.scenarioResults[0].stepResults).toHaveLength(2);
+  });
+
+  it('reports transition failure via API', async () => {
+    const adapter = createMockAdapter();
+
+    const program: TestProgram = {
+      name: 'API Fail',
+      definitionSlug: 'pm-task',
+      definitions: { 'pm-task': PM_TASK_DEFINITION },
+      scenarios: [
+        {
+          name: 'Invalid transition',
+          steps: [
+            {
+              name: 'Complete from todo (invalid)',
+              action: { type: 'transition', name: 'complete' },
+              assertions: [],
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = await runBlueprintTestProgram(program, {
+      mode: 'api',
+      adapter,
+      settleDelayMs: 0,
+    });
+
+    expect(result.passed).toBe(false);
+    expect(result.scenarioResults[0].stepResults[0].error).toContain('Invalid transition');
+  });
+
+  it('same TestProgram works in both modes', async () => {
+    const program: TestProgram = {
+      name: 'Cross-mode',
+      definitionSlug: 'pm-task',
+      definitions: { 'pm-task': PM_TASK_DEFINITION },
+      scenarios: [
+        {
+          name: 'Start task',
+          steps: [
+            {
+              name: 'Start',
+              action: { type: 'transition', name: 'start' },
+              assertions: [
+                { target: 'state', operator: 'eq', expected: 'in_progress' },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+
+    // In-process
+    const inProcessResult = await runBlueprintTestProgram(program, { mode: 'in-process' });
+
+    // API
+    const adapter = createMockAdapter();
+    const apiResult = await runBlueprintTestProgram(program, {
+      mode: 'api',
+      adapter,
+      settleDelayMs: 0,
+    });
+
+    // Both should pass
+    expect(inProcessResult.passed).toBe(true);
+    expect(apiResult.passed).toBe(true);
+
+    // Both should have same step count
+    expect(inProcessResult.scenarioResults[0].stepResults.length)
+      .toBe(apiResult.scenarioResults[0].stepResults.length);
+  });
+});