pytestflow 0.2.0__py3-none-any.whl

pytestflow/core/sequence.py

@@ -0,0 +1,404 @@
+from datetime import datetime
+import uuid
+from prefect import flow
+from typing import Any, Callable, List, Iterable
+from pytestflow.core.pytestflow_states import (
+    PyTestflowPassed, PyTestflowFailed, PyTestflowDone, PyTestflowError, PyTestflowState
+)
+from pytestflow.core.context import ptf_context
+import inspect
+
+from pytestflow.core.utils import get_data_for_gui
+from pytestflow.core.runtime_control import runtime_control
+
+
+class Sequence:
+    def __init__(
+        self,
+        name: str,
+        steps: List[Callable] = None,
+        default_parameters: dict = None,
+        allow_parent_mutation: bool = False,
+        apply_throttle: bool = True,
+    ):
+        self.name = name
+        self.steps = steps or []
+        self.allow_parent_mutation = allow_parent_mutation
+        self.apply_throttle = apply_throttle
+        self.results: List[tuple[str, PyTestflowState]] = []
+        self._locals_stack: List[dict] = []  # Stack to manage ptf_context.locals
+        self.default_parameters = default_parameters or {}
+        self.max_transitions = 10_000
+
+    def _is_passed(self, state: PyTestflowState) -> bool:
+        return isinstance(state, (PyTestflowPassed, PyTestflowDone))
+
+    def add_step(self, fn: Callable, position: int = None):
+        if position is None:
+            self.steps.append(fn)
+        else:
+            self.steps.insert(position, fn)
+
+    def remove_step(self, name_or_fn):
+        name = name_or_fn if isinstance(name_or_fn, str) else name_or_fn.__name__
+        self.steps = [s for s in self.steps if getattr(s, '__name__', '') != name]
+
+    def force_step_status(self, step_name: str, status: str):
+        def forced():
+            match status.lower():
+                case "passed":
+                    return PyTestflowPassed(ptf_result={"step_status": "forced_pass"}, message=f"{step_name} forced pass")
+                case "failed":
+                    return PyTestflowFailed(ptf_result={"step_status": "forced_fail"}, message=f"{step_name} forced fail")
+                case "done" | "skipped":
+                    return PyTestflowDone(ptf_result={"step_status": f"{status.lower()}"}, message=f"{step_name} {status.lower()}")
+                case _:
+                    raise ValueError(f"Unsupported status: {status}")
+        forced.__name__ = step_name + "_forced"
+        self.add_step(forced)
+
+    def _exec_step(self, step_fn: Callable) -> tuple[str, PyTestflowState]:
+        step_name = getattr(step_fn, "name", getattr(step_fn, "__name__", repr(step_fn)))
+        print(f"➡️ Executing step: {step_name}")
+
+        if inspect.iscoroutinefunction(step_fn):
+            raise TypeError("Async step functions are not supported in this base Sequence class.")
+
+        # Check if the step is a Sequence
+        if isinstance(step_fn, Sequence):
+            # Push current locals onto the stack
+            # Snapshot caller state
+            caller_snapshot = ptf_context.locals.copy()
+            self._locals_stack.append(caller_snapshot)
+            
+            #initialize called sequence context
+            ptf_context.locals.clear()  # Clear locals for the subsequence
+            
+            if step_fn.allow_parent_mutation:
+                # Live pointer to caller's local space
+                ptf_context.locals["__caller__"] = caller_snapshot
+            else:
+                # Read-only wrapper around a disposable copy
+                class ReadOnlyDict(dict):
+                    def __setitem__(self, k, v): raise RuntimeError("Caller context is read-only")
+                    def update(self, *a, **kw): raise RuntimeError("Caller context is read-only")
+                
+                ptf_context.locals["__caller__"] = ReadOnlyDict(caller_snapshot.copy()) # disposable copy
+            
+            try:
+                # Run the subsequence
+                state = step_fn.run(return_state=True)  # returns PyTestflowState
+                #step_name = state.ptf_result['step_name']
+            finally:
+                # Restore parent locals
+                ptf_context.locals = self._locals_stack.pop()
+        
+        else:
+            # Execute a regular step
+            try:
+                state = step_fn()
+                #step_name = state.ptf_result['step_name']
+            except Exception as exc:
+                print(f"💥 Step {step_name} raised an exception: {exc}")
+                state = PyTestflowError(ptf_result={"step_status": "error", "error": str(exc)}, message=str(exc)) 
+
+        return step_name, state
+
+    def _get_step_name(self, step_fn: Callable) -> str:
+        return getattr(step_fn, "name", getattr(step_fn, "__name__", repr(step_fn)))
+
+    def _read_next_step_directive(self) -> Any:
+        return ptf_context.locals.pop("_ptf_next_step", "next")
+
+    def _resolve_next_index(
+        self,
+        *,
+        directive: Any,
+        current_index: int,
+        step_name_to_index: dict[str, int],
+        step_count: int,
+    ) -> tuple[int, str | None]:
+        if directive is None:
+            return current_index + 1, None
+
+        if isinstance(directive, str):
+            token = directive.strip()
+            token_lower = token.lower()
+
+            if token == "" or token_lower == "next":
+                return current_index + 1, None
+            if token_lower in {"end", "stop"}:
+                return step_count, None
+            if token in step_name_to_index:
+                return step_name_to_index[token], None
+
+            return (
+                current_index + 1,
+                f"Invalid _ptf_next_step '{directive}'. Expected 'next', 'end', a valid step name, or an integer index.",
+            )
+
+        if isinstance(directive, int):
+            if 0 <= directive < step_count:
+                return directive, None
+            if directive == step_count:
+                return step_count, None
+            return (
+                current_index + 1,
+                f"Invalid _ptf_next_step index '{directive}'. Expected range [0, {step_count}]",
+            )
+
+        return (
+            current_index + 1,
+            f"Invalid _ptf_next_step type '{type(directive).__name__}'. Expected str or int.",
+        )
+
+    def _flow_control_error_state(self, message: str) -> PyTestflowError:
+        return PyTestflowError(
+            ptf_result={"step_status": "error", "error": message, "step_type": "flow_control"},
+            message=message,
+        )
+
+    def _run_steps_with_flow_control(
+        self,
+        *,
+        steps: List[Callable],
+        runtime_start_index: int = 0,
+    ) -> tuple[List[tuple[str, PyTestflowState]], int]:
+        results: List[tuple[str, PyTestflowState]] = []
+        step_name_to_index = {self._get_step_name(step): idx for idx, step in enumerate(steps)}
+        current_index = 0
+        transitions = 0
+
+        ptf_context.locals.pop("_ptf_next_step", None)
+
+        while 0 <= current_index < len(steps):
+            if transitions >= self.max_transitions:
+                msg = (
+                    f"Sequence '{self.name}' exceeded max transitions ({self.max_transitions}). "
+                    "Possible infinite loop in flow control."
+                )
+                results.append(("__flow_control__", self._flow_control_error_state(msg)))
+                break
+
+            runtime_control.checkpoint_before_step(
+                runtime_start_index + transitions,
+                apply_throttle=self.apply_throttle,
+            )
+            step_fn = steps[current_index]
+            name, state = self._exec_step(step_fn)
+            results.append((name, state))
+            transitions += 1
+
+            directive = self._read_next_step_directive()
+            next_index, error = self._resolve_next_index(
+                directive=directive,
+                current_index=current_index,
+                step_name_to_index=step_name_to_index,
+                step_count=len(steps),
+            )
+            if error:
+                results.append(("__flow_control__", self._flow_control_error_state(error)))
+                break
+
+            current_index = next_index
+
+        return results, runtime_start_index + transitions
+
+    @flow(name="SequenceRun", persist_result=False)
+    def run(self, parameters: dict | None = None) -> PyTestflowState:
+        print(f"\n▶️ Running Sequence: {self.name}")
+        self.results = []
+
+        # Initialize context for this sequence run
+        merged_parameters = {**self.default_parameters, **(parameters or {})}
+        ptf_context.locals.update(merged_parameters)
+        self.results, _ = self._run_steps_with_flow_control(
+            steps=self.steps,
+            runtime_start_index=0,
+        )
+
+        all_passed = all(self._is_passed(s) for _, s in self.results)
+
+        if all_passed:
+            overall = PyTestflowPassed(
+                ptf_result={"step_status": "sequence_passed"},
+                message=f"Sequence {self.name} passed",
+                children=self.results,
+            )
+        else:
+            overall = PyTestflowFailed(
+                ptf_result={"step_status": "sequence_failed"},
+                message=f"Sequence {self.name} failed",
+                children=self.results,
+            )
+
+        print(f"✅ Sequence {self.name} finished with status: {overall.name}")
+        return overall
+
+
+    @flow(name="SequenceRunStep")
+    def run_step(self, names: str | Iterable[str]) -> PyTestflowState:
+        if isinstance(names, str):
+            wanted = {names}
+        else:
+            wanted = set(names)
+
+        print(f"\n▶️ Running Sequence.run_step on {self.name} for: {', '.join(wanted)}")
+        selected = [s for s in self.steps if getattr(s, "__name__", "") in wanted]
+
+        results, _ = self._run_steps_with_flow_control(
+            steps=selected,
+            runtime_start_index=0,
+        )
+
+        all_passed = all(self._is_passed(s) for _, s in results)
+
+        if all_passed:
+            overall = PyTestflowPassed(
+                ptf_result={"step_status": "sequence_partial_passed"},
+                message=f"Sequence {self.name} (partial) passed",
+                children=results,
+            )
+        else:
+            overall = PyTestflowFailed(
+                ptf_result={"step_status": "sequence_partial_failed"},
+                message=f"Sequence {self.name} (partial) failed",
+                children=results,
+            )
+
+        return overall
+
+
+class TestSequence(Sequence):
+    def __init__(
+        self,
+        name: str,        
+        setup_steps: List[Callable] | None = None,
+        main_steps: List[Callable] | None = None,
+        cleanup_steps: List[Callable] | None = None,        
+    ):
+        super().__init__(name=name, steps=[])
+        self.static_uuid: uuid.UUID | None = None
+        self.setup_steps = setup_steps or []
+        self.main_steps = main_steps or []
+        self.cleanup_steps = cleanup_steps or []
+
+    def _run_section(self, label: str, steps: List[Callable], start_index: int = 0) -> tuple[List[tuple[str, PyTestflowState]], int]:
+        print(f"\n🔧 Running {label} for {self.name}")
+        return self._run_steps_with_flow_control(
+            steps=steps,
+            runtime_start_index=start_index,
+        )
+
+    @flow(name="TestSequenceRun")
+    def run(self) -> PyTestflowState:
+        print(f"\n▶️ Running Test Sequence: {self.name}")
+        
+        # Send start to GUI  
+        get_data_for_gui(self, datetime.utcnow())
+
+        all_steps = [*self.setup_steps, *self.main_steps, *self.cleanup_steps]
+        children, _ = self._run_steps_with_flow_control(
+            steps=all_steps,
+            runtime_start_index=0,
+        )
+
+        all_passed = all(self._is_passed(state) for _, state in children)
+
+        if all_passed:
+            overall = PyTestflowPassed(
+                ptf_result={"step_status": "test_sequence_passed"},
+                message=f"Test Sequence {self.name} passed",
+                children=children,
+            )
+        else:
+            overall = PyTestflowFailed(
+                ptf_result={"step_status": "test_sequence_failed"},
+                message=f"Test Sequence {self.name} failed",
+                children=children,
+            )
+
+        # Send end to GUI
+        result_data = {
+            "step_status": "passed" if all_passed else "failed",
+            "step_type": "sub_sequence",
+        }
+        get_data_for_gui(self, datetime.utcnow(), result_data)
+
+        print(f"✅ Test Sequence {self.name} finished with status: {overall.name}")
+        return overall
+
+    @flow(name="TestSequenceRunStep")
+    def run_step(self, names: str | Iterable[str]) -> PyTestflowState:
+        if isinstance(names, str):
+            wanted = {names}
+        else:
+            wanted = set(names)
+
+        print(f"\n▶️ Running TestSequence.run_step on {self.name} for main steps: {', '.join(wanted)}")
+
+        children: List[tuple[str, PyTestflowState]] = []
+        step_index = 0
+
+        setup_res, step_index = self._run_section("setup", self.setup_steps, start_index=step_index)
+        children.extend(setup_res)
+
+        selected_main = [s for s in self.main_steps if getattr(s, "__name__", "") in wanted]
+        main_res, step_index = self._run_section("main (selected)", selected_main, start_index=step_index)
+        children.extend(main_res)
+
+        cleanup_res, step_index = self._run_section("cleanup", self.cleanup_steps, start_index=step_index)
+        children.extend(cleanup_res)
+
+        all_passed = all(self._is_passed(state) for _, state in children)
+
+        if all_passed:
+            overall = PyTestflowPassed(
+                ptf_result={"step_status": "test_sequence_partial_passed"},
+                message=f"Test Sequence {self.name} (selected) passed",
+                children=children,
+            )
+        else:
+            overall = PyTestflowFailed(
+                ptf_result={"step_status": "test_sequence_partial_failed"},
+                message=f"Test Sequence {self.name} (selected) failed",
+                children=children,
+            )
+
+        return overall
+
+    def run_step(self, step_name: str, return_state: bool = False):
+        """
+        Run a specific step in the sequence, including setup and cleanup steps.
+        """
+        from prefect import flow
+
+        # Find the step by name
+        step = next(
+            (s for s in self.setup_steps + self.main_steps + self.cleanup_steps if s.name == step_name),
+            None,
+        )
+        if not step:
+            raise ValueError(f"Step '{step_name}' not found in sequence '{self.name}'.")
+
+        @flow(name=f"Test Sequence {self.name} (selected)")
+        def sequence_flow():
+            steps_to_run = [*self.setup_steps, step, *self.cleanup_steps]
+            results, _ = self._run_steps_with_flow_control(
+                steps=steps_to_run,
+                runtime_start_index=0,
+            )
+            return results
+
+        # Run the flow
+        flow_state = sequence_flow(return_state=return_state)
+
+        # Build the result
+        result_children = [
+            (name, state) for name, state in flow_state.result()
+        ]
+        result = PyTestflowPassed(children=result_children) if all(
+            state.is_completed() for _, state in result_children
+        ) else PyTestflowFailed(children=result_children)
+
+        return result

