fix(test): build missing Docker images in Testbox

scripts/lib/docker-build.sh

@@ -6,6 +6,19 @@ if ! declare -F run_logged >/dev/null 2>&1; then
   source "$DOCKER_BUILD_LIB_DIR/docker-e2e-logs.sh"
 fi
 
+docker_build_on_missing_enabled() {
+  case "${OPENCLAW_DOCKER_BUILD_ON_MISSING:-}" in
+    1 | true | TRUE | yes | YES)
+      return 0
+      ;;
+    0 | false | FALSE | no | NO)
+      return 1
+      ;;
+  esac
+
+  [ "${OPENCLAW_TESTBOX:-0}" = "1" ]
+}
+
 docker_build_exec() {
   local build_cmd=(docker build)
   if [ "${OPENCLAW_DOCKER_BUILD_USE_BUILDX:-0}" = "1" ]; then

scripts/lib/docker-e2e-image.sh

@@ -49,13 +49,19 @@ docker_e2e_build_or_reuse() {
     echo "Reusing Docker image: $image_name"
     if ! docker image inspect "$image_name" >/dev/null 2>&1; then
       echo "Docker image not found locally; pulling: $image_name"
-      if ! docker pull "$image_name"; then
+      if docker pull "$image_name"; then
+        return 0
+      fi
+      if docker_build_on_missing_enabled; then
+        echo "Docker image not available; building because OPENCLAW_DOCKER_BUILD_ON_MISSING/OPENCLAW_TESTBOX allows fallback."
+      else
         echo "Docker image not found: $image_name" >&2
         echo "Build it first or unset OPENCLAW_SKIP_DOCKER_BUILD." >&2
         return 1
       fi
+    else
+      return 0
     fi
-    return 0
   fi
 
   echo "Building Docker image: $image_name"

scripts/test-live-build-docker.sh

@@ -22,7 +22,19 @@ fi
 
 if [[ "${OPENCLAW_SKIP_DOCKER_BUILD:-}" == "1" ]]; then
   echo "==> Reuse live-test image: $LIVE_IMAGE_NAME"
-  exit 0
+  if docker image inspect "$LIVE_IMAGE_NAME" >/dev/null 2>&1; then
+    exit 0
+  fi
+  echo "==> Live-test image not found locally; pulling: $LIVE_IMAGE_NAME"
+  if docker pull "$LIVE_IMAGE_NAME"; then
+    exit 0
+  fi
+  if ! docker_build_on_missing_enabled; then
+    echo "Live-test image not found: $LIVE_IMAGE_NAME" >&2
+    echo "Build it first or unset OPENCLAW_SKIP_DOCKER_BUILD." >&2
+    exit 1
+  fi
+  echo "==> Live-test image not available; building because OPENCLAW_DOCKER_BUILD_ON_MISSING/OPENCLAW_TESTBOX allows fallback."
 fi
 
 echo "==> Build live-test image: $LIVE_IMAGE_NAME (target=build)"

scripts/test-live-cli-backend-docker.sh

@@ -391,11 +391,7 @@ fi
 pnpm test:live src/gateway/gateway-cli-backend.live.test.ts
 EOF
 
-if [[ "${OPENCLAW_SKIP_DOCKER_BUILD:-}" == "1" ]]; then
-  echo "==> Reuse live-test image: $LIVE_IMAGE_NAME (OPENCLAW_SKIP_DOCKER_BUILD=1)"
-else
-  "$ROOT_DIR/scripts/test-live-build-docker.sh"
-fi
+"$ROOT_DIR/scripts/test-live-build-docker.sh"
 
 echo "==> Run CLI backend live test in Docker"
 echo "==> Model: $CLI_MODEL"

test/scripts/docker-build-helper.test.ts

@@ -3,8 +3,11 @@ import { describe, expect, it } from "vitest";
 
 const HELPER_PATH = "scripts/lib/docker-build.sh";
 const DOCKER_ALL_SCHEDULER_PATH = "scripts/test-docker-all.mjs";
+const DOCKER_E2E_IMAGE_HELPER_PATH = "scripts/lib/docker-e2e-image.sh";
 const DOCKER_E2E_SCENARIOS_PATH = "scripts/lib/docker-e2e-scenarios.mjs";
 const INSTALL_E2E_RUNNER_PATH = "scripts/docker/install-sh-e2e/run.sh";
+const LIVE_CLI_BACKEND_DOCKER_PATH = "scripts/test-live-cli-backend-docker.sh";
+const LIVE_BUILD_DOCKER_PATH = "scripts/test-live-build-docker.sh";
 const OPENAI_WEB_SEARCH_MINIMAL_E2E_PATH = "scripts/e2e/openai-web-search-minimal-docker.sh";
 const PLUGINS_DOCKER_E2E_PATH = "scripts/e2e/plugins-docker.sh";
 const PLUGIN_UPDATE_DOCKER_E2E_PATH = "scripts/e2e/plugin-update-unchanged-docker.sh";
@@ -44,6 +47,26 @@ describe("docker build helper", () => {
     }
   });
 
+  it("lets Testbox fall back to building when a reused Docker image is missing", () => {
+    const helper = readFileSync(HELPER_PATH, "utf8");
+    const e2eImageHelper = readFileSync(DOCKER_E2E_IMAGE_HELPER_PATH, "utf8");
+    const liveBuild = readFileSync(LIVE_BUILD_DOCKER_PATH, "utf8");
+    const liveCliBackend = readFileSync(LIVE_CLI_BACKEND_DOCKER_PATH, "utf8");
+
+    expect(helper).toContain("docker_build_on_missing_enabled()");
+    expect(helper).toContain("OPENCLAW_DOCKER_BUILD_ON_MISSING");
+    expect(helper).toContain("OPENCLAW_TESTBOX");
+    expect(e2eImageHelper).toContain("docker_build_on_missing_enabled");
+    expect(e2eImageHelper).toContain("Docker image not available; building");
+    expect(liveBuild).toContain("docker image inspect");
+    expect(liveBuild).toContain("docker pull");
+    expect(liveBuild).toContain("Live-test image not available; building");
+    expect(liveCliBackend).toContain('"$ROOT_DIR/scripts/test-live-build-docker.sh"');
+    expect(liveCliBackend).not.toContain(
+      'echo "==> Reuse live-test image: $LIVE_IMAGE_NAME (OPENCLAW_SKIP_DOCKER_BUILD=1)"',
+    );
+  });
+
   it("preserves pnpm lookup paths for scheduled Docker child lanes", () => {
     const scheduler = readFileSync(DOCKER_ALL_SCHEDULER_PATH, "utf8");