narrativetrace-pytest 0.2.0__tar.gz → 0.4.0__tar.gz

{narrativetrace_pytest-0.2.0 → narrativetrace_pytest-0.4.0}/.gitignore

@@ -28,3 +28,8 @@ build/
 # narrativetrace-pytest's default per-test artifact directory -- on by default, opt out with
 # NARRATIVETRACE_OUTPUT=false (see documentation/what-to-commit.md)
 narrative-traces/
+
+# The recipe scenario's approved baselines are source; the files an approval run writes beside them
+# are not (documentation/what-to-commit.md)
+examples/recipes/checkout/test-narratives/**/*.received.nt
+examples/recipes/checkout/test-narratives/**/*.incomplete.nt

{narrativetrace_pytest-0.2.0 → narrativetrace_pytest-0.4.0}/LICENSE

@@ -7,7 +7,7 @@ Parameters
 
 Licensor:             Empower Agile
 
-Licensed Work:        NarrativeTrace for Python (the narrativetrace PyPI distributions) version 0.2.0. The Licensed Work is (c) 2026 Empower Agile.
+Licensed Work:        NarrativeTrace for Python (the narrativetrace PyPI distributions) version 0.4.0. The Licensed Work is (c) 2026 Empower Agile.
 
 Additional Use Grant: You may make production use of the Licensed Work for any
                       purpose, including internal use and use in products and
@@ -18,7 +18,7 @@ Additional Use Grant: You may make production use of the Licensed Work for any
                       parties as a logging, tracing, or code-narrative product
                       or service.
 
-Change Date:          Four years from the date the Licensed Work is published. (2030-10-05 for this version)
+Change Date:          Four years from the date the Licensed Work is published. (2030-10-16 for this version)
 
 Change License:       Apache License, Version 2.0
 