pytestflow/core/utils.py

@@ -0,0 +1,81 @@
+# # core/utils.py
+from inspect import signature, Parameter
+from pytestflow.core.context import ptf_context
+import json
+from pytestflow.core.runtime_control import runtime_control
+    
+
+def get_data_for_gui(step, timestamp, result=None):
+    overall_step_result = ''
+    status_to_send = 'started'
+    info = ""
+    if result is not None:
+        # means end of step
+        status_to_send = 'finished'
+        overall_step_result = result['step_status']
+        # get info (step type dependant)        
+        step_type = result['step_type']
+        if step_type == 'action':
+            info = json.dumps({"Output": result['output']}, default=str)
+        elif step_type == 'numeric_limit':
+            info = json.dumps({"Output": result['output'], "limit": result['limit'],"mode": result['mode'] }, default=str)
+        if step_type == 'pass_fail':
+            info = json.dumps({"Output": result['output']}, default=str)
+        elif step_type == 'string_check':
+            info = json.dumps({"Output": result['output'],
+                               "expected": result['expected'],
+                               "match": result['match'],
+                               "case_sensitive": result['case_sensitive'] },
+                               default=str)  
+    data_to_send = {
+        "cmd": "update_step_status",
+        "args": {
+            "StepUUID": str(step.static_uuid),
+            "SelectStepOnGUI": True,
+            "Status": status_to_send,
+            "Result": overall_step_result,
+            "Timestamp": timestamp if isinstance(timestamp, str) else timestamp.isoformat(),
+            "Info": info
+        }
+    }
+
+    if step.static_uuid is None:
+        print("**************************************************")
+        print("step name:", step.name)
+        print("**************************************************")
+
+    # Send to FE via runtime_control queue (in-process)
+    runtime_control.send_gui_update(data_to_send)
+
+
+
+def resolve_args(func, explicit_args, explicit_kwargs):
+    """
+    Autowires missing parameters from context by name.
+    If a parameter is 'ctx', injects the context object.
+    """
+    sig = signature(func)
+
+    # Early return for parameter-less functions
+    if len(sig.parameters) == 0:
+        return (), {}
+
+    bound = sig.bind_partial(*explicit_args, **explicit_kwargs)
+
+    for pname, param in sig.parameters.items():
+        # Skip *args and **kwargs
+        if param.kind in (Parameter.VAR_POSITIONAL, Parameter.VAR_KEYWORD):
+            continue
+
+        if pname in bound.arguments:
+            continue
+        if pname == "ctx":
+            bound.arguments[pname] = ptf_context
+        elif pname in ptf_context.locals:
+            bound.arguments[pname] = ptf_context.locals[pname]
+        elif pname in ptf_context.globals:
+            bound.arguments[pname] = ptf_context.globals[pname]
+        else:
+            raise ValueError(f"Could not autowire parameter '{pname}'")
+
+    return bound.args, bound.kwargs

