From edb391200c948f31c46f79f646cf56c2d48fca7d Mon Sep 17 00:00:00 2001
From: Ivan Kosyanenko <apgreydd@gmail.com>
Date: Fri, 27 Feb 2026 20:16:08 +0300
Subject: [PATCH] feat(integration): add local harness to run live contract
 tests

---
 CONTRIBUTING.md              |  6 ++++
 README.md                    |  6 ++++
 integration/README.md        | 12 ++++++++
 scripts/integration-local.sh | 60 ++++++++++++++++++++++++++++++++++++
 4 files changed, 84 insertions(+)
 create mode 100755 scripts/integration-local.sh

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e3ceebc..2a04383 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -54,6 +54,12 @@ Live contract tests use build tag `integration`.
 SIMPLEX_WS_URL=ws://localhost:5225 go test -tags=integration ./integration/... -v
 ```
 
+For local reproducible runs, use:
+
+```bash
+./scripts/integration-local.sh
+```
+
 Additional fixture variables are documented in `integration/README.md`.
 
 ## Pull requests
diff --git a/README.md b/README.md
index 88364f2..a869e77 100644
--- a/README.md
+++ b/README.md
@@ -173,6 +173,12 @@ Run live contract tests against a real SimpleX websocket API:
 SIMPLEX_WS_URL=ws://localhost:5225 go test -tags=integration ./integration/... -v
 ```
 
+Local harness (auto-start `simplex-chat`, run integration tests, cleanup):
+
+```bash
+./scripts/integration-local.sh
+```
+
 Optional vulnerability scan:
 
 ```bash
diff --git a/integration/README.md b/integration/README.md
index 3528723..f6a7b88 100644
--- a/integration/README.md
+++ b/integration/README.md
@@ -16,6 +16,18 @@ simplex-chat -p 5225
 SIMPLEX_WS_URL=ws://localhost:5225 go test -tags=integration ./integration/... -v
 ```
 
+Or use local harness (starts `simplex-chat`, waits for websocket, runs tests, stops process):
+
+```bash
+./scripts/integration-local.sh
+```
+
+Use existing websocket instead of starting local process:
+
+```bash
+SIMPLEX_WS_URL=ws://localhost:5225 ./scripts/integration-local.sh
+```
+
 ## Optional fixture env vars for extended flows
 
 Set these to enable additional contract tests:
diff --git a/scripts/integration-local.sh b/scripts/integration-local.sh
new file mode 100755
index 0000000..8df8738
--- /dev/null
+++ b/scripts/integration-local.sh
@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT_DIR"
+
+WS_URL="${SIMPLEX_WS_URL:-}"
+STARTED_PID=""
+LOG_FILE=""
+
+cleanup() {
+  if [[ -n "$STARTED_PID" ]]; then
+    if kill -0 "$STARTED_PID" >/dev/null 2>&1; then
+      kill "$STARTED_PID" >/dev/null 2>&1 || true
+      wait "$STARTED_PID" >/dev/null 2>&1 || true
+    fi
+  fi
+}
+trap cleanup EXIT INT TERM
+
+if [[ -z "$WS_URL" ]]; then
+  SIMPLEX_BIN="${SIMPLEX_BIN:-simplex-chat}"
+  SIMPLEX_WS_PORT="${SIMPLEX_WS_PORT:-5225}"
+  WS_URL="ws://localhost:${SIMPLEX_WS_PORT}"
+  LOG_FILE="${SIMPLEX_LOG_FILE:-/tmp/go-simplex-integration-${SIMPLEX_WS_PORT}.log}"
+
+  if ! command -v "$SIMPLEX_BIN" >/dev/null 2>&1; then
+    echo "[integration] error: '$SIMPLEX_BIN' not found" >&2
+    echo "[integration] install SimpleX CLI or set SIMPLEX_BIN/SIMPLEX_WS_URL" >&2
+    exit 1
+  fi
+
+  echo "[integration] starting $SIMPLEX_BIN -p $SIMPLEX_WS_PORT"
+  "$SIMPLEX_BIN" -p "$SIMPLEX_WS_PORT" >"$LOG_FILE" 2>&1 &
+  STARTED_PID="$!"
+
+  echo "[integration] waiting for websocket at $WS_URL"
+  ready=0
+  for _ in $(seq 1 60); do
+    if go run ./cmd/simplex-smoke --ws "$WS_URL" >/dev/null 2>&1; then
+      ready=1
+      break
+    fi
+    sleep 1
+  done
+
+  if [[ "$ready" -ne 1 ]]; then
+    echo "[integration] websocket was not ready in time: $WS_URL" >&2
+    if [[ -n "$LOG_FILE" && -f "$LOG_FILE" ]]; then
+      echo "[integration] last simplex log lines:" >&2
+      tail -n 50 "$LOG_FILE" >&2 || true
+    fi
+    exit 1
+  fi
+fi
+
+export SIMPLEX_WS_URL="$WS_URL"
+
+echo "[integration] running tests against $SIMPLEX_WS_URL"
+go test -tags=integration ./integration/... -v "$@"