@mmapp/player-core 0.1.0-alpha.1

package/src/testing/graph-walker.ts

@@ -0,0 +1,249 @@
+/**
+ * Graph Walker — static analysis of workflow definitions.
+ *
+ * Treats a PlayerWorkflowDefinition as a directed graph and provides:
+ * - analyzeDefinition(): Full graph analysis (states, edges, paths, cycles)
+ * - generateCoverageScenarios(): Auto-generate test scenarios from paths
+ *
+ * Pure functions, zero dependencies beyond player-core types.
+ */
+
+import type { PlayerWorkflowDefinition } from '../state-machine/types';
+import type {
+  AnalysisResult,
+  StateNode,
+  TransitionEdge,
+  GraphPath,
+  TestScenario,
+  TestStep,
+} from './types';
+
+const MAX_PATHS = 1000;
+
+/**
+ * Analyze a workflow definition as a directed graph.
+ * Returns all states, edges, terminal paths, cycles, unreachable/dead-end states.
+ */
+export function analyzeDefinition(def: PlayerWorkflowDefinition): AnalysisResult {
+  // Build state nodes
+  const states: StateNode[] = def.states.map(s => ({
+    name: s.name,
+    type: s.type,
+    reachable: false, // Will be set during DFS
+    hasOnEvent: Boolean(s.on_event?.length),
+    hasOnEnter: Boolean(s.on_enter?.length),
+    hasOnExit: Boolean(s.on_exit?.length),
+  }));
+
+  // Build edges (expand multi-from transitions)
+  const edges: TransitionEdge[] = [];
+  for (const t of def.transitions) {
+    for (const from of t.from) {
+      edges.push({
+        name: t.name,
+        from,
+        to: t.to,
+        auto: Boolean(t.auto),
+        hasConditions: Boolean(t.conditions?.length),
+      });
+    }
+  }
+
+  // Build adjacency list
+  const adjacency = new Map<string, TransitionEdge[]>();
+  for (const s of def.states) {
+    adjacency.set(s.name, []);
+  }
+  for (const e of edges) {
+    adjacency.get(e.from)?.push(e);
+  }
+
+  // Find start state
+  const startState = def.states.find(s => s.type === 'START');
+  if (!startState) {
+    return {
+      states,
+      edges,
+      terminalPaths: [],
+      cycles: [],
+      unreachableStates: states.map(s => s.name),
+      deadEndStates: [],
+      summary: {
+        totalStates: states.length,
+        totalTransitions: edges.length,
+        reachableStates: 0,
+        terminalPaths: 0,
+        cycles: 0,
+        unreachableStates: states.length,
+        deadEndStates: 0,
+      },
+    };
+  }
+
+  // Terminal state names
+  const terminalStates = new Set(
+    def.states.filter(s => s.type === 'END' || s.type === 'CANCELLED').map(s => s.name),
+  );
+
+  // DFS to find all paths and cycles
+  const terminalPaths: GraphPath[] = [];
+  const cycles: GraphPath[] = [];
+  const visited = new Set<string>();
+
+  function dfs(
+    state: string,
+    pathStates: string[],
+    pathTransitions: string[],
+    pathSet: Set<string>,
+  ): void {
+    if (terminalPaths.length + cycles.length >= MAX_PATHS) return;
+
+    // Mark as reachable
+    const stateNode = states.find(s => s.name === state);
+    if (stateNode) stateNode.reachable = true;
+    visited.add(state);
+
+    // Terminal state → record path (but still check outgoing edges for cycles)
+    const isTerminal = terminalStates.has(state);
+    if (isTerminal) {
+      terminalPaths.push({
+        states: [...pathStates],
+        transitions: [...pathTransitions],
+      });
+    }
+
+    const outEdges = adjacency.get(state) ?? [];
+
+    for (const edge of outEdges) {
+      if (terminalPaths.length + cycles.length >= MAX_PATHS) return;
+
+      if (pathSet.has(edge.to)) {
+        // Cycle detected
+        const cycleStart = pathStates.indexOf(edge.to);
+        cycles.push({
+          states: [...pathStates.slice(cycleStart), edge.to],
+          transitions: [...pathTransitions.slice(cycleStart), edge.name],
+        });
+        continue;
+      }
+
+      pathStates.push(edge.to);
+      pathTransitions.push(edge.name);
+      pathSet.add(edge.to);
+
+      dfs(edge.to, pathStates, pathTransitions, pathSet);
+
+      pathStates.pop();
+      pathTransitions.pop();
+      pathSet.delete(edge.to);
+    }
+  }
+
+  dfs(startState.name, [startState.name], [], new Set([startState.name]));
+
+  // Identify unreachable states
+  const unreachableStates = states
+    .filter(s => !s.reachable)
+    .map(s => s.name);
+
+  // Identify dead-end states: non-terminal, reachable, with no outgoing transitions
+  const deadEndStates = states
+    .filter(s => {
+      if (!s.reachable) return false;
+      if (terminalStates.has(s.name)) return false;
+      const outEdges = adjacency.get(s.name) ?? [];
+      return outEdges.length === 0;
+    })
+    .map(s => s.name);
+
+  // Deduplicate cycles by string key
+  const uniqueCycles: GraphPath[] = [];
+  const seenCycleKeys = new Set<string>();
+  for (const cycle of cycles) {
+    const key = cycle.states.join('→');
+    if (!seenCycleKeys.has(key)) {
+      seenCycleKeys.add(key);
+      uniqueCycles.push(cycle);
+    }
+  }
+
+  return {
+    states,
+    edges,
+    terminalPaths,
+    cycles: uniqueCycles,
+    unreachableStates,
+    deadEndStates,
+    summary: {
+      totalStates: states.length,
+      totalTransitions: edges.length,
+      reachableStates: states.filter(s => s.reachable).length,
+      terminalPaths: terminalPaths.length,
+      cycles: uniqueCycles.length,
+      unreachableStates: unreachableStates.length,
+      deadEndStates: deadEndStates.length,
+    },
+  };
+}
+
+/**
+ * Generate one test scenario per terminal path in the definition.
+ * Each step = one transition, asserting the landing state.
+ */
+export function generateCoverageScenarios(
+  def: PlayerWorkflowDefinition,
+  analysis?: AnalysisResult,
+): TestScenario[] {
+  const resolved = analysis ?? analyzeDefinition(def);
+  const scenarios: TestScenario[] = [];
+
+  for (const path of resolved.terminalPaths) {
+    const pathLabel = path.states.join(' → ');
+    const steps: TestStep[] = [];
+
+    for (let i = 0; i < path.transitions.length; i++) {
+      const transitionName = path.transitions[i];
+      const expectedState = path.states[i + 1];
+
+      // Check if this is a terminal state
+      const stateDef = def.states.find(s => s.name === expectedState);
+      const isTerminal = stateDef?.type === 'END' || stateDef?.type === 'CANCELLED';
+      const expectedStatus = stateDef?.type === 'END'
+        ? 'COMPLETED'
+        : stateDef?.type === 'CANCELLED'
+          ? 'CANCELLED'
+          : 'ACTIVE';
+
+      steps.push({
+        name: `${transitionName} → ${expectedState}`,
+        action: { type: 'transition', name: transitionName },
+        assertions: [
+          {
+            target: 'state',
+            operator: 'eq',
+            expected: expectedState,
+            label: `State should be "${expectedState}"`,
+          },
+          ...(isTerminal
+            ? [
+                {
+                  target: 'status' as const,
+                  operator: 'eq' as const,
+                  expected: expectedStatus,
+                  label: `Status should be "${expectedStatus}"`,
+                },
+              ]
+            : []),
+        ],
+      });
+    }
+
+    scenarios.push({
+      name: `Path: ${pathLabel}`,
+      tags: ['auto-generated', 'coverage'],
+      steps,
+    });
+  }
+
+  return scenarios;
+}

