From 273849574de1d826638c6fe2e6a840ead1c25867 Mon Sep 17 00:00:00 2001
From: Void Freud <246163318+voidfreud@users.noreply.github.com>
Date: Tue, 14 Apr 2026 12:36:02 +0300
Subject: [PATCH] feat(#387): standalone integration-smoke runner script

Adds scripts/run-integration-smoke.sh so the integration lane can be
driven externally: start it, walk away, get a JSON artifact. Supports
ITA_DISABLE_BACKGROUND=1 for the Lap B foreground comparison (T36), and
falls back to JUnit XML if pytest-json-report isn't importable.

Also adds pytest-json-report to the [dev] optional-dependencies so the
preferred JSON path works out of the box under `uv run --extra dev`.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 pyproject.toml                   |  1 +
 scripts/README.md                | 23 +++++++++++++
 scripts/run-integration-smoke.sh | 58 ++++++++++++++++++++++++++++++++
 3 files changed, 82 insertions(+)
 create mode 100644 scripts/README.md
 create mode 100755 scripts/run-integration-smoke.sh

diff --git a/pyproject.toml b/pyproject.toml
index e16750e..08ea86c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -15,6 +15,7 @@ dev = [
 	"pytest-xdist",
 	"pytest-timeout",
 	"pytest-benchmark",
+	"pytest-json-report",
 	"jsonschema",
 	"ruff",
 	"mutmut",
diff --git a/scripts/README.md b/scripts/README.md
new file mode 100644
index 0000000..0e6a2e3
--- /dev/null
+++ b/scripts/README.md
@@ -0,0 +1,23 @@
+# scripts/
+
+Operator-facing helpers. Run from repo root.
+
+## run-integration-smoke.sh
+
+Drive the integration lane externally so you can start it, walk away, and
+come back to a structured artifact. See issue #387.
+
+```
+# Prereq: iTerm2 running, idle terminal window, dedicated if possible.
+
+# Lap A (background, default — fixtures stay off-focus):
+bash scripts/run-integration-smoke.sh
+
+# Lap B (foreground, for comparison per T36):
+ITA_DISABLE_BACKGROUND=1 bash scripts/run-integration-smoke.sh
+
+# Artifact: /tmp/ita-integration-<ts>.json (pytest-json-report)
+#           or  /tmp/ita-integration-<ts>.xml (junit fallback)
+```
+
+Exits non-zero on test failures. Artifact path is echoed at end.
diff --git a/scripts/run-integration-smoke.sh b/scripts/run-integration-smoke.sh
new file mode 100755
index 0000000..2d4a18f
--- /dev/null
+++ b/scripts/run-integration-smoke.sh
@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# run-integration-smoke.sh — drive the integration lane externally.
+#
+# Prereq: iTerm2 running, idle terminal window, dedicated if possible.
+#
+# Lap A (background, default):
+#   bash scripts/run-integration-smoke.sh
+#
+# Lap B (foreground, for comparison per T36):
+#   ITA_DISABLE_BACKGROUND=1 bash scripts/run-integration-smoke.sh
+#
+# Artifact: /tmp/ita-integration-<ts>.json (pytest-json-report)
+#           or  /tmp/ita-integration-<ts>.xml (junit fallback)
+#
+# Issue: #387
+set -euo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+cd "$REPO_ROOT"
+
+TS="$(date +%Y%m%d-%H%M%S)"
+JSON_ARTIFACT="/tmp/ita-integration-${TS}.json"
+XML_ARTIFACT="/tmp/ita-integration-${TS}.xml"
+
+# Lap B support: let the caller force foreground mode so the fixtures
+# actually create visible tabs/windows for the human-comparison lap.
+if [ "${ITA_DISABLE_BACKGROUND:-0}" = "1" ]; then
+	unset ITA_DEFAULT_BACKGROUND
+	echo "[smoke] ITA_DEFAULT_BACKGROUND unset (Lap B, foreground)"
+fi
+
+# Prefer pytest-json-report when available; fall back to JUnit XML otherwise.
+if uv run --extra dev python -c "import pytest_jsonreport" >/dev/null 2>&1; then
+	echo "[smoke] using pytest-json-report -> ${JSON_ARTIFACT}"
+	ARTIFACT="$JSON_ARTIFACT"
+	set +e
+	uv run --extra dev pytest -m integration --timeout=60 \
+		--json-report --json-report-file="$JSON_ARTIFACT"
+	rc=$?
+	set -e
+else
+	echo "[smoke] pytest-json-report not importable; falling back to JUnit XML -> ${XML_ARTIFACT}"
+	ARTIFACT="$XML_ARTIFACT"
+	set +e
+	uv run --extra dev pytest -m integration --timeout=60 \
+		--junitxml="$XML_ARTIFACT"
+	rc=$?
+	set -e
+	# Minimal post-process summary so the operator sees pass/fail counts
+	# without reaching for xmlstarlet.
+	if [ -f "$XML_ARTIFACT" ]; then
+		grep -Eo 'testsuite[^>]*(tests|failures|errors|skipped)="[0-9]+"' "$XML_ARTIFACT" \
+			| head -5 || true
+	fi
+fi
+
+echo "[smoke] artifact: ${ARTIFACT}"
+exit "$rc"