pytestflow/flow_utils/README.md

@@ -0,0 +1,6 @@
+# Flow Utilities
+
+Helper functions for orchestrating complex flows on top of Prefect. These tools
+complement `Sequence` and `ProcessModel` classes by providing branching,
+conditional execution, and data-movement utilities while preserving the
+framework philosophy of ordered Prefect flows executing `Step` tasks.

pytestflow/starter_here.md

@@ -0,0 +1,43 @@
+# Starter Here
+
+## 1) Install (beta)
+
+```bash
+pipx install "git+https://github.com/Alberto-Manzoni/PyTestFlow.git@v0.2.0-beta.1"
+```
+
+Source repositories:
+- Engine: https://github.com/Alberto-Manzoni/PyTestFlow
+- Frontend: https://github.com/Alberto-Manzoni/PyTestFlow-FrontEnd
+
+## 2) Start backend + GUI host
+
+```bash
+pytestflow-am start
+```
+
+Optional (open browser automatically):
+
+```bash
+pytestflow-am start --open
+```
+
+## 3) Open GUI
+
+Go to `http://127.0.0.1:8000/`.
+
+## 4) Run the motherboard sequence
+
+In the GUI:
+1. Select the motherboard test sequence.
+2. Launch the run.
+
+## Notes
+
+- The backend exposes WebSocket on `ws://127.0.0.1:8765`.
+- If frontend assets are in a local folder, set `PYTESTFLOW_FRONTEND_DIR` to that folder (must contain `index.html`).
+- If you need this guide in your current folder, run:
+
+```bash
+pytestflow-am quickstart
+```