package/src/testing/index.ts

@@ -0,0 +1,69 @@
+/**
+ * Testing OS — test declarations and execution for player-core.
+ *
+ * Three layers:
+ * 1. Graph walker: static analysis + coverage generation
+ * 2. In-process runner: direct StateMachine execution (legacy, still works)
+ * 3. Blueprint runner: test IS a Blueprint, runs on any Player
+ *    - Compiler: TestProgram → PlayerWorkflowDefinition
+ *    - Action handlers: pluggable (in-process, API, cross-platform)
+ *    - Runner: thin executor that drives the Player
+ */
+
+// Types
+export type {
+  // Static analysis
+  StateNode,
+  TransitionEdge,
+  GraphPath,
+  AnalysisSummary,
+  AnalysisResult,
+  // Test program
+  TestProgram,
+  TestInstance,
+  TestScenario,
+  TestStep,
+  TestAssertion,
+  // Results
+  AssertionResult,
+  StepResult,
+  ScenarioResult,
+  TestProgramResult,
+  // In-process config
+  TestRunnerConfig,
+  // API adapter + config
+  ApiTestAdapter,
+  ApiTestRunnerConfig,
+  ApiInstanceSnapshot,
+  ApiTransitionResult,
+} from './types';
+
+// Graph walker
+export { analyzeDefinition, generateCoverageScenarios } from './graph-walker';
+
+// In-process runner (direct StateMachine, no Blueprint compilation)
+export { runTestProgram, runScenario } from './test-runner';
+
+// Blueprint runner (test IS a Blueprint, runs on any Player)
+export { compileTestScenario, compileTestProgram } from './test-compiler';
+export { createInProcessTestActions, createApiTestActions } from './test-actions';
+export type { TestActionState } from './test-actions';
+export { runBlueprintTestProgram, runBlueprintScenario } from './blueprint-test-runner';
+export type { BlueprintRunnerConfig } from './blueprint-test-runner';
+
+// NRT (Normalized Render Trace)
+export type {
+  NRT,
+  NRTNode,
+  NRTEvent,
+  NRTEventTarget,
+  NRTNavState,
+  NRTDiff,
+  NRTChange,
+} from './nrt-types';
+export { createEmptyNRT, findNode, findVisibleNodes, findInteractiveNodes, countNodes } from './nrt-types';
+export { compareNRT } from './nrt-comparator';
+
+// Action Trace
+export type { ActionTrace, ActionTick, ActionRecorder } from './action-trace';
+export { createActionRecorder, getTransitionPath, getFinalState, countByKind, hasTransition } from './action-trace';

