TestContext
===========

Test context providing test-specific utilities.

TestContext provides utilities for:
- Screenshots: Capture views during tests
- Timing: Measure operation performance
- Assertions: Record pass/fail conditions
- Logging: Test-specific notes

Tests call Slicer API directly - TestContext does NOT wrap Slicer functions.

Classes
-------

.. py:class:: TestContext

   Test execution context with test-specific utilities.
   
   Provides:
   - output_folder: Path to current test run folder
   - screenshot(): Capture and save screenshots
   - timing(): Measure operation duration
   - assert_*(): Record test assertions
   
   Does NOT provide wrappers for Slicer API. Tests should call Slicer
   functions directly (SampleData.downloadSample, slicer.mrmlScene, etc.).

   **Methods:**

   .. py:method:: __init__()

      Initialize test context.

   .. py:method:: output_folder()

      Path to current test run output folder.

   .. py:method:: assertions()

      List of assertions made during the test.

   .. py:method:: screenshots()

      List of screenshot filenames captured during the test.

   .. py:method:: metrics()

      Collected metrics for this test.

   .. py:method:: set_screenshot_context()

      Set context metadata for subsequent screenshots.

   .. py:method:: screenshot()

      Capture a screenshot of the current Slicer state (auto-numbered).

   .. py:method:: screenshot_slice_view()

      Capture a screenshot of a specific slice view (auto-numbered).

   .. py:method:: screenshot_3d_view()

      Capture a screenshot of the 3D view (auto-numbered).

   .. py:method:: timing()

      Create a timing context for measuring operation duration.

   .. py:method:: record_metric()

      Record a custom metric.

   .. py:method:: metric()

      Record a custom metric (alias for record_metric).

   .. py:method:: log()

      Log a test-specific note.

   .. py:method:: assert_true()

      Assert that a condition is true.

   .. py:method:: assert_false()

      Assert that a condition is false.

   .. py:method:: assert_equal()

      Assert that two values are equal.

   .. py:method:: assert_not_equal()

      Assert that two values are not equal.

   .. py:method:: assert_greater()

      Assert that actual > expected.

   .. py:method:: assert_greater_equal()

      Assert that actual >= expected.

   .. py:method:: assert_less()

      Assert that actual < expected.

   .. py:method:: assert_less_equal()

      Assert that actual <= expected.

   .. py:method:: assert_is_not_none()

      Assert that a value is not None.

   .. py:method:: assert_is_none()

      Assert that a value is None.

   .. py:method:: assert_almost_equal()

      Assert that two values are approximately equal.


Functions
---------

.. py:function:: output_folder()

   Path to current test run output folder.

.. py:function:: assertions()

   List of assertions made during the test.

.. py:function:: screenshots()

   List of screenshot filenames captured during the test.

.. py:function:: metrics()

   Collected metrics for this test.

.. py:function:: set_screenshot_context()

   Set context metadata for subsequent screenshots.
   
   This metadata is stored in the manifest to document what each
   screenshot shows, without creating nested folders.
   
   Usage:
       ctx.set_screenshot_context(sample_data="MRBrainTumor1", algorithm="watershed")
       ctx.screenshot("After 5 clicks")  # -> test_name/001.png with metadata
   
   Args:
       sample_data: Name of sample data being used.
       algorithm: Name of algorithm being tested.
       stage: Stage of the test (e.g., "setup", "before_paint", "after_paint").

.. py:function:: screenshot()

   Capture a screenshot of the current Slicer state (auto-numbered).
   
   Args:
       description: Human-readable description of what the screenshot shows.
       doc_tags: Tags for documentation filtering (e.g., ["algorithm", "watershed"]).
                 Screenshots with doc_tags are included in auto-generated documentation.
   
   Returns:
       ScreenshotInfo with path and metadata.

.. py:function:: screenshot_slice_view()

   Capture a screenshot of a specific slice view (auto-numbered).
   
   Args:
       view: View name ("Red", "Yellow", "Green").
       description: Human-readable description.
       doc_tags: Tags for documentation filtering.
   
   Returns:
       ScreenshotInfo with path and metadata.

.. py:function:: screenshot_3d_view()

   Capture a screenshot of the 3D view (auto-numbered).
   
   Args:
       description: Human-readable description.
       doc_tags: Tags for documentation filtering.
   
   Returns:
       ScreenshotInfo with path and metadata.

.. py:function:: timing()

   Create a timing context for measuring operation duration.
   
   Usage:
       with ctx.timing("watershed_stroke"):
           effect.apply(...)
   
   Args:
       operation: Name of the operation being timed.
   
   Returns:
       Context manager that records duration on exit.

.. py:function:: record_metric()

   Record a custom metric.
   
   Args:
       name: Metric name (e.g., "voxel_count", "dice_coefficient").
       value: Metric value.
       unit: Optional unit string (e.g., "voxels", "ms").

.. py:function:: metric()

   Record a custom metric (alias for record_metric).
   
   Args:
       name: Metric name (e.g., "voxel_count", "dice_coefficient").
       value: Metric value.
       unit: Optional unit string (e.g., "voxels", "ms").

.. py:function:: log()

   Log a test-specific note.
   
   Use for observations during test execution that may help
   with debugging or understanding test behavior.
   
   Args:
       message: Note to log.

.. py:function:: assert_true()

   Assert that a condition is true.
   
   Args:
       condition: Condition to check.
       message: Description of what is being checked.
   
   Returns:
       Assertion result.

.. py:function:: assert_false()

   Assert that a condition is false.
   
   Args:
       condition: Condition to check.
       message: Description of what is being checked.
   
   Returns:
       Assertion result.

.. py:function:: assert_equal()

   Assert that two values are equal.
   
   Args:
       actual: Actual value.
       expected: Expected value.
       message: Description of what is being checked.
   
   Returns:
       Assertion result.

.. py:function:: assert_not_equal()

   Assert that two values are not equal.
   
   Args:
       actual: Actual value.
       expected: Value that should not match.
       message: Description of what is being checked.
   
   Returns:
       Assertion result.

.. py:function:: assert_greater()

   Assert that actual > expected.
   
   Args:
       actual: Actual value.
       expected: Minimum threshold (exclusive).
       message: Description of what is being checked.
   
   Returns:
       Assertion result.

.. py:function:: assert_greater_equal()

   Assert that actual >= expected.
   
   Args:
       actual: Actual value.
       expected: Minimum threshold (inclusive).
       message: Description of what is being checked.
   
   Returns:
       Assertion result.

.. py:function:: assert_less()

   Assert that actual < expected.
   
   Args:
       actual: Actual value.
       expected: Maximum threshold (exclusive).
       message: Description of what is being checked.
   
   Returns:
       Assertion result.

.. py:function:: assert_less_equal()

   Assert that actual <= expected.
   
   Args:
       actual: Actual value.
       expected: Maximum threshold (inclusive).
       message: Description of what is being checked.
   
   Returns:
       Assertion result.

.. py:function:: assert_is_not_none()

   Assert that a value is not None.
   
   Args:
       value: Value to check.
       message: Description of what is being checked.
   
   Returns:
       Assertion result.

.. py:function:: assert_is_none()

   Assert that a value is None.
   
   Args:
       value: Value to check.
       message: Description of what is being checked.
   
   Returns:
       Assertion result.

.. py:function:: assert_almost_equal()

   Assert that two values are approximately equal.
   
   Args:
       actual: Actual value.
       expected: Expected value.
       delta: Maximum allowed difference.
       message: Description of what is being checked.
   
   Returns:
       Assertion result.