pytestflow/steps/README.md

@@ -0,0 +1,43 @@
+# PyTestFlow Steps
+
+The `pytestflow.steps` package provides ready-made decorators layered on top of
+`pytestflow.core.step`.
+
+See the [project README](../../readme.md) for overview usage.
+
+## Available step decorators
+
+| Decorator | Import path | Purpose |
+| --- | --- | --- |
+| `numeric_limit_step` | `pytestflow.steps` | Validate one numeric value against a limit/range. |
+| `df_numeric_limits_step` | `pytestflow.steps` | Apply numeric limits to multiple values (dict/series). |
+| `pass_fail_step` | `pytestflow.steps` | Convert boolean outcome into pass/fail state. |
+| `string_check_step` | `pytestflow.steps` | Compare string output with expected value/match mode. |
+| `waveform_limit_step` | `pytestflow.steps` | Validate waveform points against lower/upper masks. |
+| `flow_control_step` | `pytestflow.steps` | Publish control metadata and steer sequence transitions. |
+| `action_step` | `pytestflow.steps.action_step` | Run side-effect actions and optionally `store_as` in context. |
+| `message_pop_up_step` | `pytestflow.steps.message_pop_up` | Trigger frontend-driven popup interactions. |
+| `msgbox_step_qt` | `pytestflow.steps.utility` | Show local Qt message dialog and capture input. |
+
+## Creating custom steps
+
+```python
+from pytestflow.core import step
+from pytestflow.core.pytestflow_states import PyTestflowDone
+
+
+def my_step(name=None):
+    def decorator(fn):
+        @step(name=name or fn.__name__)
+        def wrapper(*args, **kwargs):
+            data = fn(*args, **kwargs)
+            return PyTestflowDone(ptf_result={"step_status": "done", "output": data})
+        return wrapper
+    return decorator
+```
+
+## Best practices
+
+- Keep step functions small and deterministic when possible.
+- Return `PyTestflowState` subclasses for expected test outcomes.
+- Use `store_as` and `ptf_context.locals` for explicit handoff between steps.

pytestflow/steps/__init__.py

@@ -0,0 +1,15 @@
+from .numeric_limit import numeric_limit_step
+from .string_check import string_check_step
+from .waveform_limit import waveform_limit_step
+from .df_numeric_limits import df_numeric_limits_step
+from .pass_fail import pass_fail_step
+from .flow_control import flow_control_step
+
+__all__ = [
+    "numeric_limit_step",
+    "string_check_step",
+    "waveform_limit_step",
+    "df_numeric_limits_step",
+    "pass_fail_step",
+    "flow_control_step",
+]