From 749c3f58d049b5d8a9a3498126270916913b9e7f Mon Sep 17 00:00:00 2001
From: Erwan Leboucher <erwanleboucher@gmail.com>
Date: Thu, 20 Aug 2026 22:44:03 +0200
Subject: [PATCH] feat(complement): Load test image archives

---
 bin/complement               | 42 ++++++++++++++++++++++++++++++++----
 docs/development/testing.mdx |  5 ++---
 2 files changed, 40 insertions(+), 7 deletions(-)

diff --git a/bin/complement b/bin/complement
index 0ee646578..f1ac017d1 100755
--- a/bin/complement
+++ b/bin/complement
@@ -7,10 +7,30 @@ DEFAULT_COMPLEMENT_SRC="$toplevel/target/complement"
 DEFAULT_COMPLEMENT_REVISION="6d2fdc286c2b44faaddd1037205869b2242a4005"
 
 MSC="${COMPLEMENT_MSC:-}"
-if [ "${1:-}" = "--msc" ]; then
-    MSC="${2:-}"
-    shift 2
-fi
+IMAGE_ARCHIVE=""
+while [ "$#" -gt 0 ]; do
+    case "$1" in
+        --msc)
+            if [ "$#" -lt 2 ]; then
+                echo "--msc requires an MSC number"
+                exit 2
+            fi
+            MSC="$2"
+            shift 2
+            ;;
+        --image)
+            if [ "$#" -lt 2 ]; then
+                echo "--image requires a path to a Docker image archive"
+                exit 2
+            fi
+            IMAGE_ARCHIVE="$2"
+            shift 2
+            ;;
+        *)
+            break
+            ;;
+    esac
+done
 
 if [ -n "$MSC" ]; then
     MSC="${MSC#MSC}"
@@ -63,6 +83,20 @@ for command in docker go jq; do
     fi
 done
 
+if [ -n "$IMAGE_ARCHIVE" ]; then
+    if [ ! -f "$IMAGE_ARCHIVE" ]; then
+        echo "Docker image archive not found: $IMAGE_ARCHIVE"
+        exit 1
+    fi
+    load_output="$(docker load --input "$IMAGE_ARCHIVE" 2>&1)"
+    printf '%s\n' "$load_output"
+    COMPLEMENT_BASE_IMAGE="$(printf '%s\n' "$load_output" | sed -n 's/^Loaded image: //p; s/^Loaded image ID: //p' | tail -n1)"
+    if [ -z "$COMPLEMENT_BASE_IMAGE" ]; then
+        echo "could not determine the image loaded from: $IMAGE_ARCHIVE"
+        exit 1
+    fi
+fi
+
 if ! docker image inspect "$COMPLEMENT_BASE_IMAGE" > /dev/null 2>&1; then
     echo "Complement base image not found: $COMPLEMENT_BASE_IMAGE"
     echo "Build it with: cargo build -p conduwuit && docker build -t $COMPLEMENT_BASE_IMAGE -f docker/complement.Dockerfile ."
diff --git a/docs/development/testing.mdx b/docs/development/testing.mdx
index aabdd6cfd..c97deb3cb 100644
--- a/docs/development/testing.mdx
+++ b/docs/development/testing.mdx
@@ -35,11 +35,10 @@ To run test packages that mention an MSC, pass its number:
 This selects packages from Complement's source comments and file names, so it
 can include tests shared with that MSC but does not claim a complete mapping.
 
-To use an image built elsewhere, load and name it before running the script:
+To run a Docker image archive instead of building locally:
 
 ```bash
-docker load < complement_oci_image.tar.gz
-COMPLEMENT_BASE_IMAGE=your-image:tag ./bin/complement
+./bin/complement --image path/to/complement-image.tar.gz
 ```
 
 `COMPLEMENT_ENABLE_DIRTY_RUNS=1` reuses Complement containers for faster local