From 3286e99bc2b21a412b61e7e0a64ecbcf077c8e26 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Wed, 29 Apr 2026 01:17:15 +0100
Subject: [PATCH] refactor: share docker e2e instance helpers

---
 docs/reference/test.md                 |  2 +-
 scripts/e2e/cron-mcp-cleanup-docker.sh | 63 +++++++------------------
 scripts/e2e/mcp-channels-docker.sh     | 65 ++++++--------------------
 scripts/lib/docker-e2e-package.sh      |  2 +-
 scripts/lib/openclaw-e2e-instance.sh   | 56 ++++++++++++++++++++++
 5 files changed, 89 insertions(+), 99 deletions(-)
 create mode 100644 scripts/lib/openclaw-e2e-instance.sh

diff --git a/docs/reference/test.md b/docs/reference/test.md
index 38bfe7a19a8..db52c06a23d 100644
--- a/docs/reference/test.md
+++ b/docs/reference/test.md
@@ -16,7 +16,7 @@ title: "Tests"
 - `pnpm check:changed`: runs the smart changed check gate for the diff against `origin/main`. It runs typecheck, lint, and guard commands for the affected architectural lanes, but does not run Vitest tests. Use `pnpm test:changed` or explicit `pnpm test <target>` for test proof.
 - `pnpm test`: routes explicit file/directory targets through scoped Vitest lanes. Untargeted runs use fixed shard groups and expand to leaf configs for local parallel execution; the extension group always expands to the per-extension shard configs instead of one giant root-project process.
 - Test wrapper runs end with a short `[test] passed|failed|skipped ... in ...` summary. Vitest's own duration line stays the per-shard detail.
-- Shared OpenClaw test state: use `src/test-utils/openclaw-test-state.ts` from Vitest when a test needs an isolated `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, config fixture, workspace, agent dir, or auth-profile store. For process-level E2E tests that need a running Gateway, use `test/helpers/openclaw-test-instance.ts` so state, config, CLI env, gateway startup, log capture, and cleanup stay together. Docker/Bash E2E lanes that source `scripts/lib/docker-e2e-image.sh` can pass `docker_e2e_test_state_shell_b64 <label> <scenario>` into the container and `eval` the decoded snippet there; multi-home scripts can pass `docker_e2e_test_state_function_b64` and call `openclaw_test_state_create <label> <scenario>` in each flow. Lower-level callers can use `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` for an in-container shell snippet, or `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` for a sourceable host env file. The `--` before `create` keeps newer Node runtimes from treating `--env-file` as a Node flag.
+- Shared OpenClaw test state: use `src/test-utils/openclaw-test-state.ts` from Vitest when a test needs an isolated `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, config fixture, workspace, agent dir, or auth-profile store. For process-level E2E tests that need a running Gateway, use `test/helpers/openclaw-test-instance.ts` so state, config, CLI env, gateway startup, log capture, and cleanup stay together. Docker/Bash E2E lanes that source `scripts/lib/docker-e2e-image.sh` can pass `docker_e2e_test_state_shell_b64 <label> <scenario>` into the container and decode it with `scripts/lib/openclaw-e2e-instance.sh`; multi-home scripts can pass `docker_e2e_test_state_function_b64` and call `openclaw_test_state_create <label> <scenario>` in each flow. Lower-level callers can use `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` for an in-container shell snippet, or `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` for a sourceable host env file. The `--` before `create` keeps newer Node runtimes from treating `--env-file` as a Node flag. Docker/Bash lanes that launch a Gateway can source `scripts/lib/openclaw-e2e-instance.sh` inside the container for entrypoint resolution, mock OpenAI startup, Gateway readiness, log dumps, and process cleanup.
 - Full, extension, and include-pattern shard runs update local timing data in `.artifacts/vitest-shard-timings.json`; later whole-config runs use those timings to balance slow and fast shards. Include-pattern CI shards append the shard name to the timing key, which keeps filtered shard timings visible without replacing whole-config timing data. Set `OPENCLAW_TEST_PROJECTS_TIMINGS=0` to ignore the local timing artifact.
 - Selected `plugin-sdk` and `commands` test files now route through dedicated light lanes that keep only `test/setup.ts`, leaving runtime-heavy cases on their existing lanes.
 - Source files with sibling tests map to that sibling before falling back to wider directory globs. Helper edits under `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers`, and `src/plugins/contracts` use a local import graph to run importing tests instead of broad-running every shard when the dependency path is precise.
diff --git a/scripts/e2e/cron-mcp-cleanup-docker.sh b/scripts/e2e/cron-mcp-cleanup-docker.sh
index 43cba93d8e7..5dc76c0306b 100644
--- a/scripts/e2e/cron-mcp-cleanup-docker.sh
+++ b/scripts/e2e/cron-mcp-cleanup-docker.sh
@@ -40,68 +40,37 @@ docker run --rm \
   "${DOCKER_E2E_HARNESS_ARGS[@]}" \
   "$IMAGE_NAME" \
   bash -lc "set -euo pipefail
