From 3f780bb27da18c464f1393f7e78b5b73216a3d7c Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Tue, 28 Apr 2026 18:47:41 +0100
Subject: [PATCH] test: share Docker test-state wrapper

---
 docs/reference/test.md                        |  2 +-
 .../agents-delete-shared-workspace-docker.sh  |  8 +-----
 ...bundled-plugin-install-uninstall-docker.sh |  9 ++++---
 scripts/e2e/doctor-install-switch-docker.sh   | 12 ++++-----
 .../e2e/npm-onboard-channel-agent-docker.sh   |  8 +-----
 scripts/e2e/openai-image-auth-docker.sh       |  5 ++--
 scripts/lib/docker-e2e-image.sh               | 16 ++++++++++++
 scripts/lib/docker-e2e-scenarios.mjs          |  7 +++++-
 test/scripts/docker-e2e-plan.test.ts          | 25 ++++++++++++++++++-
 9 files changed, 64 insertions(+), 28 deletions(-)

diff --git a/docs/reference/test.md b/docs/reference/test.md
index a66bb141c9b..07eb930204d 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. Docker/Bash E2E lanes 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. 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.
 - 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/agents-delete-shared-workspace-docker.sh b/scripts/e2e/agents-delete-shared-workspace-docker.sh
index fb65ca58e8c..521aad58190 100644
--- a/scripts/e2e/agents-delete-shared-workspace-docker.sh
+++ b/scripts/e2e/agents-delete-shared-workspace-docker.sh
@@ -7,13 +7,7 @@ source "$ROOT_DIR/scripts/lib/docker-e2e-image.sh"
 IMAGE_NAME="$(docker_e2e_resolve_image "openclaw-agents-delete-shared-workspace-e2e:local" OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE)"
 SKIP_BUILD="${OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD:-0}"
 DOCKER_COMMAND_TIMEOUT="${OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_DOCKER_COMMAND_TIMEOUT:-300s}"
