FAQ¶

Common questions about the generic BDD framework architecture.

1. Why separate Steps from Orchestrators?¶

Steps express intent only (Given/When/Then) and remain thin. Orchestrators own lifecycle logic (submit → poll → finalize), keeping workflow control reusable and testable.

2. How do Commands differ from Executors?¶

Commands are declarative payloads describing what to do. Executors implement how to perform the action (local vs remote). This decoupling allows new execution strategies without changing higher layers.

3. Why use a ParserFactory?¶

Raw outputs vary (JSON, text, logs). A lightweight factory selects the correct parser and returns a typed model. This keeps Services clean and avoids scattering parsing logic across the codebase.

4. Can I call an Executor directly from a Step?¶

Avoid it. Direct calls leak execution details into test intent. Use Service (for command building) + Orchestrator (for lifecycle) to preserve abstraction boundaries.

5. How is remote vs local execution selected?¶

Configuration picks the Executor implementation (Local, Remote/SSM, Container-based, etc.). Services interact only with a simple run(command) interface—execution strategy remains interchangeable.

6. How do I add a new workflow type?¶

Implement a new Orchestrator or compose existing ones. Reuse Services and Executors; keep Step changes minimal (new Given/When/Then mapping).

7. What ensures parallel safety?¶

Stateless Services, immutable Commands, and Executors that avoid shared state. Use unique workflow identifiers and isolated fixtures to prevent cross‑test interference.

8. How do retries and timeouts fit in?¶

They belong in Orchestrators (policy layer). Keep Executors simple: single attempt execution returning raw output.

9. Why prefer pseudocode and Mermaid diagrams here?¶

Because this repository documents the architecture rather than a production framework. Diagrams communicate flow; pseudocode expresses structure without tying the design to any specific platform or vendor.

10. How should failures be represented?¶

Parsers turn raw output into a structured WorkflowResponse containing status, errors, and evidence. Tests assert against typed fields rather than brittle text matching.

11. How do I version architecture changes?¶

Use semantic versioning concepts (documented in README) even for design evolution: mark breaking conceptual changes clearly.

12. How do I extend parsing?¶

Provide a new parser and register it with the factory using a command type or output signature. Maintain deterministic rules so all command outputs resolve to a predictable typed model.

Have a question not covered here? Propose an addition via pull request following the docs style template.