TestRunFolder
=============

Test run folder organization.

Creates and manages the output folder structure for test runs.

Classes
-------

.. py:class:: TestRunFolder

   Manages the folder structure for a test run.
   
   Structure:
       test_runs/2026-01-24_143025_algorithms/
       ├── metadata.json          # Run config, summary
       ├── results.json           # Test results
       ├── metrics.json           # Performance metrics
       ├── manual_actions.jsonl   # Recorded manual testing
       ├── screenshots/
       │   ├── manifest.json      # Screenshot descriptions
       │   └── *.png              # Captured screenshots
       └── logs/
           ├── test_run.log       # Test execution log
           └── slicer_session.log # Copy of Slicer log

   **Methods:**

   .. py:method:: __init__()

      Initialize test run folder.

   .. py:method:: create()

      Create a new test run folder with timestamp.

   .. py:method:: path()

      Path to the test run folder.

   .. py:method:: screenshots_folder()

      Path to screenshots subfolder.

   .. py:method:: logs_folder()

      Path to logs subfolder.

   .. py:method:: save_metadata()

      Save test run metadata.

   .. py:method:: save_results()

      Save test results to JSON.

   .. py:method:: save_screenshot_manifest()

      Save screenshot manifest.

   .. py:method:: copy_slicer_log()

      Copy Slicer session log to test run folder.

   .. py:method:: append_manual_action()

      Append a manual action to the actions log.


Functions
---------

.. py:function:: create()

   Create a new test run folder with timestamp.
   
   Args:
       base_path: Base directory for test runs.
       run_name: Name of the test run (e.g., "algorithms", "ui").
   
   Returns:
       New TestRunFolder instance.

.. py:function:: path()

   Path to the test run folder.

.. py:function:: screenshots_folder()

   Path to screenshots subfolder.

.. py:function:: logs_folder()

   Path to logs subfolder.

.. py:function:: save_metadata()

   Save test run metadata.
   
   Args:
       metadata: Metadata dictionary to save.

.. py:function:: save_results()

   Save test results to JSON.
   
   Args:
       results: List of TestResult objects.

.. py:function:: save_screenshot_manifest()

   Save screenshot manifest.
   
   Args:
       screenshots: List of screenshot info dictionaries.

.. py:function:: copy_slicer_log()

   Copy Slicer session log to test run folder.
   
   Returns:
       Path to copied log file, or None if not found.

.. py:function:: append_manual_action()

   Append a manual action to the actions log.
   
   Args:
       action: Action dictionary with type, timestamp, and details.