-OPENCLAW_TEST_STATE_SCRIPT_B64="$(
-  node "$ROOT_DIR/scripts/lib/openclaw-test-state.mjs" shell \
-    --label agents-delete-shared-workspace \
-    --scenario empty \
-    | base64 \
-    | tr -d '\n'
-)"
+OPENCLAW_TEST_STATE_SCRIPT_B64="$(docker_e2e_test_state_shell_b64 agents-delete-shared-workspace empty)"
 
 docker_cmd() {
   if command -v timeout >/dev/null 2>&1; then
diff --git a/scripts/e2e/bundled-plugin-install-uninstall-docker.sh b/scripts/e2e/bundled-plugin-install-uninstall-docker.sh
index a5abd92d349..423c9b049f5 100755
--- a/scripts/e2e/bundled-plugin-install-uninstall-docker.sh
+++ b/scripts/e2e/bundled-plugin-install-uninstall-docker.sh
@@ -6,8 +6,12 @@ source "$ROOT_DIR/scripts/lib/docker-e2e-image.sh"
 IMAGE_NAME="$(docker_e2e_resolve_image "openclaw-bundled-plugin-install-uninstall-e2e" OPENCLAW_BUNDLED_PLUGIN_INSTALL_UNINSTALL_E2E_IMAGE)"
 
 docker_e2e_build_or_reuse "$IMAGE_NAME" bundled-plugin-install-uninstall
+OPENCLAW_TEST_STATE_SCRIPT_B64="$(docker_e2e_test_state_shell_b64 bundled-plugin-install-uninstall empty)"
 
-DOCKER_ENV_ARGS=(-e COREPACK_ENABLE_DOWNLOAD_PROMPT=0)
+DOCKER_ENV_ARGS=(
+  -e COREPACK_ENABLE_DOWNLOAD_PROMPT=0
+  -e "OPENCLAW_TEST_STATE_SCRIPT_B64=$OPENCLAW_TEST_STATE_SCRIPT_B64"
+)
 for env_name in \
   OPENCLAW_BUNDLED_PLUGIN_SWEEP_TOTAL \
   OPENCLAW_BUNDLED_PLUGIN_SWEEP_INDEX \
@@ -34,8 +38,7 @@ else
 fi
 export OPENCLAW_ENTRY
 
-home_dir=$(mktemp -d "/tmp/openclaw-bundled-plugin-sweep.XXXXXX")
-export HOME="$home_dir"
+eval "$(printf "%s" "${OPENCLAW_TEST_STATE_SCRIPT_B64:?missing OPENCLAW_TEST_STATE_SCRIPT_B64}" | base64 -d)"
 
 node - <<'NODE' > /tmp/bundled-plugin-sweep-ids
 const fs = require("node:fs");
diff --git a/scripts/e2e/doctor-install-switch-docker.sh b/scripts/e2e/doctor-install-switch-docker.sh
index bfd3c1ff49b..943ae5d18bf 100755
--- a/scripts/e2e/doctor-install-switch-docker.sh
+++ b/scripts/e2e/doctor-install-switch-docker.sh
@@ -10,16 +10,19 @@ IMAGE_NAME="$(docker_e2e_resolve_image "openclaw-doctor-install-switch-e2e" OPEN
 PACKAGE_TGZ="$(docker_e2e_prepare_package_tgz doctor-switch "${OPENCLAW_CURRENT_PACKAGE_TGZ:-}")"
 # Bare lanes mount the package artifact instead of baking app sources into the image.
 docker_e2e_package_mount_args "$PACKAGE_TGZ"
+OPENCLAW_TEST_STATE_FUNCTION_B64="$(docker_e2e_test_state_function_b64)"
 
 docker_e2e_build_or_reuse "$IMAGE_NAME" doctor-switch "$ROOT_DIR/scripts/e2e/Dockerfile" "$ROOT_DIR" "bare"
 
 echo "Running doctor install switch E2E..."
 docker run --rm \
   -e COREPACK_ENABLE_DOWNLOAD_PROMPT=0 \
+  -e "OPENCLAW_TEST_STATE_FUNCTION_B64=$OPENCLAW_TEST_STATE_FUNCTION_B64" \
   "${DOCKER_E2E_PACKAGE_ARGS[@]}" \
   "$IMAGE_NAME" \
   bash -lc '
   set -euo pipefail
+  eval "$(printf "%s" "${OPENCLAW_TEST_STATE_FUNCTION_B64:?missing OPENCLAW_TEST_STATE_FUNCTION_B64}" | base64 -d)"
 
   # Keep logs focused; the npm global install step can emit noisy deprecation warnings.
   export npm_config_loglevel=error
@@ -215,8 +218,7 @@ NODE
     local command_timeout="${OPENCLAW_DOCKER_DOCTOR_SWITCH_COMMAND_TIMEOUT:-300s}"
 
     echo "== Flow: $name =="
-    home_dir=$(mktemp -d "/tmp/openclaw-switch-${name}.XXXXXX")
-    export HOME="$home_dir"
+    openclaw_test_state_create "switch-${name}" empty
     export USER="testuser"
 
     if ! timeout "$command_timeout" bash -c "$install_cmd" >"$install_log" 2>&1; then
@@ -262,8 +264,7 @@ NODE
     local command_timeout="${OPENCLAW_DOCKER_DOCTOR_SWITCH_COMMAND_TIMEOUT:-300s}"
 
     echo "== Flow: $name =="
-    home_dir=$(mktemp -d "/tmp/openclaw-switch-${name}.XXXXXX")
-    export HOME="$home_dir"
+    openclaw_test_state_create "switch-${name}" empty
     export USER="testuser"
 
     unit_path="$HOME/.config/systemd/user/openclaw-gateway.service"
@@ -303,8 +304,7 @@ NODE
     local command_timeout="${OPENCLAW_DOCKER_DOCTOR_SWITCH_COMMAND_TIMEOUT:-300s}"
 
     echo "== Flow: $name =="
-    home_dir=$(mktemp -d "/tmp/openclaw-switch-${name}.XXXXXX")
-    export HOME="$home_dir"
+    openclaw_test_state_create "switch-${name}" empty
     export USER="testuser"
     mkdir -p "$HOME/.local/bin"
     local wrapper="$HOME/.local/bin/openclaw-wrapper"
diff --git a/scripts/e2e/npm-onboard-channel-agent-docker.sh b/scripts/e2e/npm-onboard-channel-agent-docker.sh
index 7205d3fa0e6..ed55221e5bf 100644
--- a/scripts/e2e/npm-onboard-channel-agent-docker.sh
+++ b/scripts/e2e/npm-onboard-channel-agent-docker.sh
@@ -40,13 +40,7 @@ prepare_package_tgz
 docker_e2e_package_mount_args "$PACKAGE_TGZ"
 docker_e2e_harness_mount_args
 run_log="$(docker_e2e_run_log npm-onboard-channel-agent)"
-OPENCLAW_TEST_STATE_SCRIPT_B64="$(
-  node "$ROOT_DIR/scripts/lib/openclaw-test-state.mjs" shell \
-    --label npm-onboard-channel-agent \
-    --scenario empty \
-    | base64 \
-    | tr -d '\n'
-)"
+OPENCLAW_TEST_STATE_SCRIPT_B64="$(docker_e2e_test_state_shell_b64 npm-onboard-channel-agent empty)"
 
 echo "Running npm tarball onboard/channel/agent Docker E2E ($CHANNEL)..."
 if ! docker run --rm \
