fix: enforce docker install for tests

Ensure test scripts invoke install-docker.sh when required.
Document docker-based validator and challenge tests.

Author: echobt

docs/challenge-integration.md

@@ -33,6 +33,12 @@ Platform uses a modular challenge architecture where each challenge:
     └─────────────┘   └─────────────┘  └─────────────┘
 ```
 
+## Testing With Docker
+
+Challenge containers are exercised by the validator test harness. Use `./scripts/test-comprehensive.sh` to run Docker-backed integration tests; it will call `scripts/install-docker.sh` if Docker or Compose are missing (unless `PLATFORM_TEST_DOCKER_MODE=skip`).
+
+---
+
 ## Creating a Challenge Crate
 
 ### 1. Project Structure

docs/validator.md

@@ -22,6 +22,9 @@ cd platform
 cp .env.example .env
 # Edit .env: add your VALIDATOR_SECRET_KEY (BIP39 mnemonic)
 
+# Optional: install Docker + Compose (used by test scripts)
+./scripts/install-docker.sh
+
 # Create the Docker network (required, one-time setup)
 docker network create platform-network
 
@@ -55,6 +58,7 @@ The validator will auto-connect to the network and sync. No GPUs, no third-party
 - Docker 24.0+
 - Docker Compose v2
 - Linux (Ubuntu 22.04+ recommended)
+- `scripts/install-docker.sh` (automated installer used by test scripts)
 
 ### Bittensor
 
@@ -192,6 +196,15 @@ Expected response:
 
 ---
 
+## Testing and Validation
+
+Validator deployment tests rely on Docker and Docker Compose. The test harness automatically invokes `scripts/install-docker.sh` when Docker is missing (unless `PLATFORM_TEST_DOCKER_MODE=skip`).
+
+- Run `./scripts/test-comprehensive.sh` to execute Docker-backed integration and multi-validator tests.
+- Run `./scripts/test-all.sh` for build/unit-only runs (Docker not required).
+
+---
+
 ## Troubleshooting
 
 ### Connection Issues

scripts/test-comprehensive.sh

@@ -47,13 +47,6 @@ else
     log_failure "Unit tests failed"
 fi
 
-log_info "============================================================================="
-log_info "Phase 3: Docker Integration Tests"
-log_info "============================================================================="
-if platform_should_run_docker; then
-    if platform_require_compose; then
-        platform_ensure_network
-platform_install_docker_if_needed
 log_info "============================================================================="
 log_info "Phase 3: Docker Integration Tests"
 log_info "============================================================================="
@@ -143,13 +136,6 @@ else
     log_failure "Distributed storage tests failed"
 fi
 
-log_info "============================================================================="
-log_info "Phase 8: Multi-validator Docker Compose"
-log_info "============================================================================="
-if platform_should_run_docker; then
-    if platform_require_compose; then
-        platform_ensure_network
-platform_install_docker_if_needed
 log_info "============================================================================="
 log_info "Phase 8: Multi-validator Docker Compose"
 log_info "============================================================================="

scripts/test-harness.sh

@@ -117,6 +117,11 @@ platform_install_docker_if_needed() {
 
     local script_dir
     script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    if [ ! -x "${script_dir}/install-docker.sh" ]; then
+        log_failure "scripts/install-docker.sh not found or not executable"
+        return 1
+    fi
+
     log_info "Docker/Compose missing; attempting installation via scripts/install-docker.sh"
     "${script_dir}/install-docker.sh"
 

tests/docker/entrypoint-test.sh

@@ -20,6 +20,10 @@ fi
 ARGS="--data-dir ${DATA_DIR:-/data}"
 ARGS="$ARGS --listen-addr ${P2P_LISTEN_ADDR:-/ip4/0.0.0.0/tcp/9000}"
 
+if [ "${PLATFORM_TEST_DOCKER_MODE:-auto}" = "required" ] && command -v platform_install_docker_if_needed >/dev/null 2>&1; then
+    platform_install_docker_if_needed
+fi
+
 if [ -n "${VALIDATOR_SECRET_KEY:-}" ]; then
     ARGS="$ARGS --secret-key ${VALIDATOR_SECRET_KEY}"
 fi

tests/docker/test-multi-validator.sh

@@ -4,7 +4,7 @@
 # =============================================================================
 # Tests multiple validators in a P2P network without Docker build issues
 # Uses locally built binary
-# Note: This script does not require Docker; see scripts/test-comprehensive.sh
+# Note: This script does not require Docker; see scripts/test-comprehensive.sh for Docker-based suites
 # =============================================================================
 
 set -euo pipefail
@@ -13,14 +13,16 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=../../scripts/test-harness.sh
 source "${SCRIPT_DIR}/../../scripts/test-harness.sh"
 
-platform_test_init
-trap platform_cleanup_run_dir EXIT
 platform_test_init
 trap platform_cleanup_run_dir EXIT
 
-VALIDATOR_BINARY="${VALIDATOR_BINARY:-${PLATFORM_TEST_ROOT}/target/release/validator-node}"
+if [ "${PLATFORM_TEST_DOCKER_MODE:-auto}" = "required" ]; then
+    platform_install_docker_if_needed
+fi
+
 NUM_VALIDATORS="${NUM_VALIDATORS:-3}"
 BASE_PORT="${BASE_PORT:-9100}"
+VALIDATOR_BINARY="${VALIDATOR_BINARY:-${PLATFORM_TEST_ROOT}/target/release/validator-node}"
 PLATFORM_TEST_RUN_DIR="${PLATFORM_TEST_RUN_DIR:-${PLATFORM_TEST_TMP_BASE}/multi-validator}"
 
 log_info "Test directory: ${PLATFORM_TEST_RUN_DIR}"