{narrativetrace_pytest-0.2.0 → narrativetrace_pytest-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: narrativetrace-pytest
-Version: 0.2.0
+Version: 0.4.0
 Summary: pytest plugin for narrativetrace: per-test trace fixtures, artifacts, and reporting
 Project-URL: Homepage, https://github.com/narrativetrace/narrativetrace-python
 Project-URL: Source, https://github.com/narrativetrace/narrativetrace-python

{narrativetrace_pytest-0.2.0 → narrativetrace_pytest-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "narrativetrace-pytest"
-version = "0.2.0"
+version = "0.4.0"
 description = "pytest plugin for narrativetrace: per-test trace fixtures, artifacts, and reporting"
 readme = "README.md"
 requires-python = ">=3.12"

{narrativetrace_pytest-0.2.0 → narrativetrace_pytest-0.4.0}/src/narrativetrace_pytest/__init__.py

@@ -4,4 +4,4 @@
 # Copyright (c) 2026 Empower Agile
 """pytest plugin for narrativetrace."""
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"

narrativetrace_pytest-0.4.0/tests/fixture_wiring.py

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: BUSL-1.1
+# Licensed under the Business Source License 1.1 (see LICENSE); Change Date: four
+# years from publication; Change License: Apache-2.0
+# Copyright (c) 2026 Empower Agile
+"""The pytest row's wiring, as the framework table shows it: a test that requests the
+``narrative_trace`` fixture and traces through it. Not collected here (the outer session disables
+the plugin); ``test_fixture_wiring.py`` runs it under the real plugin. The doctor's
+``config.pytest-fixture`` fix and ``llms-full.md`` carry the ``wiring`` region verbatim
+(``narrativetrace_tooling/frameworks/wiring-snippets.md``)."""
+
+from __future__ import annotations
+
+# snippet:begin wiring
+from narrativetrace import ContextVarNarrativeContext, trace_object
+
+
+def test_place_order(narrative_trace: ContextVarNarrativeContext) -> None:
+    service = trace_object(OrderService(), narrative_trace)
+
+    assert service.place_order("cust-1", "prod-42") == "ORD-cust-1-prod-42"
+    # snippet:end wiring
+
+
+class OrderService:
+    def place_order(self, customer_id: str, product_id: str) -> str:
+        return f"ORD-{customer_id}-{product_id}"

narrativetrace_pytest-0.4.0/tests/test_fixture_wiring.py

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: BUSL-1.1
+# Licensed under the Business Source License 1.1 (see LICENSE); Change Date: four
+# years from publication; Change License: Apache-2.0
+# Copyright (c) 2026 Empower Agile
+"""The pytest row's wiring fixture works as printed: run under the real plugin, its test passes and
+the plugin writes that test's trace."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+_FIXTURE = Path(__file__).with_name("fixture_wiring.py")
+
+
+def test_the_wired_test_passes_and_writes_its_trace(
+    pytester: pytest.Pytester, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    out_dir = pytester.path / "nt-out"
+    monkeypatch.setenv("NARRATIVETRACE_OUTPUT_DIR", str(out_dir))
+    pytester.makepyfile(test_wired=_FIXTURE.read_text(encoding="utf-8"))
+
+    result = pytester.runpytest_subprocess()
+
+    result.assert_outcomes(passed=1)
+    traces = [path.read_text(encoding="utf-8") for path in out_dir.rglob("*.md")]
+    assert any("OrderService.place_order" in text for text in traces)

{narrativetrace_pytest-0.2.0 → narrativetrace_pytest-0.4.0}/tests/test_plugin.py

@@ -914,3 +914,64 @@ def test_a_malformed_committed_glossary_skips_harvesting_without_failing_the_sui
 
     result.assert_outcomes(passed=1)
     result.stdout.fnmatch_lines(["*glossary harvest failed, skipped*"])
+
+
+def test_a_failing_checkout_test_gets_its_own_narrative_showing_the_failure(
+    pytester: pytest.Pytester, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The recipe's "why did this test fail" shape: the payment charge throws, so the failure
+    narrative (terminal block and the written trace) shows reserve, then the failing charge, and
+    never the order save that was not reached."""
+    out_dir = pytester.path / "nt-out"
+    monkeypatch.setenv("NARRATIVETRACE_OUTPUT", "1")
+    monkeypatch.setenv("NARRATIVETRACE_OUTPUT_DIR", str(out_dir))
+    pytester.makepyfile(
+        """
+        import pytest
+        from narrativetrace.trace_object import trace_object
+
+        class Inventory:
+            def reserve(self, sku): return True
+
+        class Payment:
+            def charge(self, amount): raise ValueError("card declined")
+
+        class Orders:
+            def save(self, order_id): return order_id
+
+        class Checkout:
+            def __init__(self, inventory, payment, orders):
+                self.inventory, self.payment, self.orders = inventory, payment, orders
+
+            def place_order(self, sku):
+                self.inventory.reserve(sku)
+                self.payment.charge(10)
+                return self.orders.save("ORD-1")
+
+        def test_checkout_charges_the_card(narrative_trace):
+            checkout = Checkout(
+                trace_object(Inventory(), narrative_trace),
+                trace_object(Payment(), narrative_trace),
+                trace_object(Orders(), narrative_trace),
+            )
+            trace_object(checkout, narrative_trace).place_order("sku-1")
+        """
+    )
+
+    result = pytester.runpytest_subprocess()
+
+    result.assert_outcomes(failed=1)
+    result.stdout.fnmatch_lines(
+        ["*Inventory.reserve*", "*Payment.charge*ValueError*card declined*"]
+    )
+    traces = (
+        out_dir
+        / "traces"
+        / "test_a_failing_checkout_test_gets_its_own_narrative_showing_the_failure"
+    )
+    narrative = traces / "test_checkout_charges_the_card.md"
+    text = narrative.read_text(encoding="utf-8")
+    assert "**Result:** FAILED" in text
+    assert "Payment.charge" in text
+    assert "ValueError" in text
+    assert "Orders.save" not in text

{narrativetrace_pytest-0.2.0 → narrativetrace_pytest-0.4.0}/tests/test_structural_plugin.py

@@ -181,3 +181,68 @@ def test_approval_mode_rejects_a_changed_structure_with_a_readable_diff(
     changed.assert_outcomes(passed=1, errors=1)
     changed.stdout.fnmatch_lines(["*Structure changed against the approved trace*"])
     assert next(approved_dir.rglob("*.received.nt")).is_file()
+
+
+_CHECKOUT_COMMON = """
+from narrativetrace.trace_object import trace_object
+
+class Inventory:
+    def reserve(self, sku):
+        return True
+
+class Payment:
+    def charge(self, amount):
+        return "paid"
+
+class Orders:
+    def save(self, order_id):
+        return order_id
+
+class Checkout:
+    def __init__(self, inventory, payment, orders):
+        self.inventory, self.payment, self.orders = inventory, payment, orders
+
+    def place_order(self, sku):
+        self.inventory.reserve(sku)
+%s
+        return self.orders.save("ORD-1")
+
+def test_arithmetic_is_unaffected():
+    assert 1 + 1 == 2
+
+def test_place_order(narrative_trace):
+    checkout = Checkout(
+        trace_object(Inventory(), narrative_trace),
+        trace_object(Payment(), narrative_trace),
+        trace_object(Orders(), narrative_trace),
+    )
+    trace_object(checkout, narrative_trace).place_order("sku-1")
+"""
+_CHECKOUT_BASELINE_SOURCE = _CHECKOUT_COMMON % "        self.payment.charge(10)"
+_CHECKOUT_DROPPED_CHARGE_SOURCE = _CHECKOUT_COMMON % "        pass"
+
+
+def test_approval_mode_names_a_dropped_call_while_the_ordinary_tests_stay_green(
+    pytester: pytest.Pytester, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The recipe's refactoring-review shape: checkout reserves inventory, charges payment and
+    saves the order; a change drops the payment charge and the run must fail naming it."""
+    approved_dir = pytester.path / "approved"
+    monkeypatch.setenv("NARRATIVETRACE_APPROVAL", "true")
+    monkeypatch.setenv("NARRATIVETRACE_APPROVED_DIR", str(approved_dir))
+    pytester.makepyfile(_CHECKOUT_BASELINE_SOURCE)
+    pytester.runpytest_subprocess("-s").assert_outcomes(passed=2, errors=1)
+    received = next(approved_dir.rglob("*.received.nt"))
+    received.replace(received.with_name(received.name.replace(".received.nt", ".approved.nt")))
+    pytester.runpytest_subprocess("-s").assert_outcomes(passed=2)
+
+    pytester.makepyfile(_CHECKOUT_DROPPED_CHARGE_SOURCE)
+    dropped = pytester.runpytest_subprocess("-s")
+
+    dropped.assert_outcomes(passed=2, errors=1)
+    dropped.stdout.fnmatch_lines(
+        [
+            "*Structure changed against the approved trace (-1 call Payment.charge):*",
+            "*-  #1.2 - Payment.charge(amount) *",
+        ]
+    )