diff --git a/scripts/e2e/openai-image-auth-docker.sh b/scripts/e2e/openai-image-auth-docker.sh
index f2b22cb1b62..d14b2986426 100644
--- a/scripts/e2e/openai-image-auth-docker.sh
+++ b/scripts/e2e/openai-image-auth-docker.sh
@@ -11,17 +11,18 @@ SKIP_BUILD="${OPENCLAW_OPENAI_IMAGE_AUTH_E2E_SKIP_BUILD:-0}"
 
 docker_e2e_build_or_reuse "$IMAGE_NAME" openai-image-auth "$ROOT_DIR/scripts/e2e/Dockerfile" "$ROOT_DIR" "" "$SKIP_BUILD"
 docker_e2e_harness_mount_args
+OPENCLAW_TEST_STATE_SCRIPT_B64="$(docker_e2e_test_state_shell_b64 openai-image-auth empty)"
 
 echo "Running OpenAI image auth Docker E2E..."
 # Harness files are mounted read-only; the app under test comes from /app/dist.
 run_logged openai-image-auth docker run --rm \
   -e "OPENAI_API_KEY=sk-openclaw-image-auth-e2e" \
   -e "OPENCLAW_QA_ALLOW_LOCAL_IMAGE_PROVIDER=1" \
+  -e "OPENCLAW_TEST_STATE_SCRIPT_B64=$OPENCLAW_TEST_STATE_SCRIPT_B64" \
   "${DOCKER_E2E_HARNESS_ARGS[@]}" \
   -i "$IMAGE_NAME" bash -lc '
 set -euo pipefail
-export HOME="$(mktemp -d "/tmp/openclaw-openai-image-auth.XXXXXX")"
-export OPENCLAW_STATE_DIR="$HOME/.openclaw"
+eval "$(printf "%s" "${OPENCLAW_TEST_STATE_SCRIPT_B64:?missing OPENCLAW_TEST_STATE_SCRIPT_B64}" | base64 -d)"
 export OPENCLAW_SKIP_CHANNELS=1
 export OPENCLAW_SKIP_GMAIL_WATCHER=1
 export OPENCLAW_SKIP_CRON=1
diff --git a/scripts/lib/docker-e2e-image.sh b/scripts/lib/docker-e2e-image.sh
index b47f44bbf4a..60739767b6c 100644
--- a/scripts/lib/docker-e2e-image.sh
+++ b/scripts/lib/docker-e2e-image.sh
@@ -81,3 +81,19 @@ docker_e2e_build_or_reuse() {
   build_args+=(-t "$image_name" -f "$dockerfile" "$context")
   docker_build_run "$label-build" "${build_args[@]}"
 }
