docs: run item capture + batch param

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

DESIGN.md

@@ -202,7 +202,7 @@ A find bar (Ctrl+F) over the `QTestTree` (`src/testium/main_win/test_tree.py`) h
 - `QTestTreeItem._refresh_highlight()` is the single source of truth for the name-column colours: the **search** highlight (pastel amber bg + forced black text, readable in light *and* dark themes) and the green **run** highlight (`setHighlighted`) are recomputed from state flags with precedence **run > search > default**. No brush is saved/restored, so the two layers never leave a stale/permanent colour when they overlap (e.g. searching while a test runs).
 
 ### `run` item
-`src/testium/interpreter/test_items/test_item_run.py` — launches a `.tum` file in a new testium instance (`-b` in batch mode, `-r` in GUI mode). Result:
+`src/testium/interpreter/test_items/test_item_run.py` — launches a `.tum` file in a new testium instance. Child mode: `-b` in batch, `-r` (own window) in the GUI, or forced `-b` by `batch: true`. A `-b` child is **captured** (launched `-o`, no colour): its stdout/stderr stream through `proc_drain.drain_to_log()` into this test's log/report, and the full text is kept as the result value, so `store_result` pushes it to the gdict and `expected_result`/`process_result`/a py_func can post-process it. Stop kills the child via the poll loop. Result:
 - **PASS** if the sub-instance launched and ran to completion (exit code is ignored)
 - **FAIL** if the file is not found, `wait_for_exec` is set without `start_time`/`end_time`, the time window was not reached, or any other launch error
 

doc/manual/sphinx/source/test_items/run_test_item.rst

@@ -4,7 +4,13 @@
 This test item executes a new instance of testium with the specified ``.tum`` file.
 
 * In **batch mode** (``-b``): the sub-instance is started with ``-b``.
-* In **GUI mode**: the sub-instance is started with ``-r`` (run and close).
+* In **GUI mode**: the sub-instance opens its own window with ``-r`` (run and close).
+* ``batch: true`` forces the sub-instance to run headless (``-b``) even in the GUI.
+
+A sub-instance started with ``-b`` is **captured**: its output is streamed into this
+test's log and report, and kept as the item's result value, so it can be stored
+with ``store_result`` and post-processed (``expected_result``, ``process_result``,
+or a ``py_func`` reading the global variable).
 
 The item result is **PASS** if the sub-instance launched and ran to completion,
 regardless of whether the sub-tests passed or failed.
@@ -17,7 +23,6 @@ launched, or the time window was not reached (see ``start_time`` / ``end_time``)
     - run:
         name: Execute TUM
         tum: example_cycle.tum
-        python_bin: python3
         log_file: $(home)/reports/test.log
         report_file: $(home)/reports/test.rep
 
@@ -28,9 +33,8 @@ run test item has the following specific attributes:
 
 * ``tum``: mandatory, the path of the file to execute. Can be relative to the current execution folder.
 * ``param_file`` (optional): the path of the parameter file to use; otherwise the default parameter file is used.
-* ``python_bin`` (optional): the path of a specific Python interpreter to use.
-* ``testium_path`` (optional): the path of a specific testium executable to use.
-* ``log_file`` (optional): the path of the log file. In GUI mode, if not provided, a file is created with a timestamp next to the ``.tum`` file. Not used in batch mode.
+* ``batch`` (optional): ``true`` to run the sub-instance headless (``-b``) and capture its output even in GUI mode (see above).
+* ``log_file`` (optional): the path of the log file. In GUI mode, if not provided, a file is created with a timestamp next to the ``.tum`` file. Not used in batch mode (the output is captured instead).
 * ``report_file`` (optional): the path of the report file to create.
 * ``start_time`` (optional): earliest time to execute the sub-instance, in ``HH:MM`` format.
 * ``end_time`` (optional): latest time for execution within a time frame, in ``HH:MM`` format.