elsabro 7.0.1 → 7.2.0

package/flow-engine/tests/runner.test.js

@@ -229,6 +229,463 @@ describe('serializeContext / deserializeContext', () => {
   });
 });
 
+// ---------- Failure mode flow definitions ----------
+
+const flowWithOnError = {
+  id: 'onerror_flow',
+  version: '1.0.0',
+  config: {},
+  nodes: [
+    { id: 'start', type: 'entry', runtime_status: 'implemented', next: 'risky_agent' },
+    {
+      id: 'risky_agent',
+      type: 'agent',
+      runtime_status: 'implemented',
+      agent: 'test-agent',
+      inputs: {},
+      onError: 'error_exit',
+      next: 'success_exit'
+    },
+    {
+      id: 'success_exit',
+      type: 'exit',
+      runtime_status: 'implemented',
+      status: 'success',
+      outputs: { result: 'ok' }
+    },
+    {
+      id: 'error_exit',
+      type: 'exit',
+      runtime_status: 'implemented',
+      status: 'cancelled',
+      outputs: { result: 'handled_error' }
+    }
+  ]
+};
+
+const flowWithoutOnError = {
+  id: 'no_onerror_flow',
+  version: '1.0.0',
+  config: {},
+  nodes: [
+    { id: 'start', type: 'entry', runtime_status: 'implemented', next: 'risky_agent' },
+    {
+      id: 'risky_agent',
+      type: 'agent',
+      runtime_status: 'implemented',
+      agent: 'test-agent',
+      inputs: {},
+      next: 'end'
+    },
+    { id: 'end', type: 'exit', runtime_status: 'implemented', status: 'success', outputs: {} }
+  ]
+};
+
+const flowWithLoop = {
+  id: 'loop_flow',
+  version: '1.0.0',
+  config: {},
+  nodes: [
+    { id: 'start', type: 'entry', runtime_status: 'implemented', next: 'loop_node' },
+    {
+      id: 'loop_node',
+      type: 'condition',
+      runtime_status: 'implemented',
+      condition: '{{inputs.always_true}}',
+      true: 'loop_node',
+      false: 'end'
+    },
+    { id: 'end', type: 'exit', runtime_status: 'implemented', status: 'success', outputs: {} }
+  ]
+};
+
+const flowWithParallel = {
+  id: 'parallel_flow',
+  version: '1.0.0',
+  config: {},
+  nodes: [
+    { id: 'start', type: 'entry', runtime_status: 'implemented', next: 'par' },
+    {
+      id: 'par',
+      type: 'parallel',
+      runtime_status: 'implemented',
+      branches: [
+        { id: 'b1', agent: 'agent-a', inputs: {} },
+        { id: 'b2', agent: 'agent-b', inputs: {} }
+      ],
+      timeout: 5000,
+      next: 'end'
+    },
+    { id: 'end', type: 'exit', runtime_status: 'implemented', status: 'success', outputs: {} }
+  ]
+};
+
+const flowWithParallelOnError = {
+  id: 'parallel_onerror_flow',
+  version: '1.0.0',
+  config: {},
+  nodes: [
+    { id: 'start', type: 'entry', runtime_status: 'implemented', next: 'par' },
+    {
+      id: 'par',
+      type: 'parallel',
+      runtime_status: 'implemented',
+      branches: [
+        { id: 'b1', agent: 'agent-a', inputs: {} }
+      ],
+      onError: 'error_exit',
+      next: 'end'
+    },
+    { id: 'end', type: 'exit', runtime_status: 'implemented', status: 'success', outputs: {} },
+    {
+      id: 'error_exit',
+      type: 'exit',
+      runtime_status: 'implemented',
+      status: 'cancelled',
+      outputs: { result: 'parallel_error_handled' }
+    }
+  ]
+};
+
+const flowWithMaxIterations = {
+  id: 'maxiter_flow',
+  version: '1.0.0',
+  config: {},
+  nodes: [
+    { id: 'start', type: 'entry', runtime_status: 'implemented', next: 'par' },
+    {
+      id: 'par',
+      type: 'parallel',
+      runtime_status: 'implemented',
+      branches: [{ id: 'b1', agent: 'agent-a', inputs: {} }],
+      maxIterations: 1,
+      next: 'end'
+    },
+    { id: 'end', type: 'exit', runtime_status: 'implemented', status: 'success', outputs: {} }
+  ]
+};
+
+const flowWithMaxIterationsHandler = {
+  id: 'maxiter_handler_flow',
+  version: '1.0.0',
+  config: {},
+  nodes: [
+    { id: 'start', type: 'entry', runtime_status: 'implemented', next: 'par' },
+    {
+      id: 'par',
+      type: 'parallel',
+      runtime_status: 'implemented',
+      branches: [{ id: 'b1', agent: 'agent-a', inputs: {} }],
+      maxIterations: 1,
+      onMaxIterations: 'limit_exit',
+      next: 'end'
+    },
+    { id: 'end', type: 'exit', runtime_status: 'implemented', status: 'success', outputs: {} },
+    {
+      id: 'limit_exit',
+      type: 'exit',
+      runtime_status: 'implemented',
+      status: 'cancelled',
+      outputs: { result: 'max_iterations_reached' }
+    }
+  ]
+};
+
+// Note: flowWithBadRef not needed — loadFlow validates references at load time.
+// The runner's node-not-found path (L66-69) is tested via graph mutation after load.
+
+// ---------- Failure mode tests ----------
+
+describe('Failure modes — onError routing', () => {
+  it('routes to onError node when executor throws', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithOnError);
+
+    const result = await engine.run({}, {
+      onAgent: async () => { throw new Error('agent exploded'); }
+    });
+
+    assert.equal(result.success, false);
+    assert.equal(result.outputs.result, 'handled_error');
+    assert.ok(result.nodesVisited.includes('error_exit'));
+    assert.ok(!result.nodesVisited.includes('success_exit'));
+  });
+
+  it('stores error message in outputs when using onError', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithOnError);
+
+    const result = await engine.run({}, {
+      onAgent: async () => { throw new Error('kaboom'); }
+    });
+
+    // The risky_agent node should have error info in its outputs
+    assert.equal(result.context.nodes.risky_agent.outputs.error, 'kaboom');
+  });
+
+  it('propagates error when node has no onError', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithoutOnError);
+
+    await assert.rejects(
+      engine.run({}, {
+        onAgent: async () => { throw new Error('unhandled boom'); }
+      }),
+      (err) => {
+        assert.equal(err.message, 'unhandled boom');
+        return true;
+      }
+    );
+  });
+
+  it('saves checkpoint before onError redirect', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithOnError);
+
+    const checkpoints = [];
+    await engine.run({}, {
+      onAgent: async () => { throw new Error('checkpoint test'); },
+      onCheckpoint: async (data) => checkpoints.push(data)
+    });
+
+    // Find checkpoint for risky_agent → should point to error_exit
+    const agentCheckpoint = checkpoints.find(cp => cp.currentNode === 'risky_agent');
+    assert.ok(agentCheckpoint, 'checkpoint for risky_agent should exist');
+    assert.equal(agentCheckpoint.nextNode, 'error_exit');
+  });
+});
+
+describe('Failure modes — maxNodes loop guard', () => {
+  it('throws RunnerError when exceeding 200 node traversals', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithLoop);
+
+    await assert.rejects(
+      engine.run({ always_true: true }, {}),
+      (err) => {
+        assert.equal(err.name, 'RunnerError');
+        assert.ok(err.message.includes('200'));
+        assert.ok(err.message.includes('infinite loop'));
+        return true;
+      }
+    );
+  });
+
+  it('RunnerError includes current node id', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithLoop);
+
+    await assert.rejects(
+      engine.run({ always_true: true }, {}),
+      (err) => {
+        assert.equal(err.nodeId, 'loop_node');
+        return true;
+      }
+    );
+  });
+
+  it('checkpoints are saved during loop before guard triggers', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithLoop);
+
+    const checkpoints = [];
+    await assert.rejects(
+      engine.run({ always_true: true }, {
+        onCheckpoint: async (data) => checkpoints.push(data)
+      })
+    );
+
+    // entry (1) + 199 loop iterations before guard fires on 201st attempt = 200 checkpoints
+    assert.ok(checkpoints.length >= 200, `expected >= 200 checkpoints, got ${checkpoints.length}`);
+  });
+});
+
+describe('Failure modes — parallel callback failures', () => {
+  it('parallel node with onError routes there when onParallel rejects', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithParallelOnError);
+
+    const result = await engine.run({}, {
+      onParallel: async () => { throw new Error('parallel failed'); }
+    });
+
+    assert.equal(result.success, false);
+    assert.equal(result.outputs.result, 'parallel_error_handled');
+    assert.ok(result.nodesVisited.includes('error_exit'));
+  });
+
+  it('parallel node without onError propagates callback rejection', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithParallel);
+
+    await assert.rejects(
+      engine.run({}, {
+        onParallel: async () => { throw new Error('unhandled parallel'); }
+      }),
+      (err) => {
+        assert.equal(err.message, 'unhandled parallel');
+        return true;
+      }
+    );
+  });
+
+  it('timeout value is passed to onParallel callback', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithParallel);
+
+    let capturedArgs = null;
+    await engine.run({}, {
+      onParallel: async (args) => {
+        capturedArgs = args;
+        return [{ id: 'b1', result: 'ok' }, { id: 'b2', result: 'ok' }];
+      }
+    });
+
+    assert.ok(capturedArgs, 'onParallel should have been called');
+    assert.equal(capturedArgs.timeout, 5000);
+    assert.equal(capturedArgs.nodeId, 'par');
+    assert.equal(capturedArgs.joinType, 'all');
+  });
+
+  it('parallel node handles missing onParallel gracefully', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithParallel);
+
+    // No onParallel callback provided
+    const result = await engine.run({}, {});
+
+    assert.equal(result.success, true);
+    // Branches should be marked as skipped
+    const parOutputs = result.context.nodes.par.outputs;
+    assert.ok(parOutputs.branches, 'branches should exist in outputs');
+    assert.equal(parOutputs.branches.b1.skipped, true);
+    assert.equal(parOutputs.branches.b2.skipped, true);
+  });
+});
+
+describe('Failure modes — context serialization', () => {
+  it('serializeContext handles circular references gracefully', () => {
+    const ctx = {
+      inputs: { task: 'test' },
+      nodes: {},
+      steps: {},
+      state: {},
+      _iterations: {}
+    };
+    // Create a circular reference
+    ctx.state.self = ctx.state;
+
+    const serialized = serializeContext(ctx);
+
+    // state should be null due to circular ref
+    assert.equal(serialized.state, null);
+    // Other keys should still be fine
+    assert.deepEqual(serialized.inputs, { task: 'test' });
+    assert.deepEqual(serialized.nodes, {});
+  });
+
+  it('serializeContext preserves all standard keys', () => {
+    const ctx = {
+      inputs: { a: 1 },
+      nodes: { n1: { outputs: { x: 2 } } },
+      steps: { s1: { output: 'data' } },
+      state: { flag: true },
+      _iterations: { n1: 3 }
+    };
+
+    const serialized = serializeContext(ctx);
+
+    assert.deepEqual(serialized.inputs, ctx.inputs);
+    assert.deepEqual(serialized.nodes, ctx.nodes);
+    assert.deepEqual(serialized.steps, ctx.steps);
+    assert.deepEqual(serialized.state, ctx.state);
+    assert.deepEqual(serialized._iterations, ctx._iterations);
+  });
+
+  it('serializeContext ignores unknown keys', () => {
+    const ctx = {
+      inputs: {},
+      nodes: {},
+      steps: {},
+      state: {},
+      _iterations: {},
+      extraField: 'should be ignored',
+      _internal: { secret: true }
+    };
+
+    const serialized = serializeContext(ctx);
+
+    assert.equal(serialized.extraField, undefined);
+    assert.equal(serialized._internal, undefined);
+    assert.ok('inputs' in serialized);
+  });
+});
+
+describe('Failure modes — maxIterations fallback', () => {
+  it('parallel node falls through to next when maxIterations reached without handler', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithMaxIterations);
+
+    const result = await engine.run({}, {
+      onParallel: async () => [{ id: 'b1', result: 'done' }]
+    });
+
+    // Should reach 'end' via node.next even though maxIterations=1 was hit
+    assert.equal(result.success, true);
+    assert.ok(result.nodesVisited.includes('end'));
+    assert.ok(!result.nodesVisited.includes('limit_exit'));
+  });
+
+  it('parallel node routes to onMaxIterations when handler defined', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(flowWithMaxIterationsHandler);
+
+    const result = await engine.run({}, {
+      onParallel: async () => [{ id: 'b1', result: 'done' }]
+    });
+
+    // Should route to limit_exit via onMaxIterations
+    assert.equal(result.success, false); // limit_exit is cancelled status
+    assert.equal(result.outputs.result, 'max_iterations_reached');
+    assert.ok(result.nodesVisited.includes('limit_exit'));
+  });
+});
+
+describe('Failure modes — runner edge cases', () => {
+  it('RunnerError thrown for node not found in graph at runtime', async () => {
+    const engine = new FlowEngine();
+    engine.loadFlow(miniFlow);
+
+    // Mutate graph after loading: point entry to a non-existent node
+    const startNode = engine.graph.nodes.get('start');
+    startNode.next = 'ghost_node';
+
+    await assert.rejects(
+      engine.run({ task: 'test', go: true }, {}),
+      (err) => {
+        assert.equal(err.name, 'RunnerError');
+        assert.ok(err.message.includes('ghost_node'));
+        assert.ok(err.message.includes('not found'));
+        return true;
+      }
+    );
+  });
+
+  it('RunnerError thrown when no flow loaded', async () => {
+    const engine = new FlowEngine();
+    // Do NOT call loadFlow
+
+    await assert.rejects(
+      engine.run({}, {}),
+      (err) => {
+        assert.equal(err.name, 'RunnerError');
+        assert.ok(err.message.includes('loadFlow'));
+        return true;
+      }
+    );
+  });
+});
+
 describe('CheckpointManager', () => {
   const tmpDir = path.join(os.tmpdir(), `elsabro-test-cp-${Date.now()}`);