-    eval \"\$(printf '%s' \"\${OPENCLAW_TEST_STATE_SCRIPT_B64:?missing OPENCLAW_TEST_STATE_SCRIPT_B64}\" | base64 -d)\"
-    entry=dist/index.mjs
-    [ -f \"\$entry\" ] || entry=dist/index.js
+    source scripts/lib/openclaw-e2e-instance.sh
+    openclaw_e2e_eval_test_state_from_b64 \"\${OPENCLAW_TEST_STATE_SCRIPT_B64:?missing OPENCLAW_TEST_STATE_SCRIPT_B64}\"
+    entry=\"\$(openclaw_e2e_resolve_entrypoint)\"
     export MOCK_PORT=44081
     export SUCCESS_MARKER=OPENCLAW_CRON_MCP_CLEANUP_OK
     export MOCK_REQUEST_LOG=/tmp/openclaw-cron-mock-openai-requests.jsonl
     export OPENCLAW_DOCKER_OPENAI_BASE_URL=\"http://127.0.0.1:\$MOCK_PORT/v1\"
-    node scripts/e2e/mock-openai-server.mjs >/tmp/cron-mcp-cleanup-mock-openai.log 2>&1 &
-    mock_pid=\$!
-    tsx scripts/e2e/cron-mcp-cleanup-seed.ts >/tmp/cron-mcp-cleanup-seed.log
-    node \"\$entry\" gateway --port $PORT --bind loopback --allow-unconfigured >/tmp/cron-mcp-cleanup-gateway.log 2>&1 &
-    gateway_pid=\$!
-    stop_process() {
-      pid=\"\$1\"
-      kill \"\$pid\" >/dev/null 2>&1 || true
-      for _ in \$(seq 1 40); do
-        if ! kill -0 \"\$pid\" >/dev/null 2>&1; then
-          wait \"\$pid\" >/dev/null 2>&1 || true
-          return
-        fi
-        sleep 0.25
-      done
-      kill -9 \"\$pid\" >/dev/null 2>&1 || true
-      wait \"\$pid\" >/dev/null 2>&1 || true
-    }
+    mock_pid=\"\$(openclaw_e2e_start_mock_openai \"\$MOCK_PORT\" /tmp/cron-mcp-cleanup-mock-openai.log)\"
+    gateway_pid=
     cleanup_inner() {
-      stop_process \"\$mock_pid\"
-      stop_process \"\$gateway_pid\"
+      openclaw_e2e_stop_process \"\${gateway_pid:-}\"
+      openclaw_e2e_stop_process \"\${mock_pid:-}\"
     }
     dump_gateway_log_on_error() {
       status=\$?
       if [ \"\$status\" -ne 0 ]; then
-        tail -n 80 /tmp/cron-mcp-cleanup-gateway.log 2>/dev/null || true
-        cat /tmp/cron-mcp-cleanup-seed.log 2>/dev/null || true
-        cat /tmp/cron-mcp-cleanup-mock-openai.log 2>/dev/null || true
-        cat \"\$MOCK_REQUEST_LOG\" 2>/dev/null || true
+        openclaw_e2e_dump_logs \
+          /tmp/cron-mcp-cleanup-gateway.log \
+          /tmp/cron-mcp-cleanup-seed.log \
+          /tmp/cron-mcp-cleanup-mock-openai.log \
+          \"\$MOCK_REQUEST_LOG\"
       fi
       cleanup_inner
       exit \"\$status\"
     }
     trap cleanup_inner EXIT
     trap dump_gateway_log_on_error ERR
-    for _ in \$(seq 1 80); do
-      if node -e \"fetch('http://127.0.0.1:' + process.env.MOCK_PORT + '/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\"; then
-        break
-      fi
-      sleep 0.1
-    done
-    node -e \"fetch('http://127.0.0.1:' + process.env.MOCK_PORT + '/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\"
-    gateway_ready=0
-    for _ in \$(seq 1 300); do
-      if grep -q '\[gateway\] ready' /tmp/cron-mcp-cleanup-gateway.log 2>/dev/null; then
-        gateway_ready=1
-        break
-      fi
-      sleep 0.25
-    done
-    if [ \"\$gateway_ready\" -ne 1 ]; then
-      echo \"Gateway did not become ready\"
-      tail -n 120 /tmp/cron-mcp-cleanup-gateway.log 2>/dev/null || true
-      exit 1
-    fi
+    openclaw_e2e_wait_mock_openai \"\$MOCK_PORT\"
+    tsx scripts/e2e/cron-mcp-cleanup-seed.ts >/tmp/cron-mcp-cleanup-seed.log
+    gateway_pid=\"\$(openclaw_e2e_start_gateway \"\$entry\" $PORT /tmp/cron-mcp-cleanup-gateway.log)\"
+    openclaw_e2e_wait_gateway_ready \"\$gateway_pid\" /tmp/cron-mcp-cleanup-gateway.log 300
     tsx scripts/e2e/cron-mcp-cleanup-docker-client.ts
   " >"$CLIENT_LOG" 2>&1
 status=${PIPESTATUS[0]}
diff --git a/scripts/e2e/mcp-channels-docker.sh b/scripts/e2e/mcp-channels-docker.sh
index 94f11930f0b..5f5a11a77c6 100644
--- a/scripts/e2e/mcp-channels-docker.sh
+++ b/scripts/e2e/mcp-channels-docker.sh
@@ -40,69 +40,34 @@ docker run --rm \
   "${DOCKER_E2E_HARNESS_ARGS[@]}" \
   "$IMAGE_NAME" \
   bash -lc "set -euo pipefail
-    eval \"\$(printf '%s' \"\${OPENCLAW_TEST_STATE_SCRIPT_B64:?missing OPENCLAW_TEST_STATE_SCRIPT_B64}\" | base64 -d)\"
-    entry=dist/index.mjs
-    [ -f \"\$entry\" ] || entry=dist/index.js
+    source scripts/lib/openclaw-e2e-instance.sh
+    openclaw_e2e_eval_test_state_from_b64 \"\${OPENCLAW_TEST_STATE_SCRIPT_B64:?missing OPENCLAW_TEST_STATE_SCRIPT_B64}\"
+    entry=\"\$(openclaw_e2e_resolve_entrypoint)\"
     mock_port=44081
     export OPENCLAW_DOCKER_OPENAI_BASE_URL=\"http://127.0.0.1:\$mock_port/v1\"
-    MOCK_PORT=\"\$mock_port\" node scripts/e2e/mock-openai-server.mjs >/tmp/mcp-channels-mock-openai.log 2>&1 &
-    mock_pid=\$!
-    for _ in \$(seq 1 80); do
-      if node -e \"fetch('http://127.0.0.1:' + process.argv[1] + '/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\" \"\$mock_port\"; then
-        break
-      fi
-      sleep 0.1
-    done
-    node -e \"fetch('http://127.0.0.1:' + process.argv[1] + '/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\" \"\$mock_port\"
-    tsx scripts/e2e/mcp-channels-seed.ts >/tmp/mcp-channels-seed.log
-    node \"\$entry\" gateway --port $PORT --bind loopback --allow-unconfigured >/tmp/mcp-channels-gateway.log 2>&1 &
-    gateway_pid=\$!
-    stop_process() {
-      pid=\"\$1\"
-      kill \"\$pid\" >/dev/null 2>&1 || true
-      for _ in \$(seq 1 40); do
-        if ! kill -0 \"\$pid\" >/dev/null 2>&1; then
-          wait \"\$pid\" >/dev/null 2>&1 || true
-          return
-        fi
-        sleep 0.25
-      done
-      kill -9 \"\$pid\" >/dev/null 2>&1 || true
-      wait \"\$pid\" >/dev/null 2>&1 || true
-    }
+    mock_pid=\"\$(openclaw_e2e_start_mock_openai \"\$mock_port\" /tmp/mcp-channels-mock-openai.log)\"
+    gateway_pid=
     cleanup_inner() {
-      stop_process \"\$gateway_pid\"
-      stop_process \"\$mock_pid\"
+      openclaw_e2e_stop_process \"\${gateway_pid:-}\"
+      openclaw_e2e_stop_process \"\${mock_pid:-}\"
     }
     dump_gateway_log_on_error() {
       status=\$?
       if [ \"\$status\" -ne 0 ]; then
-        tail -n 80 /tmp/mcp-channels-gateway.log 2>/dev/null || true
+        openclaw_e2e_dump_logs \
+          /tmp/mcp-channels-gateway.log \
+          /tmp/mcp-channels-seed.log \
+          /tmp/mcp-channels-mock-openai.log
       fi
       cleanup_inner
       exit \"\$status\"
     }
     trap cleanup_inner EXIT
     trap dump_gateway_log_on_error ERR
-    gateway_ready=0
-    for _ in \$(seq 1 480); do
-      if ! kill -0 \"\$gateway_pid\" >/dev/null 2>&1; then
-        echo \"Gateway exited before becoming ready\"
-        wait \"\$gateway_pid\" || true
-        tail -n 120 /tmp/mcp-channels-gateway.log 2>/dev/null || true
-        exit 1
-      fi
-      if grep -q '\[gateway\] ready' /tmp/mcp-channels-gateway.log 2>/dev/null; then
-        gateway_ready=1
-        break
-      fi
-      sleep 0.25
-    done
-    if [ \"\$gateway_ready\" -ne 1 ]; then
-      echo \"Gateway did not become ready\"
-      tail -n 120 /tmp/mcp-channels-gateway.log 2>/dev/null || true
-      exit 1
-    fi
+    openclaw_e2e_wait_mock_openai \"\$mock_port\"
+    tsx scripts/e2e/mcp-channels-seed.ts >/tmp/mcp-channels-seed.log
+    gateway_pid=\"\$(openclaw_e2e_start_gateway \"\$entry\" $PORT /tmp/mcp-channels-gateway.log)\"
+    openclaw_e2e_wait_gateway_ready \"\$gateway_pid\" /tmp/mcp-channels-gateway.log 480
     tsx scripts/e2e/mcp-channels-docker-client.ts
   " >"$CLIENT_LOG" 2>&1
 status=${PIPESTATUS[0]}
diff --git a/scripts/lib/docker-e2e-package.sh b/scripts/lib/docker-e2e-package.sh
index 6b25f25a564..6f699d31b29 100644
--- a/scripts/lib/docker-e2e-package.sh
+++ b/scripts/lib/docker-e2e-package.sh
@@ -60,5 +60,5 @@ docker_e2e_package_mount_args() {
 }
 
 docker_e2e_harness_mount_args() {
-  DOCKER_E2E_HARNESS_ARGS=(-v "$ROOT_DIR/scripts/e2e:/app/scripts/e2e:ro")
+  DOCKER_E2E_HARNESS_ARGS=(-v "$ROOT_DIR/scripts/e2e:/app/scripts/e2e:ro" -v "$ROOT_DIR/scripts/lib:/app/scripts/lib:ro")
 }
diff --git a/scripts/lib/openclaw-e2e-instance.sh b/scripts/lib/openclaw-e2e-instance.sh
new file mode 100644
index 00000000000..99a4b6f6263
--- /dev/null
+++ b/scripts/lib/openclaw-e2e-instance.sh
@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Shared in-container lifecycle helpers for Docker/Bash E2E lanes.
+openclaw_e2e_eval_test_state_from_b64() { eval "$(printf '%s' "${1:?missing OpenClaw test-state script}" | base64 -d)"; }
+openclaw_e2e_resolve_entrypoint() {
+  local entry
+  for entry in dist/index.mjs dist/index.js; do
+    [ -f "$entry" ] && { printf '%s\n' "$entry"; return 0; }
+  done
+  echo "OpenClaw entrypoint not found under dist/" >&2
+  return 1
+}
+openclaw_e2e_stop_process() {
+  local pid="${1:-}" _
+  [ -n "$pid" ] || return 0
+  kill "$pid" >/dev/null 2>&1 || true
+  for _ in $(seq 1 40); do
+    ! kill -0 "$pid" >/dev/null 2>&1 && { wait "$pid" >/dev/null 2>&1 || true; return 0; }
+    sleep 0.25
+  done
+  kill -9 "$pid" >/dev/null 2>&1 || true
+  wait "$pid" >/dev/null 2>&1 || true
+}
+openclaw_e2e_start_mock_openai() { MOCK_PORT="$1" node scripts/e2e/mock-openai-server.mjs >"$2" 2>&1 & printf '%s\n' "$!"; }
+openclaw_e2e_wait_mock_openai() {
+  local port="$1" attempts="${2:-80}" _
+  local probe="fetch('http://127.0.0.1:' + process.argv[1] + '/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+  for _ in $(seq 1 "$attempts"); do
+    node -e "$probe" "$port" && return 0
+    sleep 0.1
+  done
+  node -e "$probe" "$port"
+}
+openclaw_e2e_start_gateway() { node "$1" gateway --port "$2" --bind loopback --allow-unconfigured >"$3" 2>&1 & printf '%s\n' "$!"; }
+openclaw_e2e_wait_gateway_ready() {
+  local pid="$1" log="$2" attempts="${3:-300}" _
+  for _ in $(seq 1 "$attempts"); do
+    ! kill -0 "$pid" >/dev/null 2>&1 && {
+      echo "Gateway exited before becoming ready"
+      wait "$pid" || true
+      tail -n 120 "$log" 2>/dev/null || true
+      return 1
+    }
+    grep -q '\[gateway\] ready' "$log" 2>/dev/null && return 0
+    sleep 0.25
+  done
+  echo "Gateway did not become ready"
+  tail -n 120 "$log" 2>/dev/null || true
+  return 1
+}
+openclaw_e2e_dump_logs() {
+  local path
+  for path in "$@"; do
+    [ -f "$path" ] || continue
+    echo "--- $path ---"; tail -n "${OPENCLAW_E2E_LOG_TAIL_LINES:-120}" "$path" || true
+  done
+}