From 7ff4e0a3bfd657727301b5d727a00737760a4d93 Mon Sep 17 00:00:00 2001
From: goodboy <goodboy_foss@protonmail.com>
Date: Thu, 2 Jul 2026 12:29:16 -0400
Subject: [PATCH] Surface example stderr on any non-zero exit
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The docs-example harness only re-raises captured subproc
stderr when the LAST line contains 'Error', but a `tractor`
root-actor crash always ends stderr with the strict-EG
collapse note `( ^^^ this exc was collapsed from a group ^^^ )`
— so every possible crash is swallowed down to a bare
`assert 1 == 0`, exactly what the macOS CI leg shows for the
UDS example in GH #473.

- raise with the FULL stderr (+stdout) whenever the example
  subproc exits non-zero, regardless of stderr shape.
- keep the legacy last-line 'Error' check for zero-rc runs
  which still emit error-ish output.

First task-bullet of GH #473.

Prompt-IO: ai/prompt-io/claude/20260702T155006Z_65bf9df5_prompt_io.md

(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
---
 tests/test_docs_examples.py | 32 +++++++++++++++++++++++++++++---
 1 file changed, 29 insertions(+), 3 deletions(-)

diff --git a/tests/test_docs_examples.py b/tests/test_docs_examples.py
index cce85292..1692ae63 100644
--- a/tests/test_docs_examples.py
+++ b/tests/test_docs_examples.py
@@ -178,10 +178,11 @@ def test_example(
         code = ex.read()
 
         with run_example_in_subproc(code) as proc:
+            out = None
             err = None
             try:
                 if not proc.poll():
-                    _, err = proc.communicate(timeout=timeout)
+                    out, err = proc.communicate(timeout=timeout)
 
             except subprocess.TimeoutExpired as e:
                 test_log.exception(
@@ -190,9 +191,34 @@ def test_example(
                 proc.kill()
                 err = e.stderr
 
+            errmsg: str = err.decode() if err else ''
+
+            # XXX, ALWAYS surface the subproc's full stderr
+            # whenever it exits non-zero!
+            #
+            # The prior impl only raised when the LAST stderr
+            # line contained 'Error', swallowing any crash whose
+            # traceback ends in a non-`XxxError:` line; in
+            # particular EVERY `tractor` root-actor crash ends
+            # with the strict-EG collapse note,
+            # '( ^^^ this exc was collapsed from a group ^^^ )',
+            # so ALL such failures were reduced to a bare
+            # `assert 1 == 0` in CI logs.. see GH #473.
+            rc: int|None = proc.returncode
+            if rc:
+                outmsg: str = out.decode() if out else ''
+                raise Exception(
+                    f'Example script exited with rc={rc} !?\n'
+                    f'\n'
+                    f'stdout:\n'
+                    f'{outmsg}\n'
+                    f'\n'
+                    f'stderr:\n'
+                    f'{errmsg}\n'
+                )
+
             # if we get some gnarly output let's aggregate and raise
-            if err:
-                errmsg = err.decode()
+            if errmsg:
                 errlines = errmsg.splitlines()
                 last_error = errlines[-1]
                 if (