testsweet 0.2.2__tar.gz → 0.2.3__tar.gz

{testsweet-0.2.2 → testsweet-0.2.3}/CHANGELOG.md

@@ -1,6 +1,21 @@
 Changelog
 =========
 
+[0.2.3] (2026-06-28)
+--------------------
+
+### Improvements
+
+- Added tests and documentation for the assertion explainer.
+- Added color output for outcomes.
+- Grouped output by module and class.
+- Included timing in the summary.
+- Captured each test's stdout and stderr, replaying them in the
+  failure detail block.
+
+[0.2.3]: https://github.com/kaapstorm/testsweet/releases/tag/v0.2.3
+
+
 [0.2.2] (2026-06-27)
 --------------------
 

{testsweet-0.2.2 → testsweet-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: testsweet
-Version: 0.2.2
+Version: 0.2.3
 Summary: Python testing for humans
 Project-URL: Homepage, https://github.com/kaapstorm/testsweet
 Project-URL: Source, https://github.com/kaapstorm/testsweet

{testsweet-0.2.2 → testsweet-0.2.3}/docs/getting-started.md

@@ -138,46 +138,6 @@ Subclasses can chain a parent's `__test_context__` via
 `super().__test_context__()`.
 
 
-Plugins
--------
-
-Testsweet discovers plugins via the `testsweet.plugins` entry-point
-group. A plugin is any module exposing both of:
-
-* `session()` — a context manager that wraps the entire test run.
-  Use for one-time setup/teardown (e.g. provisioning a test database).
-* `unit(name)` — a context manager that wraps each test call. Use for
-  per-test isolation.
-
-Both are required. If a plugin doesn't need one, define a no-op:
-
-```python
-from contextlib import contextmanager
-
-
-@contextmanager
-def session():
-    # ... real setup/teardown ...
-    yield
-
-
-@contextmanager
-def unit(name):
-    yield
-```
-
-Plugins are installed as ordinary Python distributions and register
-themselves in their own `pyproject.toml`:
-
-```toml
-[project.entry-points."testsweet.plugins"]
-django = "testsweet_django"
-```
-
-See [testsweet-django](https://github.com/kaapstrom/testsweet-django)
-for a working example.
-
-
 Parametrized tests
 ------------------
 
@@ -208,6 +168,57 @@ it consumed at run time, use `@params_lazy` instead.
 > functions or methods you want discovered.
 
 
+Getting the most from explanations
+----------------------------------
+
+When an `assert` fails, Testsweet prints the value of each operand in
+the failing expression, so you can often see what went wrong without
+reaching for a debugger:
+
+```python
+@test
+def counts_items():
+    items = [1, 2]
+    count = len(items)
+    assert count == 3
+```
+
+```
+======================================================================
+FAIL: tests.example.counts_items
+----------------------------------------------------------------------
+Traceback (most recent call last):
+  ...
+AssertionError
+  count = 2
+```
+
+To show those values, Testsweet re-evaluates the operands of the failing
+expression. Running code a second time can have side effects, so to
+make sure that building the explanation never changes how your program
+behaves, Testsweet deliberately **skips function calls, attribute
+access, and subscripts**. Constant literals are skipped too, since they
+carry no information.
+
+That means an assertion built directly out of calls, attributes, or
+subscripts has nothing left to explain:
+
+```python
+assert response.json()['status'] == 200   # no operand values shown
+```
+
+Bind the interesting values to plain local variables and assert on
+those instead:
+
+```python
+status = response.json()['status']
+assert status == 200                      # explanation: status = 404
+```
+
+This is good practice anyway: it keeps each assertion to a single idea
+and makes the failure output read like the question you were asking.
+
+
 Skipping and expected failures
 ------------------------------
 
@@ -374,3 +385,43 @@ test_files = ["test_*.py", "*_test.py"]
 ```
 
 See the [reference](reference.md) for the full list of public APIs.
+
+
+Plugins
+-------
+
+Testsweet discovers plugins via the `testsweet.plugins` entry-point
+group. A plugin is any module exposing both of:
+
+* `session()` — a context manager that wraps the entire test run.
+  Use for one-time setup/teardown (e.g. provisioning a test database).
+* `unit(name)` — a context manager that wraps each test call. Use for
+  per-test isolation.
+
+Both are required. If a plugin doesn't need one, define a no-op:
+
+```python
+from contextlib import contextmanager
+
+
+@contextmanager
+def session():
+    # ... real setup/teardown ...
+    yield
+
+
+@contextmanager
+def unit(name):
+    yield
+```
+
+Plugins are installed as ordinary Python distributions and register
+themselves in their own `pyproject.toml`:
+
+```toml
+[project.entry-points."testsweet.plugins"]
+django = "testsweet_django"
+```
+
+See [testsweet-django](https://github.com/kaapstrom/testsweet-django)
+for a working example.

{testsweet-0.2.2 → testsweet-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "testsweet"
-version = "0.2.2"
+version = "0.2.3"
 description = "Python testing for humans"
 license = "Apache-2.0"
 license-files = ["LICENSE"]

{testsweet-0.2.2 → testsweet-0.2.3}/src/testsweet/__init__.py

@@ -7,6 +7,7 @@ from testsweet._outcomes import (
     Failed,
     Outcome,
     Passed,
+    Result,
     Skipped,
     XFailed,
     XPassed,
@@ -27,6 +28,7 @@ __all__ = [
     'Outcome',
     'Passed',
     'Plugin',
+    'Result',
     'Skipped',
     'XFailed',
     'XPassed',

{testsweet-0.2.2 → testsweet-0.2.3}/src/testsweet/__main__.py

@@ -1,11 +1,13 @@
 import argparse
+import os
 import pathlib
 import sys
+import time
 
 from testsweet._config import load_config
 from testsweet._loaders import scoped_sys_path
 from testsweet._plugins import load_plugins, session_for, unit_wrapper
-from testsweet._outcomes import Errored, Failed, Outcome, XPassed
+from testsweet._outcomes import Errored, Failed, Result, XPassed
 from testsweet._report import (
     format_result_line,
     print_failure_detail,
@@ -45,6 +47,31 @@ Options:
 """
 
 
+def _split_group(name: str) -> tuple[str | None, str]:
+    """Split 'ClassName.method[n]' into ('ClassName', 'method[n]').
+
+    Returns (None, name) for standalone functions with no class prefix.
+    """
+    dot = name.find('.')
+    return (name[:dot], name[dot + 1:]) if dot != -1 else (None, name)
+
+
+def _supports_color() -> bool:
+    if not sys.stdout.isatty():
+        return False
+    if os.environ.get('NO_COLOR'):
+        return False
+    if sys.platform == 'win32':
+        # VT processing is auto-enabled from Python 3.12+. On older
+        # versions, accept Windows Terminal (WT_SESSION) and ANSICON.
+        return (
+            sys.version_info >= (3, 12)
+            or bool(os.environ.get('WT_SESSION'))
+            or bool(os.environ.get('ANSICON'))
+        )
+    return True
+
+
 def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(add_help=False)
     parser.add_argument(
@@ -94,25 +121,51 @@ def main(argv: list[str]) -> int:
         config = load_config(pathlib.Path.cwd())
         plugins = load_plugins()
         wrap_unit = unit_wrapper(plugins)
-        results: list[tuple[str, Outcome]] = []
-        real_failures: list[tuple[str, Outcome]] = []
+        use_color = _supports_color()
+        results: list[Result] = []
+        real_failures: list[tuple[str, Result]] = []
+        start = time.monotonic()
         with session_for(plugins):
             groups = discover_targets(args.targets, config)
+            last_module: str | None = None
+            last_class: str | None = None
             for module, names in groups:
-                for name, outcome in run(
+                for result in run(
                     module,
                     names=names,
                     wrap_unit=wrap_unit,
                     keep=keep,
                 ):
-                    full_name = f'{module.__name__}.{name}'
-                    print(format_result_line(full_name, outcome))
-                    results.append((full_name, outcome))
-                    if isinstance(outcome, (Failed, Errored, XPassed)):
-                        real_failures.append((full_name, outcome))
-        for full_name, outcome in real_failures:
-            print_failure_detail(full_name, outcome)
-        print(summarize(results))
+                    full_name = f'{module.__name__}.{result.name}'
+                    class_name, short_name = _split_group(result.name)
+                    if module.__name__ != last_module:
+                        print(module.__name__)
+                        last_module = module.__name__
+                        last_class = None
+                    if class_name != last_class:
+                        if class_name is not None:
+                            print(f'  {class_name}')
+                        last_class = class_name
+                    indent = '    ' if class_name else '  '
+                    result_line = format_result_line(
+                        short_name,
+                        result.outcome,
+                        use_color=use_color,
+                    )
+                    print(f'{indent}{result_line}')
+                    results.append(result)
+                    if isinstance(result.outcome, (Failed, Errored, XPassed)):
+                        real_failures.append((full_name, result))
+        elapsed = time.monotonic() - start
+        for full_name, result in real_failures:
+            print_failure_detail(
+                full_name,
+                result.outcome,
+                result.stdout,
+                result.stderr,
+            )
+        print()
+        print(summarize(results, use_color=use_color, elapsed=elapsed))
         return 1 if real_failures else 0
 
 

{testsweet-0.2.2 → testsweet-0.2.3}/src/testsweet/_assertion.py

@@ -2,9 +2,10 @@
 
 Reads the source file referenced by the failing assertion's traceback,
 locates the ``assert`` AST node, and re-evaluates its sub-expressions
-in the original frame to show their values. ``Call`` sub-expressions
-are deliberately skipped: re-evaluating a call would fire its side
-effects a second time.
+in the original frame to show their values. Sub-expressions that can
+fire side effects when re-evaluated are deliberately skipped: calls,
+attribute access (``__getattr__``/properties), and subscripting
+(``__getitem__``).
 
 Failures (missing source, syntax errors, eval errors) silently yield
 ``None`` — the explainer is a nicety, not a correctness requirement.
@@ -30,9 +31,16 @@ def explain_assertion(exc: AssertionError) -> str | None:
     lines = []
     seen: set[str] = set()
     for sub in _sub_exprs(assert_node.test):
-        if isinstance(sub, (ast.Constant, ast.Call)):
-            # Skip constants (no information) and calls (re-evaluating
-            # would fire side effects a second time).
+        if isinstance(sub, (
+            ast.Constant,
+            ast.Call,
+            ast.Attribute,
+            ast.Subscript,
+        )):
+            # Skip constants (no information) and anything that can
+            # fire side effects when re-evaluated: calls, attribute
+            # access (``__getattr__``/properties), and subscripting
+            # (``__getitem__``).
             continue
         src = ast.unparse(sub)
         if src in seen:

{testsweet-0.2.2 → testsweet-0.2.3}/src/testsweet/_outcomes.py

@@ -59,3 +59,19 @@ class XPassed:
 
 
 Outcome = Passed | Failed | Errored | Skipped | XFailed | XPassed
+
+
+@dataclass(frozen=True)
+class Result:
+    """A test unit's outcome plus any output it produced.
+
+    ``run()`` returns ``list[Result]``. ``stdout`` and ``stderr`` hold
+    the test's captured streams; they are empty unless the unit wrote
+    to those streams. Captured output is replayed only when the test
+    fails — see ``_report.print_failure_detail``.
+    """
+
+    name: str
+    outcome: Outcome
+    stdout: str = ''
+    stderr: str = ''

{testsweet-0.2.2 → testsweet-0.2.3}/src/testsweet/_report.py

@@ -14,11 +14,22 @@ from testsweet._outcomes import (
     Failed,
     Outcome,
     Passed,
+    Result,
     Skipped,
     XFailed,
     XPassed,
 )
 
+_GREEN = '32'
+_YELLOW = '33'
+_RED = '31'
+_BOLD_RED = '1;31'
+_MAGENTA = '35'
+
+
+def _c(text: str, code: str, enabled: bool) -> str:
+    return f'\033[{code}m{text}\033[0m' if enabled else text
+
 
 _XPASS_DETAIL = (
     'Test was marked @xfail but passed. '
@@ -30,36 +41,63 @@ def _suffix(reason: str | None) -> str:
     return f': {reason}' if reason else ''
 
 
-def format_result_line(full_name: str, outcome: Outcome) -> str:
+def format_result_line(
+    full_name: str,
+    outcome: Outcome,
+    use_color: bool = False,
+) -> str:
     """One-line summary suitable for streaming output."""
     match outcome:
         case Passed():
-            return f'{full_name} ... ok'
+            status = _c('ok', _GREEN, use_color)
+            return f'{full_name} ... {status}'
         case Skipped(reason=reason):
-            return f'{full_name} ... skipped{_suffix(reason)}'
+            status = _c(f'skipped{_suffix(reason)}', _YELLOW, use_color)
+            return f'{full_name} ... {status}'
         case XFailed(reason=reason):
-            return f'{full_name} ... xfailed{_suffix(reason)}'
+            status = _c(f'xfailed{_suffix(reason)}', _YELLOW, use_color)
+            return f'{full_name} ... {status}'
         case XPassed(reason=reason):
-            return f'{full_name} ... XPASSED{_suffix(reason)}'
+            status = _c(f'XPASSED{_suffix(reason)}', _MAGENTA, use_color)
+            return f'{full_name} ... {status}'
         case Failed(exc=exc):
             detail = str(exc) or assertion_source(exc) or ''
-            return f'{full_name} ... FAIL: AssertionError: {detail}'
+            status = _c(
+                f'FAIL: AssertionError: {detail}',
+                _BOLD_RED,
+                use_color,
+            )
+            return f'{full_name} ... {status}'
         case Errored(exc=exc):
-            return (
-                f'{full_name} ... ERROR: {type(exc).__name__}: {exc}'
+            status = _c(
+                f'ERROR: {type(exc).__name__}: {exc}', _RED, use_color,
             )
+            return f'{full_name} ... {status}'
+
+
+def _print_captured(stdout: str, stderr: str, file: TextIO) -> None:
+    if stdout:
+        print('-' * 26 + ' Captured stdout ' + '-' * 27, file=file)
+        print(stdout, end='' if stdout.endswith('\n') else '\n', file=file)
+    if stderr:
+        print('-' * 26 + ' Captured stderr ' + '-' * 27, file=file)
+        print(stderr, end='' if stderr.endswith('\n') else '\n', file=file)
 
 
 def print_failure_detail(
     full_name: str,
     outcome: Outcome,
-    file: TextIO = sys.stdout,
+    stdout: str = '',
+    stderr: str = '',
+    file: TextIO | None = None,
 ) -> None:
     """Multi-line failure block.
 
     Fires only for ``Failed``, ``Errored``, and ``XPassed``. Other
     outcomes do not get a detail block.
     """
+    if file is None:
+        file = sys.stdout
     match outcome:
         case Passed() | Skipped() | XFailed():
             return
@@ -69,14 +107,17 @@ def print_failure_detail(
             print(f'XPASSED: {full_name}', file=file)
             print('-' * 70, file=file)
             print(_XPASS_DETAIL, file=file)
+            _print_captured(stdout, stderr, file)
             return
         case Failed(exc=exc):
             _print_traceback_block('FAIL', full_name, exc, file)
             explanation = explain_assertion(exc)
             if explanation is not None:
                 print(explanation, file=file)
+            _print_captured(stdout, stderr, file)
         case Errored(exc=exc):
             _print_traceback_block('ERROR', full_name, exc, file)
+            _print_captured(stdout, stderr, file)
 
 
 def _print_traceback_block(
@@ -110,27 +151,32 @@ def _outcome_key(outcome: Outcome) -> str:
 
 
 _SUMMARY_ORDER = (
-    ('passed', 'passed'),
-    ('failed', 'failed'),
-    ('errored', 'error'),
-    ('skipped', 'skipped'),
-    ('xfailed', 'xfailed'),
-    ('xpassed', 'xpassed'),
+    ('passed', 'passed', _GREEN),
+    ('failed', 'failed', _BOLD_RED),
+    ('errored', 'error', _RED),
+    ('skipped', 'skipped', _YELLOW),
+    ('xfailed', 'xfailed', _YELLOW),
+    ('xpassed', 'xpassed', _MAGENTA),
 )
 
 
-def summarize(results: Iterable[tuple[str, Outcome]]) -> str:
+def summarize(
+    results: Iterable[Result],
+    use_color: bool = False,
+    elapsed: float | None = None,
+) -> str:
     """One-line summary of result counts."""
     counts: collections.Counter = collections.Counter()
     total = 0
-    for _name, outcome in results:
-        counts[_outcome_key(outcome)] += 1
+    for r in results:
+        counts[_outcome_key(r.outcome)] += 1
         total += 1
+    timing = f' in {elapsed:.2f}s' if elapsed is not None else ''
     if total == 0:
-        return '0 tests'
+        return f'0 tests{timing}'
     parts = [
-        f'{counts[key]} {label}'
-        for key, label in _SUMMARY_ORDER
+        _c(f'{counts[key]} {label}', color, use_color)
+        for key, label, color in _SUMMARY_ORDER
         if counts.get(key)
     ]
-    return ', '.join(parts)
+    return f'{", ".join(parts)}{timing}'

{testsweet-0.2.2 → testsweet-0.2.3}/src/testsweet/_runner.py

@@ -1,5 +1,11 @@
 """Run resolved test units and collect results."""
-from contextlib import AbstractContextManager, nullcontext
+import io
+from contextlib import (
+    AbstractContextManager,
+    nullcontext,
+    redirect_stderr,
+    redirect_stdout,
+)
 from types import ModuleType
 from typing import Any, Callable
 
@@ -10,6 +16,7 @@ from testsweet._outcomes import (
     Failed,
     Outcome,
     Passed,
+    Result,
     Skipped,
     XFailed,
     XPassed,
@@ -24,7 +31,7 @@ def run(
     names: list[str] | None = None,
     wrap_unit: Callable[[str], AbstractContextManager[Any]] | None = None,
     keep: TagFilter | None = None,
-) -> list[tuple[str, Outcome]]:
+) -> list[Result]:
     """Run the tests in ``module``.
 
     If ``names`` is given, only run tests whose qualified names appear
@@ -35,16 +42,18 @@ def run(
     method's effective tag set is the union of its class's tags and
     its own.
 
-    Returns a list of ``(name, outcome)`` tuples. ``outcome`` is one
-    of ``Passed``, ``Failed``, ``Errored``, ``Skipped``, ``XFailed``,
-    ``XPassed``.
+    Returns a list of ``Result`` records. Each carries the unit's
+    ``name``, its ``outcome`` (one of ``Passed``, ``Failed``,
+    ``Errored``, ``Skipped``, ``XFailed``, ``XPassed``), and the
+    ``stdout``/``stderr`` it printed (empty unless it wrote to those
+    streams; captured only while the unit body runs).
     """
     if wrap_unit is None:
         def wrap_unit(_name: str) -> AbstractContextManager[Any]:
             return nullcontext()
-    results: list[tuple[str, Outcome]] = []
+    results: list[Result] = []
     for name, call in resolve_units(module, names, keep=keep):
-        results.append((name, _run_one(name, call, wrap_unit)))
+        results.append(_run_one(name, call, wrap_unit))
     return results
 
 
@@ -52,29 +61,43 @@ def _run_one(
     name: str,
     call: Callable[[], Any],
     wrap_unit: Callable[[str], AbstractContextManager[Any]],
-) -> Outcome:
+) -> Result:
     try:
         skip_marker: SkipMarker | None = active_marker(call, SKIP_MARKER)
     except Exception as exc:
-        return Errored(exc)
+        return Result(name, Errored(exc))
     if skip_marker is not None:
-        return Skipped(skip_marker.reason)
+        return Result(name, Skipped(skip_marker.reason))
     try:
         xfail_marker: XFailMarker | None = active_marker(call, XFAIL_MARKER)
     except Exception as exc:
-        return Errored(exc)
+        return Result(name, Errored(exc))
+    out_buf = io.StringIO()
+    err_buf = io.StringIO()
     if xfail_marker is not None:
         try:
-            with wrap_unit(name):
+            with (
+                wrap_unit(name),
+                redirect_stdout(out_buf),
+                redirect_stderr(err_buf),
+            ):
                 call()
         except Exception as exc:
-            return XFailed(exc, xfail_marker.reason)
-        return XPassed(xfail_marker.reason)
+            outcome: Outcome = XFailed(exc, xfail_marker.reason)
+        else:
+            outcome = XPassed(xfail_marker.reason)
+        return Result(name, outcome, out_buf.getvalue(), err_buf.getvalue())
     try:
-        with wrap_unit(name):
+        with (
+            wrap_unit(name),
+            redirect_stdout(out_buf),
+            redirect_stderr(err_buf),
+        ):
             call()
     except AssertionError as exc:
-        return Failed(exc)
+        outcome = Failed(exc)
     except Exception as exc:
-        return Errored(exc)
-    return Passed()
+        outcome = Errored(exc)
+    else:
+        outcome = Passed()
+    return Result(name, outcome, out_buf.getvalue(), err_buf.getvalue())

{testsweet-0.2.2 → testsweet-0.2.3}/src/testsweet/_tag.py

@@ -7,8 +7,6 @@ def tag(*names):
 
     Stack ``@tag`` calls or pass multiple names in one call; the
     accumulated set is stored as a frozenset under ``TAGS_MARKER``.
-    Tags are stored but not yet used by the runner in 0.2.0 —
-    groundwork for future filtering.
     """
     if not names:
         raise TypeError('tag() requires at least one tag name')