package/src/testing/nrt-comparator.ts

@@ -0,0 +1,199 @@
+/**
+ * NRT Comparator — semantic diff between two NRT snapshots.
+ *
+ * Compares structure, text, visibility, and events while ignoring
+ * platform-specific details like classNames, styles, and layout metrics.
+ *
+ * Usage:
+ *   const diff = compareNRT(before, after);
+ *   if (!diff.equal) {
+ *     console.log('Changes:', diff.changes);
+ *   }
+ */
+
+import type { NRT, NRTNode, NRTDiff, NRTChange } from './nrt-types';
+
+// =============================================================================
+// Comparison
+// =============================================================================
+
+/**
+ * Compares two NRT snapshots and returns a semantic diff.
+ */
+export function compareNRT(before: NRT, after: NRT): NRTDiff {
+  const changes: NRTChange[] = [];
+
+  // Compare workflow state
+  if (before.workflowState !== after.workflowState) {
+    changes.push({
+      type: 'modified',
+      path: 'workflowState',
+      field: 'workflowState',
+      oldValue: before.workflowState,
+      newValue: after.workflowState,
+    });
+  }
+
+  // Compare navigation state
+  if (before.nav?.routeState !== after.nav?.routeState) {
+    changes.push({
+      type: 'modified',
+      path: 'nav.routeState',
+      field: 'routeState',
+      oldValue: before.nav?.routeState,
+      newValue: after.nav?.routeState,
+    });
+  }
+
+  // Compare node trees
+  compareNodes(before.root, after.root, 'root', changes);
+
+  return {
+    equal: changes.length === 0,
+    changes,
+  };
+}
+
+/**
+ * Recursively compares two NRT nodes.
+ */
+function compareNodes(
+  before: NRTNode | undefined,
+  after: NRTNode | undefined,
+  path: string,
+  changes: NRTChange[]
+): void {
+  // Node added
+  if (!before && after) {
+    changes.push({
+      type: 'added',
+      path,
+      nodeId: after.id,
+      field: 'node',
+      newValue: summarizeNode(after),
+    });
+    return;
+  }
+
+  // Node removed
+  if (before && !after) {
+    changes.push({
+      type: 'removed',
+      path,
+      nodeId: before.id,
+      field: 'node',
+      oldValue: summarizeNode(before),
+    });
+    return;
+  }
+
+  if (!before || !after) return;
+
+  // Compare semantic fields (ignore platform-specific details)
+  if (before.type !== after.type) {
+    changes.push({
+      type: 'modified',
+      path,
+      nodeId: after.id,
+      field: 'type',
+      oldValue: before.type,
+      newValue: after.type,
+    });
+  }
+
+  if (before.text !== after.text) {
+    changes.push({
+      type: 'modified',
+      path,
+      nodeId: after.id,
+      field: 'text',
+      oldValue: before.text,
+      newValue: after.text,
+    });
+  }
+
+  if (before.visible !== after.visible) {
+    changes.push({
+      type: 'modified',
+      path,
+      nodeId: after.id,
+      field: 'visible',
+      oldValue: before.visible,
+      newValue: after.visible,
+    });
+  }
+
+  if (before.enabled !== after.enabled) {
+    changes.push({
+      type: 'modified',
+      path,
+      nodeId: after.id,
+      field: 'enabled',
+      oldValue: before.enabled,
+      newValue: after.enabled,
+    });
+  }
+
+  if (JSON.stringify(before.value) !== JSON.stringify(after.value)) {
+    changes.push({
+      type: 'modified',
+      path,
+      nodeId: after.id,
+      field: 'value',
+      oldValue: before.value,
+      newValue: after.value,
+    });
+  }
+
+  // Compare events
+  const beforeEvents = Object.keys(before.events || {});
+  const afterEvents = Object.keys(after.events || {});
+
+  for (const event of afterEvents) {
+    if (!beforeEvents.includes(event)) {
+      changes.push({
+        type: 'added',
+        path: `${path}.events`,
+        nodeId: after.id,
+        field: event,
+        newValue: after.events![event],
+      });
+    }
+  }
+
+  for (const event of beforeEvents) {
+    if (!afterEvents.includes(event)) {
+      changes.push({
+        type: 'removed',
+        path: `${path}.events`,
+        nodeId: before.id,
+        field: event,
+        oldValue: before.events![event],
+      });
+    }
+  }
+
+  // Compare children
+  const maxChildren = Math.max(before.children.length, after.children.length);
+  for (let i = 0; i < maxChildren; i++) {
+    compareNodes(
+      before.children[i],
+      after.children[i],
+      `${path}.children[${i}]`,
+      changes
+    );
+  }
+}
+
+/**
+ * Creates a brief summary of a node for diff output.
+ */
+function summarizeNode(node: NRTNode): Record<string, unknown> {
+  return {
+    id: node.id,
+    type: node.type,
+    text: node.text,
+    visible: node.visible,
+    childCount: node.children.length,
+  };
+}