ActionRecorder
==============

Action recorder for manual testing.

Records user actions during manual testing sessions for:
1. Reproducibility - understand what was tested
2. Test generation - convert actions to automated tests
3. Documentation - capture testing workflows

Uses Slicer observers to automatically capture:
- Segmentation modifications (detected via node observers)
- Effect parameter state at time of modification

Classes
-------

.. py:class:: ActionType
   :bases: Enum

   Types of recordable actions.


.. py:class:: ActionRecorder

   Records user actions during manual testing.
   
   Automatically captures segmentation modifications via Slicer observers.
   Records effect parameters at time of each paint action for reproducibility.
   
   Usage:
       recorder = ActionRecorder(test_run_folder)
   
       # Start recording with automatic capture
       recorder.start()
   
       # Manual records (screenshots, notes) still work
       recorder.record_screenshot("001_test", "After painting")
       recorder.record_note("Watershed stopped at expected boundary")
       recorder.record_pass("Segmentation looks correct")
   
       # Stop recording
       recorder.stop()
   
   Callback mode (for branch recording):
       def my_callback(action_dict):
           print(f"Action recorded: {action_dict['type']}")
   
       recorder = ActionRecorder(test_run_folder, action_callback=my_callback)
       recorder.start()
       # ... actions are recorded and callback is called ...

   **Methods:**

   .. py:method:: __init__()

      Initialize action recorder.

   .. py:method:: is_recording()

      True if currently recording.

   .. py:method:: action_count()

      Number of actions recorded in current session.

   .. py:method:: has_callback()

      True if an action callback is set.

   .. py:method:: set_action_callback()

      Set or clear the action callback.

   .. py:method:: start()

      Start recording actions.

   .. py:method:: stop()

      Stop recording actions.

   .. py:method:: record_paint()

      Record a paint action.

   .. py:method:: record_parameter_change()

      Record a parameter change.

   .. py:method:: record_algorithm_change()

      Record an algorithm change.

   .. py:method:: record_screenshot()

      Record a screenshot capture.

   .. py:method:: record_note()

      Record a user note.

   .. py:method:: record_pass()

      Record a manual pass mark.

   .. py:method:: record_fail()

      Record a manual fail mark.


Functions
---------

.. py:function:: is_recording()

   True if currently recording.

.. py:function:: action_count()

   Number of actions recorded in current session.

.. py:function:: has_callback()

   True if an action callback is set.

.. py:function:: set_action_callback()

   Set or clear the action callback.
   
   Args:
       callback: Callback function that receives action dicts, or None to clear.

.. py:function:: start()

   Start recording actions.
   
   Sets up observers on the current segmentation node to automatically
   capture paint events and parameter changes.

.. py:function:: stop()

   Stop recording actions.
   
   Removes all observers and saves final state.

.. py:function:: record_paint()

   Record a paint action.
   
   Args:
       ijk: Voxel coordinates (i, j, k).
       algorithm: Algorithm name used for painting.
       mode: "add" or "erase".
       radius_mm: Brush radius in mm.
       is_3d: Whether 3D brush mode is enabled.

.. py:function:: record_parameter_change()

   Record a parameter change.
   
   Args:
       parameter: Parameter name.
       value: New value.

.. py:function:: record_algorithm_change()

   Record an algorithm change.
   
   Args:
       algorithm: New algorithm name.

.. py:function:: record_screenshot()

   Record a screenshot capture.
   
   Args:
       screenshot_id: Screenshot identifier.
       description: Screenshot description.

.. py:function:: record_note()

   Record a user note.
   
   Args:
       note: User's observation or note.

.. py:function:: record_pass()

   Record a manual pass mark.
   
   Args:
       reason: Reason for passing.

.. py:function:: record_fail()

   Record a manual fail mark.
   
   Args:
       reason: Reason for failing.