@mmapp/player-core 0.1.0-alpha.1

package/src/__tests__/testing-engine.test.ts

@@ -0,0 +1,671 @@
+/**
+ * Testing OS — Unit tests for the testing engine.
+ *
+ * Uses PM Blueprint definitions (PM-Task, PM-Project) as fixtures.
+ * Tests graph walker, coverage generation, test runner (single + multi-instance).
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { analyzeDefinition, generateCoverageScenarios } from '../testing/graph-walker';
+import { runTestProgram, runScenario } from '../testing/test-runner';
+import type { PlayerWorkflowDefinition } from '../state-machine/types';
+import type { TestProgram, TestScenario } from '../testing/types';
+
+// =============================================================================
+// Fixtures: PM Blueprint definitions (from blueprint-e2e.test.ts)
+// =============================================================================
+
+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' },
+  ],
+};
+
+// =============================================================================
+// Graph Walker Tests
+// =============================================================================
+
+describe('Graph Walker', () => {
+  describe('analyzeDefinition', () => {
+    it('correctly analyzes PM-Task (4 states, 4 transitions)', () => {
+      const analysis = analyzeDefinition(PM_TASK_DEFINITION);
+
+      expect(analysis.states).toHaveLength(4);
+      expect(analysis.summary.totalStates).toBe(4);
+      expect(analysis.summary.reachableStates).toBe(4);
+      expect(analysis.unreachableStates).toHaveLength(0);
+      expect(analysis.deadEndStates).toHaveLength(0);
+
+      // All states reachable
+      for (const state of analysis.states) {
+        expect(state.reachable).toBe(true);
+      }
+    });
+
+    it('finds terminal paths in PM-Task', () => {
+      const analysis = analyzeDefinition(PM_TASK_DEFINITION);
+
+      // Paths: todo→in_progress→done, todo→cancelled, todo→in_progress→cancelled
+      expect(analysis.terminalPaths.length).toBeGreaterThanOrEqual(3);
+
+      // Each terminal path should end at 'done' or 'cancelled'
+      for (const path of analysis.terminalPaths) {
+        const lastState = path.states[path.states.length - 1];
+        expect(['done', 'cancelled']).toContain(lastState);
+      }
+    });
+
+    it('detects cycles (reopen from done/cancelled)', () => {
+      const analysis = analyzeDefinition(PM_TASK_DEFINITION);
+
+      // reopen creates cycles: done→todo and cancelled→todo
+      expect(analysis.cycles.length).toBeGreaterThan(0);
+    });
+
+    it('correctly analyzes PM-Project (auto-transition)', () => {
+      const analysis = analyzeDefinition(PM_PROJECT_DEFINITION);
+
+      expect(analysis.states).toHaveLength(4);
+      expect(analysis.summary.reachableStates).toBe(4);
+
+      // Should have edges for auto_complete
+      const autoEdges = analysis.edges.filter(e => e.auto);
+      expect(autoEdges.length).toBe(1);
+      expect(autoEdges[0].name).toBe('auto_complete');
+    });
+
+    it('identifies unreachable states', () => {
+      const isolated: PlayerWorkflowDefinition = {
+        id: 'test-isolated',
+        slug: 'test-isolated',
+        states: [
+          { name: 'start', type: 'START' },
+          { name: 'middle', type: 'REGULAR' },
+          { name: 'end', type: 'END' },
+          { name: 'orphan', type: 'REGULAR' }, // unreachable
+        ],
+        transitions: [
+          { name: 'go', from: ['start'], to: 'middle' },
+          { name: 'finish', from: ['middle'], to: 'end' },
+        ],
+      };
+
+      const analysis = analyzeDefinition(isolated);
+      expect(analysis.unreachableStates).toContain('orphan');
+      expect(analysis.summary.unreachableStates).toBe(1);
+    });
+
+    it('identifies dead-end states', () => {
+      const deadEnd: PlayerWorkflowDefinition = {
+        id: 'test-deadend',
+        slug: 'test-deadend',
+        states: [
+          { name: 'start', type: 'START' },
+          { name: 'stuck', type: 'REGULAR' }, // no outgoing transitions
+        ],
+        transitions: [
+          { name: 'go', from: ['start'], to: 'stuck' },
+        ],
+      };
+
+      const analysis = analyzeDefinition(deadEnd);
+      expect(analysis.deadEndStates).toContain('stuck');
+      expect(analysis.summary.deadEndStates).toBe(1);
+    });
+
+    it('handles definition with no START state', () => {
+      const noStart: PlayerWorkflowDefinition = {
+        id: 'no-start',
+        slug: 'no-start',
+        states: [
+          { name: 'a', type: 'REGULAR' },
+          { name: 'b', type: 'END' },
+        ],
+        transitions: [
+          { name: 'go', from: ['a'], to: 'b' },
+        ],
+      };
+
+      const analysis = analyzeDefinition(noStart);
+      expect(analysis.terminalPaths).toHaveLength(0);
+      expect(analysis.unreachableStates).toHaveLength(2);
+    });
+  });
+
+  describe('generateCoverageScenarios', () => {
+    it('generates one scenario per terminal path for PM-Task', () => {
+      const analysis = analyzeDefinition(PM_TASK_DEFINITION);
+      const scenarios = generateCoverageScenarios(PM_TASK_DEFINITION, analysis);
+
+      expect(scenarios.length).toBe(analysis.terminalPaths.length);
+
+      // Each scenario should have the 'auto-generated' tag
+      for (const scenario of scenarios) {
+        expect(scenario.tags).toContain('auto-generated');
+        expect(scenario.steps.length).toBeGreaterThan(0);
+      }
+    });
+
+    it('scenario steps assert correct state after each transition', () => {
+      const scenarios = generateCoverageScenarios(PM_TASK_DEFINITION);
+
+      // Find the happy path: todo → in_progress → done
+      const happyPath = scenarios.find(s => s.name.includes('done'));
+      expect(happyPath).toBeDefined();
+
+      // First step should be 'start' transition, assert state 'in_progress'
+      const firstStep = happyPath!.steps[0];
+      expect(firstStep.action).toEqual({ type: 'transition', name: 'start' });
+      expect(firstStep.assertions[0]).toMatchObject({
+        target: 'state',
+        operator: 'eq',
+        expected: 'in_progress',
+      });
+    });
+
+    it('generates scenarios for PM-Project including auto-transition path', () => {
+      const scenarios = generateCoverageScenarios(PM_PROJECT_DEFINITION);
+
+      // Should have paths through completed and cancelled
+      expect(scenarios.length).toBeGreaterThanOrEqual(2);
+
+      const pathNames = scenarios.map(s => s.name);
+      expect(pathNames.some(n => n.includes('completed'))).toBe(true);
+      expect(pathNames.some(n => n.includes('cancelled'))).toBe(true);
+    });
+
+    it('terminal steps assert status', () => {
+      const scenarios = generateCoverageScenarios(PM_TASK_DEFINITION);
+
+      const donePath = scenarios.find(s => s.name.includes('done'));
+      expect(donePath).toBeDefined();
+
+      const lastStep = donePath!.steps[donePath!.steps.length - 1];
+      const statusAssertion = lastStep.assertions.find(a => a.target === 'status');
+      expect(statusAssertion).toBeDefined();
+      expect(statusAssertion!.expected).toBe('COMPLETED');
+    });
+  });
+});
+
+// =============================================================================
+// Test Runner Tests
+// =============================================================================
+
+describe('Test Runner', () => {
+  describe('Single-instance scenarios', () => {
+    it('runs PM-Task full lifecycle (todo → in_progress → done)', 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 runTestProgram(program);
+
+      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('verifies state_data via set_field action', async () => {
+      const program: TestProgram = {
+        name: 'State data test',
+        definitionSlug: 'pm-task',
+        definitions: { 'pm-task': PM_TASK_DEFINITION },
+        scenarios: [
+          {
+            name: 'set_field works',
+            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 runTestProgram(program);
+      expect(result.passed).toBe(true);
+    });
+
+    it('reports failing assertion correctly', async () => {
+      const program: TestProgram = {
+        name: 'Failing test',
+        definitionSlug: 'pm-task',
+        definitions: { 'pm-task': PM_TASK_DEFINITION },
+        scenarios: [
+          {
+            name: 'Wrong state',
+            steps: [
+              {
+                name: 'Start task',
+                action: { type: 'transition', name: 'start' },
+                assertions: [
+                  { target: 'state', operator: 'eq', expected: 'done', label: 'Should be done (will fail)' },
+                ],
+              },
+            ],
+          },
+        ],
+      };
+
+      const result = await runTestProgram(program);
+
+      expect(result.passed).toBe(false);
+      expect(result.scenarioResults[0].passed).toBe(false);
+
+      const failedAssertion = result.scenarioResults[0].stepResults[0].assertionResults[0];
+      expect(failedAssertion.passed).toBe(false);
+      expect(failedAssertion.actual).toBe('in_progress');
+      expect(failedAssertion.assertion.expected).toBe('done');
+    });
+
+    it('available_transitions assertion works', async () => {
+      const program: TestProgram = {
+        name: 'Available transitions',
+        definitionSlug: 'pm-task',
+        definitions: { 'pm-task': PM_TASK_DEFINITION },
+        scenarios: [
+          {
+            name: 'Check available transitions',
+            steps: [
+              {
+                name: 'In todo state',
+                action: { type: 'assert_only' },
+                assertions: [
+                  { target: 'available_transitions', operator: 'contains', expected: 'start' },
+                  { target: 'available_transitions', operator: 'contains', expected: 'cancel' },
+                ],
+              },
+            ],
+          },
+        ],
+      };
+
+      const result = await runTestProgram(program);
+      expect(result.passed).toBe(true);
+    });
+
+    it('numeric comparison operators work', async () => {
+      const program: TestProgram = {
+        name: 'Numeric operators',
+        definitionSlug: 'pm-task',
+        definitions: { 'pm-task': PM_TASK_DEFINITION },
+        scenarios: [
+          {
+            name: 'Numeric assertions',
+            steps: [
+              {
+                name: 'Set count',
+                action: { type: 'set_field', field: 'count', value: 5 },
+                assertions: [
+                  { target: 'state_data', path: 'count', operator: 'gt', expected: 3 },
+                  { target: 'state_data', path: 'count', operator: 'gte', expected: 5 },
+                  { target: 'state_data', path: 'count', operator: 'lt', expected: 10 },
+                  { target: 'state_data', path: 'count', operator: 'lte', expected: 5 },
+                  { target: 'state_data', path: 'count', operator: 'neq', expected: 0 },
+                ],
+              },
+            ],
+          },
+        ],
+      };
+
+      const result = await runTestProgram(program);
+      expect(result.passed).toBe(true);
+    });
+  });
+
+  describe('Multi-instance scenarios', () => {
+    it('PM-Project + PM-Task connected via EventBus: complete task → verify project state_data', async () => {
+      const scenario: TestScenario = {
+        name: 'Multi-instance: 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: [
+          // Activate the project
+          {
+            name: 'Activate project',
+            instanceId: 'project',
+            action: { type: 'transition', name: 'activate' },
+            assertions: [
+              { target: 'state', instanceId: 'project', operator: 'eq', expected: 'active' },
+            ],
+          },
+          // Start task
+          {
+            name: 'Start task',
+            instanceId: 'task1',
+            action: { type: 'transition', name: 'start' },
+            assertions: [
+              { target: 'state', instanceId: 'task1', operator: 'eq', expected: 'in_progress' },
+            ],
+          },
+          // Simulate task completion domain event on the shared event bus
+          {
+            name: 'Publish task completed event',
+            action: {
+              type: 'publish_event',
+              topic: 'stakeholder:s1:pm-task:transition.completed',
+              payload: {
+                transition_name: 'complete',
+                from_state: 'in_progress',
+                to_state: 'done',
+              },
+            },
+            assertions: [
+              // Project's on_event should have set last_task_event
+              {
+                target: 'state_data',
+                instanceId: 'project',
+                path: 'last_task_event',
+                operator: 'eq',
+                expected: 'task_transitioned',
+              },
+            ],
+          },
+        ],
+      };
+
+      const result = await runScenario(
+        scenario,
+        { 'pm-project': PM_PROJECT_DEFINITION, 'pm-task': PM_TASK_DEFINITION },
+      );
+
+      expect(result.passed).toBe(true);
+      expect(result.stepResults).toHaveLength(3);
+    });
+  });
+
+  describe('Auto-generated coverage', () => {
+    it('runs auto-generated scenarios from graph walker', async () => {
+      const analysis = analyzeDefinition(PM_TASK_DEFINITION);
+      const scenarios = generateCoverageScenarios(PM_TASK_DEFINITION, analysis);
+
+      const program: TestProgram = {
+        name: 'Auto-generated PM-Task coverage',
+        definitionSlug: 'pm-task',
+        definitions: { 'pm-task': PM_TASK_DEFINITION },
+        scenarios,
+      };
+
+      const result = await runTestProgram(program);
+
+      // All auto-generated scenarios should pass
+      expect(result.passed).toBe(true);
+      expect(result.scenarioResults.length).toBe(scenarios.length);
+      expect(result.durationMs).toBeLessThan(100);
+    });
+  });
+
+  describe('Callbacks and abort', () => {
+    it('calls onStepComplete callback', async () => {
+      const onStepComplete = vi.fn();
+
+      const program: TestProgram = {
+        name: 'Callback test',
+        definitionSlug: 'pm-task',
+        definitions: { 'pm-task': PM_TASK_DEFINITION },
+        scenarios: [
+          {
+            name: 'With callbacks',
+            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 runTestProgram(program, { onStepComplete });
+
+      expect(onStepComplete).toHaveBeenCalledTimes(2);
+    });
+
+    it('calls onScenarioComplete callback', async () => {
+      const onScenarioComplete = vi.fn();
+
+      const program: TestProgram = {
+        name: 'Scenario callback test',
+        definitionSlug: 'pm-task',
+        definitions: { 'pm-task': PM_TASK_DEFINITION },
+        scenarios: [
+          {
+            name: 'First',
+            steps: [
+              {
+                name: 'Start',
+                action: { type: 'transition', name: 'start' },
+                assertions: [{ target: 'state', operator: 'eq', expected: 'in_progress' }],
+              },
+            ],
+          },
+          {
+            name: 'Second',
+            steps: [
+              {
+                name: 'Cancel',
+                action: { type: 'transition', name: 'cancel' },
+                assertions: [{ target: 'state', operator: 'eq', expected: 'cancelled' }],
+              },
+            ],
+          },
+        ],
+      };
+
+      await runTestProgram(program, { onScenarioComplete });
+
+      expect(onScenarioComplete).toHaveBeenCalledTimes(2);
+    });
+
+    it('abort signal stops execution', async () => {
+      const controller = new AbortController();
+      const onScenarioComplete = vi.fn();
+
+      // Abort after first scenario
+      onScenarioComplete.mockImplementation(() => {
+        controller.abort();
+      });
+
+      const program: TestProgram = {
+        name: 'Abort test',
+        definitionSlug: 'pm-task',
+        definitions: { 'pm-task': PM_TASK_DEFINITION },
+        scenarios: [
+          {
+            name: 'First',
+            steps: [
+              {
+                name: 'Start',
+                action: { type: 'transition', name: 'start' },
+                assertions: [{ target: 'state', operator: 'eq', expected: 'in_progress' }],
+              },
+            ],
+          },
+          {
+            name: 'Second (should be skipped)',
+            steps: [
+              {
+                name: 'Complete',
+                action: { type: 'transition', name: 'start' },
+                assertions: [{ target: 'state', operator: 'eq', expected: 'in_progress' }],
+              },
+            ],
+          },
+        ],
+      };
+
+      const result = await runTestProgram(program, {
+        abortSignal: controller.signal,
+        onScenarioComplete,
+      });
+
+      // Only first scenario should have run
+      expect(result.scenarioResults).toHaveLength(1);
+    });
+  });
+
+  describe('Error handling', () => {
+    it('reports missing definition error', async () => {
+      const scenario: TestScenario = {
+        name: 'Missing def',
+        instances: [{ id: 'x', definitionSlug: 'nonexistent' }],
+        steps: [],
+      };
+
+      const result = await runScenario(scenario, {});
+      expect(result.passed).toBe(false);
+      expect(result.error).toContain('nonexistent');
+    });
+
+    it('reports transition failure as step error', async () => {
+      const program: TestProgram = {
+        name: 'Bad transition',
+        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 runTestProgram(program);
+      expect(result.passed).toBe(false);
+      expect(result.scenarioResults[0].stepResults[0].error).toContain('not valid');
+    });
+  });
+});