feat(integration): add local harness for live contract tests

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

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

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:

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 "$@"