+
+docker_e2e_test_state_shell_b64() {
+  local label="${1:?missing test-state label}"
+  local scenario="${2:-empty}"
+  node "$ROOT_DIR/scripts/lib/openclaw-test-state.mjs" shell \
+    --label "$label" \
+    --scenario "$scenario" \
+    | base64 \
+    | tr -d '\n'
+}
+
+docker_e2e_test_state_function_b64() {
+  node "$ROOT_DIR/scripts/lib/openclaw-test-state.mjs" shell-function \
+    | base64 \
+    | tr -d '\n'
+}
diff --git a/scripts/lib/docker-e2e-scenarios.mjs b/scripts/lib/docker-e2e-scenarios.mjs
index 10b6d38cd34..58f62562086 100644
--- a/scripts/lib/docker-e2e-scenarios.mjs
+++ b/scripts/lib/docker-e2e-scenarios.mjs
@@ -177,6 +177,7 @@ const bundledPluginInstallUninstallLanes = Array.from(
       {
         estimateSeconds: 280,
         resources: ["npm"],
+        stateScenario: "empty",
         weight: 1,
       },
     ),
@@ -253,6 +254,7 @@ export const mainLanes = [
     { resources: ["npm"], weight: 3 },
   ),
   npmLane("doctor-switch", "OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:doctor-switch", {
+    stateScenario: "empty",
     weight: 3,
   }),
   npmLane(
@@ -285,7 +287,9 @@ export const mainLanes = [
   npmLane("plugin-update", "OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:plugin-update"),
   serviceLane("config-reload", "OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:config-reload"),
   ...bundledScenarioLanes,
-  lane("openai-image-auth", "OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:openai-image-auth"),
+  lane("openai-image-auth", "OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:openai-image-auth", {
+    stateScenario: "empty",
+  }),
   lane(
     "crestodian-first-run",
     "OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:crestodian-first-run",
@@ -484,6 +488,7 @@ const releasePathPackageUpdateCoreLanes = [
     { resources: ["service"], stateScenario: "empty", weight: 3 },
   ),
   npmLane("doctor-switch", "OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:doctor-switch", {
+    stateScenario: "empty",
     weight: 3,
   }),
   npmLane(
diff --git a/test/scripts/docker-e2e-plan.test.ts b/test/scripts/docker-e2e-plan.test.ts
index b6ae9cdcddd..a863df90b39 100644
--- a/test/scripts/docker-e2e-plan.test.ts
+++ b/test/scripts/docker-e2e-plan.test.ts
@@ -160,6 +160,10 @@ describe("scripts/lib/docker-e2e-plan", () => {
           name: "npm-onboard-channel-agent",
           stateScenario: "empty",
         }),
+        expect.objectContaining({
+          name: "doctor-switch",
+          stateScenario: "empty",
+        }),
         expect.objectContaining({
           name: "update-channel-switch",
           stateScenario: "update-stable",
@@ -313,7 +317,14 @@ describe("scripts/lib/docker-e2e-plan", () => {
 
   it("surfaces Docker lane test-state scenarios in plan JSON", () => {
     const plan = planFor({
-      selectedLaneNames: ["onboard", "agents-delete-shared-workspace", "update-channel-switch"],
+      selectedLaneNames: [
+        "onboard",
+        "agents-delete-shared-workspace",
+        "doctor-switch",
+        "openai-image-auth",
+        "bundled-plugin-install-uninstall-0",
+        "update-channel-switch",
+      ],
     });
 
     expect(plan.lanes).toEqual([
@@ -325,6 +336,18 @@ describe("scripts/lib/docker-e2e-plan", () => {
         name: "agents-delete-shared-workspace",
         stateScenario: "empty",
       }),
+      expect.objectContaining({
+        name: "doctor-switch",
+        stateScenario: "empty",
+      }),
+      expect.objectContaining({
+        name: "openai-image-auth",
+        stateScenario: "empty",
+      }),
+      expect.objectContaining({
+        name: "bundled-plugin-install-uninstall-0",
+        stateScenario: "empty",
+      }),
       expect.objectContaining({
         name: "update-channel-switch",
         stateScenario: "update-stable",