TestRunner
==========

Test runner for executing registered test cases.

The TestRunner coordinates test execution:
1. Creates test run folder for output
2. Sets up TestContext with utilities
3. Runs test setup, run, verify, teardown phases
4. Collects results and generates reports

Classes
-------

.. py:class:: TestSuiteResult

   Result of running a test suite.

   **Methods:**

   .. py:method:: passed()

      True if all tests passed.

   .. py:method:: passed_count()

      Number of tests that passed.

   .. py:method:: failed_count()

      Number of tests that failed.

   .. py:method:: total_count()

      Total number of tests.


.. py:class:: TestRunner

   Executes registered test cases and collects results.
   
   Usage:
       runner = TestRunner()
   
       # List available tests
       for info in runner.list_tests():
           print(f"{info.name}: {info.description}")
   
       # Run a single test
       result = runner.run_test("algorithm_watershed")
   
       # Run all tests in a category
       suite_result = runner.run_suite("algorithms")
   
       # Run all tests
       suite_result = runner.run_suite("all")

   **Methods:**

   .. py:method:: __init__()

      Initialize test runner.

   .. py:method:: list_tests()

      List available test cases.

   .. py:method:: list_categories()

      List available test categories.

   .. py:method:: run_test()

      Run a single test case by name.

   .. py:method:: run_suite()

      Run a suite of tests.

   .. py:method:: discover_tests()

      Discover and register test cases from TestCases package.


Functions
---------

.. py:function:: passed()

   True if all tests passed.

.. py:function:: passed_count()

   Number of tests that passed.

.. py:function:: failed_count()

   Number of tests that failed.

.. py:function:: total_count()

   Total number of tests.

.. py:function:: list_tests()

   List available test cases.
   
   Args:
       category: Optional category filter.
   
   Returns:
       List of TestCaseInfo objects.

.. py:function:: list_categories()

   List available test categories.
   
   Returns:
       List of category names.

.. py:function:: run_test()

   Run a single test case by name.
   
   Args:
       name: Name of test to run.
       test_run_folder: Optional existing test run folder.
   
   Returns:
       TestResult with pass/fail status and details.
   
   Raises:
       ValueError: If test name not found.

.. py:function:: run_suite()

   Run a suite of tests.
   
   Args:
       suite: Suite name. Can be "all" or a category name
              (e.g., "algorithm", "ui", "workflow").
   
   Returns:
       TestSuiteResult with all test results.

.. py:function:: discover_tests()

   Discover and register test cases from TestCases package.
   
   This imports all test modules to trigger @register_test decorators.