@essential-apps/shopify-test-runner 1.0.0

package/src/scripts/runVm.ts

@@ -0,0 +1,562 @@
+#!/usr/bin/env node
+/**
+ * Run online tests inside an HVF microVM (via supermachine HVF).
+ *
+ * Drop-in replacement for `runDocker.ts`. Same workflow, same test
+ * outputs, but uses the VM runtime's arm64 microVM with virtio-fs DAX
+ * bind mounts instead of Apple `container`'s libkrun:
+ *
+ *   libkrun                          vm
+ *   ─────────                        ────────────
+ *   amd64 image (Rosetta)            arm64 image (native)
+ *   ~10 s cold boot                  ~5 s cold bake / ~1 s warm restore
+ *   ~30 s/test wall-clock            ~3× faster end-to-end on offline-full
+ *   Google Chrome amd64 in Xvfb      Playwright bundled chromium in
+ *                                    Xvfb (patchright stealth still works)
+ *
+ * Architecture:
+ *   - Image: `essential-apps/shopify-test-vm:latest` baked
+ *     via `tests/test-offline/docker/Dockerfile.vm` in the consuming
+ *     app (the equivalent of `Dockerfile` for libkrun). Auto-saved as
+ *     a local OCI archive on first invocation via `prepareOciArchive`.
+ *   - Bind mounts (virtio-fs DAX):
+ *       - consuming app repo      → /workspace
+ *       - linux node_modules cache → /workspace/node_modules
+ *     Both writable in-VM, host changes reflected immediately.
+ *   - Postgres autostarted in the warmup callback (folded into the
+ *     snapshot so warm restores skip the cost).
+ *   - `runTests.js` invoked inside the VM; its localhost:5432 points
+ *     at the in-VM postgres started by the warmup.
+ *
+ * Override env vars (all match the conformance package's conventions
+ * so users only learn one set):
+ *   TEST_ONLINE_VM_IMAGE          ref to bake/restore. Default:
+ *                                   `essential-apps/shopify-test-vm:latest`
+ *   TEST_ONLINE_VM_IMAGE_SOURCE   oci-archive | oci-layout | registry. Default: oci-archive.
+ *   TEST_ONLINE_VM_IMAGE_LAYOUT_PATH  required when source=oci-layout.
+ *   TEST_ONLINE_VM_MEMORY_MIB     guest RAM. Default: 8192.
+ *   TEST_ONLINE_VM_VCPUS          guest vCPUs. Default: 4.
+ *   TEST_LINUX_NODE_MODULES_VOLUME   host path for the Linux node_modules
+ *                                   sparse-file volume.
+ *                                   Default: ~/.cache/${appName}-test/node_modules.img
+ *   TEST_ONLINE_VM_TIMEOUT_MS     overall guard for runTests.js. Default: 10 min.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { prepareOciArchive, envFileArgs } from '@essential-apps/shopify-test-core';
+
+const repoRoot = process.cwd();
+
+interface PackageJson {
+  name?: string;
+}
+
+function readAppName(): string {
+  const pkgPath = resolve(repoRoot, 'package.json');
+  if (!existsSync(pkgPath)) {
+    throw new Error(
+      `No package.json at ${pkgPath}. Run this from the consuming app's repo root.`,
+    );
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as PackageJson;
+  if (!pkg.name) {
+    throw new Error(`package.json at ${pkgPath} has no \`name\` field.`);
+  }
+  return pkg.name.replace(/^@[^/]+\//, '');
+}
+
+/**
+ * Resolve the VM image source the same way the conformance
+ * runner does. Duplicated here intentionally — extracting into a
+ * shared helper would create a runner→conformance dep cycle (runner
+ * is allowed to depend on conformance, but in practice this is the
+ * single use-site and the indirection isn't worth a new dep).
+ */
+async function imageSourceOptions(): Promise<Record<string, unknown>> {
+  const mode = process.env['TEST_ONLINE_VM_IMAGE_SOURCE'] ?? 'oci-archive';
+  if (mode === 'registry') return {};
+  const ref =
+    process.env['TEST_ONLINE_VM_IMAGE'] ??
+    // Must match the default in main() below — otherwise the OCI
+    // archive's recorded ref won't match what Image.build expects.
+    'essential-apps/shopify-test-vm:latest';
+  if (mode === 'oci-archive') {
+    const prep = await prepareOciArchive(ref);
+    if (prep.freshlySaved) {
+      console.error(
+        `[runVm] saved ${ref} → ${prep.archivePath} (${(prep.sizeBytes / 1024 / 1024).toFixed(1)} MB)`,
+      );
+    }
+    return { source: 'oci-archive', sourcePath: prep.archivePath };
+  }
+  if (mode === 'oci-layout') {
+    const sourcePath = process.env['TEST_ONLINE_VM_IMAGE_LAYOUT_PATH'];
+    if (!sourcePath) {
+      throw new Error(
+        `TEST_ONLINE_VM_IMAGE_SOURCE=oci-layout requires TEST_ONLINE_VM_IMAGE_LAYOUT_PATH`,
+      );
+    }
+    return { source: 'oci-layout', sourcePath };
+  }
+  throw new Error(
+    `TEST_ONLINE_VM_IMAGE_SOURCE=${mode} not recognised. Valid: oci-archive | oci-layout | registry`,
+  );
+}
+
+async function main(): Promise<void> {
+  const appName = readAppName();
+  // node_modules now lives in a virtio-blk VOLUME (sparse host file)
+  // instead of a virtio-fs bind mount. Three wins:
+  //   1. ~native disk speed for the many-small-files workload that
+  //      npm install actually is (10-30s vs 3-6 min on a virtio-fs
+  //      mount per the VM runtime's example 07).
+  //   2. State semantics make sense: node_modules is VM-private
+  //      (produced by in-VM npm install), not shared with the host.
+  //   3. Cache invalidation via `extraFiles` on the tarball manifest
+  //      (see below) handles "tarballs changed → rebake" properly,
+  //      so pack-into no longer needs the wipe-host-cache hack.
+  // Path defaults stay namespaced by appName so multi-app dev works.
+  const linuxModulesVolume =
+    process.env['TEST_LINUX_NODE_MODULES_VOLUME'] ??
+    resolve(homedir(), `.cache/${appName}-test/node_modules.img`);
+  mkdirSync(resolve(linuxModulesVolume, '..'), { recursive: true });
+
+  // Tarball-manifest file written by `scripts/pack-into.sh`. We pass
+  // it as an extraFile so its bytes are folded into the snapshot's
+  // input hash — any tarball change re-bakes automatically. Optional
+  // (consumer might not use pack-into); we just skip the extraFile if
+  // it's missing.
+  const tarballManifest = resolve(
+    repoRoot,
+    'vendor/essential-apps-shopify-test/.tarball-manifest',
+  );
+  const tarballManifestExists = existsSync(tarballManifest);
+
+  // Fold the manifest hash into the warmupTag. The `extraFiles` entry
+  // below does NOT reliably re-key the snapshot in this VM-runtime
+  // version (verified on the offline runner: manifest changed, bake
+  // was still 0.0s warm). The warmupTag DOES definitively key it, so
+  // hash the manifest (a sha256 list of the vendored tarballs) into
+  // the tag: tarball change → manifest change → tag change → rebake →
+  // warmup reinstalls, with no manual bump. `v15` is the warmup-SCRIPT
+  // version — bump only for warmup-step changes (v15: a failed
+  // npm install now aborts the bake instead of caching a half-
+  // installed node_modules volume).
+  const manifestHash = tarballManifestExists
+    ? createHash('sha256').update(readFileSync(tarballManifest)).digest('hex').slice(0, 12)
+    : 'no-manifest';
+
+  // Fold the @supermachine/core (VM runtime) version into the snapshot
+  // key too: the bake hash keys on GUEST inputs (image + tarballs), not
+  // the host VMM, so a runtime bump would otherwise warm-restore a stale
+  // snapshot baked by the old runtime. Key on the installed version so a
+  // bump auto-rebakes — same philosophy as the manifest hash. Resolved
+  // from the consumer root; degrades to a stable bucket if unreadable.
+  const runtimeVersion = ((): string => {
+    try {
+      const requirePkg = createRequire(resolve(repoRoot, 'package.json'));
+      return (
+        requirePkg('@supermachine/core/package.json') as { version: string }
+      ).version;
+    } catch {
+      return 'unknown';
+    }
+  })();
+  const runtimeTag = `sm${runtimeVersion.replace(/[^0-9a-z]+/gi, '')}`;
+  // Scope the snapshot to the consuming app — see runOffline.ts. Warm
+  // snapshots are keyed (image + warmupTag) and the image is shared, so
+  // two apps vendoring the same shopify-test build would otherwise
+  // collide on one warm snapshot (which captures the app's npm install).
+  const warmupTag = `online-v15-${appName}-${runtimeTag}-${manifestHash}`;
+
+  // Dynamic import — @supermachine/core is heavy and only needed
+  // when actually running tests, not for `--help` etc.
+  const { Image } = await import('@supermachine/core');
+
+  const imageOpts = await imageSourceOptions();
+  console.error(`[runVm] baking image… (warmupTag=${warmupTag})`);
+  const tBake = performance.now();
+  // arm64 native — no Rosetta translation tax. Storepool +
+  // captureAuth use patchright's bundled chromium (arm64 build
+  // ships with the package), so we no longer need amd64+Rosetta
+  // for real Google Chrome.
+  const platform = process.env['TEST_ONLINE_VM_PLATFORM'] ?? 'linux/arm64';
+
+  // `cmd` overrides only the image's CMD; VM runtime 0.7.16+
+  // auto-prepends the image's ENTRYPOINT (Docker-like semantics).
+  // The amd64 image's entrypoint.sh starts Xvfb + Postgres +
+  // /etc/hosts seed before exec-ing the cmd args; those services
+  // are preserved across snapshot/restore as background processes.
+  const image = await Image.build({
+    ref:
+      process.env['TEST_ONLINE_VM_IMAGE'] ??
+      // arm64-native conformance image (Dockerfile.vm).
+      // We switched the browser to patchright-only (storePool +
+      // captureAuth both use the bundled chromium with stealth
+      // patches), so we no longer need the amd64 image to host
+      // google-chrome-stable amd64 — arm64 native is faster
+      // (no Rosetta translation) and uses less memory.
+      'essential-apps/shopify-test-vm:latest',
+    // 12 GiB ceiling — patchright chromium + postgres + Vite/Remix
+    // (Prisma + esbuild + 2k+ packages loaded) + npm-install warmup
+    // all live concurrently. 8 GiB OOM-killed Vite during Playwright
+    // startup. Lazy CoW means host phys_footprint is far smaller;
+    // bump via TEST_ONLINE_VM_MEMORY_MIB for memory-hungry suites.
+    memoryMib: Number(process.env['TEST_ONLINE_VM_MEMORY_MIB'] ?? 12288),
+    vcpus: Number(process.env['TEST_ONLINE_VM_VCPUS'] ?? 4),
+    cmd: ['sleep', 'infinity'],
+    // SKIP_OFFLINE_HOST_HIJACK=1 — image's entrypoint.sh would
+    // otherwise redirect *.shopify.com → 127.0.0.1 for offline-mode
+    // wiring. Online hits REAL Shopify endpoints; need real DNS.
+    env: { SKIP_OFFLINE_HOST_HIJACK: '1' },
+    ...(platform ? { platform } : {}),
+    mounts: [
+      // Workspace stays a virtio-fs MOUNT — host edits live in
+      // the guest. node_modules moved to a volume below.
+      // `guestPath` is required in the VM runtime 0.7.28+; init-oci
+      // auto-mounts at this path in declared order BEFORE warmup
+      // fires, so we no longer mount manually in the warmup script.
+      { hostPath: repoRoot, guestTag: 'workspace', guestPath: '/workspace' },
+    ],
+    volumes: [
+      // node_modules: virtio-blk volume mounted at /workspace/node_modules.
+      // The first volume → /dev/vdb (root is /dev/vda). Warmup formats
+      // it on first bake; subsequent restores re-mount it as-is.
+      // 4 GiB cap (sparse, only uses what's actually written).
+      {
+        hostPath: linuxModulesVolume,
+        guestPath: '/workspace/node_modules',
+        sizeMib: 4096,
+      },
+    ],
+    extraFiles: tarballManifestExists
+      ? [
+          // Folded into bake input-hash; any tarball change → manifest
+          // bytes change → new snapshot. Guest path is irrelevant
+          // beyond not colliding with anything else.
+          { hostPath: tarballManifest, guestPath: '/etc/.shopify-test-tarball-manifest' },
+        ]
+      : [],
+    // Snapshot key — computed from the tarball-manifest hash (see
+    // above) so a tarball refresh auto-rebakes without a manual bump.
+    // Warmup runs ONCE per bake; warm acquires skip it.
+    warmupTag,
+    // @ts-expect-error — @supermachine/core's BuildOptions type
+    // doesn't declare `warmup`, but the runtime accepts it. Tracked
+    // upstream; fix-or-augment when the types catch up.
+    warmup: async (vm: {
+      exec: (opts: { argv: string[]; timeoutMs?: number }) => Promise<{
+        exitCode: number;
+        stdout: Buffer;
+        stderr: Buffer;
+      }>;
+    }) => {
+      const r = await vm.exec({
+        argv: ['sh', '-c', `
+          set -e
+
+          # VM runtime 0.7.28+ auto-mounts both /workspace
+          # (virtio-fs) and /workspace/node_modules (virtio-blk ext4
+          # volume) BEFORE warmup fires — no manual mount/format
+          # needed here. We keep one defence-in-depth check though:
+          # assert /workspace/node_modules is NOT virtiofs. If the
+          # volume auto-mount silently failed, /workspace/node_modules
+          # would surface the HOST's repo node_modules via the
+          # workspace bind, and the rm-rf below would corrupt the
+          # @supermachine binary and many other things mid-bake.
+          NM_FS=\$(stat -f -c %T /workspace/node_modules 2>/dev/null || stat --file-system --format=%T /workspace/node_modules)
+          echo "[volume] /workspace/node_modules filesystem type: \$NM_FS"
+          if [ "\$NM_FS" = "virtiofs" ] || [ "\$NM_FS" = "fuse.virtiofs" ]; then
+            echo "FATAL: /workspace/node_modules is \$NM_FS — auto-mount broken"
+            echo "/proc/mounts:"; grep ' /workspace' /proc/mounts || echo "  (no /workspace entries)"
+            exit 1
+          fi
+
+          echo "--- repair perms for postgres ---"
+          chown -R postgres:postgres /var/lib/postgresql/data
+          chmod 700 /var/lib/postgresql/data
+          mkdir -p /var/run/postgresql
+          chown postgres:postgres /var/run/postgresql
+          chmod 775 /var/run/postgresql
+
+          echo "--- npm install (fresh per rebake) ---"
+          # Warmup runs exactly when the snapshot is rebaked — which
+          # happens only when the tarball-manifest extraFile changes
+          # (= someone ran pack-into.sh) or the warmupTag bumps.
+          # Either way we want a fresh install: wipe the volume's
+          # node_modules dir first so npm can't reuse stale tarballs.
+          cd /workspace
+          rm -rf node_modules/* node_modules/.[!.]* 2>/dev/null || true
+          # npm gates optionalDependencies by os/cpu automatically,
+          # so darwin-arm64-only natives (e.g. @supermachine/core-darwin-arm64)
+          # are skipped on Linux without needing --no-optional. Any
+          # "notsup os/cpu" failure here means a darwin-only package
+          # has snuck into hard "dependencies" — fix it in package.json
+          # rather than papering over with --no-optional, since that
+          # would also skip genuinely-needed Linux optionals.
+          # NB: do not pipe npm to "tail" — the pipeline exit status is
+          # tail's (0), which masks npm failures under "set -e", so a
+          # transient install error (e.g. ECONNRESET fetching prisma
+          # engines) would bake a snapshot with a half-installed
+          # node_modules volume that every warm restore then reuses.
+          # Capture to a file and check npm's own status: a failed
+          # install aborts the bake (no snapshot cached, next run
+          # rebakes), so a flaky-network blip self-heals.
+          if ! npm install --legacy-peer-deps --engine-strict=false > /tmp/npm-install.log 2>&1; then
+            echo "--- npm install FAILED - last 40 lines ---"
+            tail -40 /tmp/npm-install.log
+            exit 1
+          fi
+          tail -30 /tmp/npm-install.log
+
+          echo "--- patch /etc/hosts for localhost ---"
+          if ! grep -q "^127.0.0.1.*localhost" /etc/hosts; then
+            echo "127.0.0.1 localhost" >> /etc/hosts
+            echo "::1 localhost" >> /etc/hosts
+          fi
+
+          echo "--- warmup done ---"
+        `],
+        timeoutMs: 15 * 60 * 1000,
+      });
+      // Always print warmup output so silent failures (npm install
+      // writing to wrong dir, mounts attaching wrong tag, etc.) are
+      // visible.
+      console.error(`[runVm.warmup] stdout (${r.stdout.length} bytes):\n${r.stdout.toString()}`);
+      if (r.stderr.length > 0) {
+        console.error(`[runVm.warmup] stderr (${r.stderr.length} bytes):\n${r.stderr.toString()}`);
+      }
+      if (r.exitCode !== 0) {
+        throw new Error(`warmup failed (exit ${r.exitCode}) — see output above`);
+      }
+    },
+    ...imageOpts,
+  });
+  console.error(`[runVm] bake: ${((performance.now() - tBake) / 1000).toFixed(1)} s`);
+
+  const pool = await image.pool({ min: 1, max: 1, restoreOnRelease: false });
+  const vm = await pool.acquire();
+  try {
+    // Post-restore sanity. VM runtime 0.7.28+ captures the
+    // auto-mount tree in the snapshot, so /workspace and
+    // /workspace/node_modules are already mounted on restore. We
+    // just assert + bail if anything's off; same defence-in-depth
+    // virtiofs check as the warmup to prevent rm-by-accident if
+    // auto-mount layering ever breaks.
+    const tMount = performance.now();
+    const mountR = await vm.exec({
+      argv: ['sh', '-c', `
+        mountpoint -q /workspace || { echo "FATAL: /workspace not mounted"; exit 1; }
+        mountpoint -q /workspace/node_modules || { echo "FATAL: /workspace/node_modules not mounted"; exit 1; }
+        NM_FS=\$(stat -f -c %T /workspace/node_modules 2>/dev/null)
+        if [ "\$NM_FS" = "virtiofs" ] || [ "\$NM_FS" = "fuse.virtiofs" ]; then
+          echo "FATAL: /workspace/node_modules is \$NM_FS — auto-mount layering broken"
+          exit 1
+        fi
+        ls /workspace/node_modules/@essential-apps/shopify-test-runner/dist/scripts/runTests.js >/dev/null \
+          || { echo "FATAL: runTests.js missing in volume — snapshot/volume out of sync"; ls /workspace/node_modules/@essential-apps 2>&1 | head; exit 1; }
+      `],
+      timeoutMs: 10_000,
+    });
+    if (mountR.exitCode !== 0) {
+      console.error(`[runVm] mount failed:\n${mountR.stdout.toString()}${mountR.stderr.toString()}`);
+      process.exit(1);
+    }
+    console.error(`[runVm] mounts: ${((performance.now() - tMount) / 1000).toFixed(2)} s`);
+
+    // Postgres startup — fast because warmup already chowned the data dir.
+    const tPg = performance.now();
+    const pgR = await vm.exec({
+      argv: ['sh', '-c', `
+        export PGDATA=/var/lib/postgresql/data
+        export PG_BIN=/usr/lib/postgresql/14/bin
+        # Use pg_isready (actually checks ACCEPT-CONNECTIONS) rather
+        # than pg_ctl status (which just checks postmaster.pid exists).
+        # The snapshot can capture a stale postmaster.pid file from
+        # the bake-time postgres that didn't survive restore, so
+        # pg_ctl status returns 0 but pg_isready / actual connections
+        # both fail. Always prefer the real readiness probe.
+        if su postgres -c "\${PG_BIN}/pg_isready -h 127.0.0.1 -p 5432 -q" >/dev/null 2>&1; then exit 0; fi
+        # Postgres isn't actually serving — clean up any stale state
+        # from the snapshot and start fresh.
+        rm -f \${PGDATA}/postmaster.pid 2>/dev/null || true
+        if [ -z "$(ls -A \${PGDATA} 2>/dev/null)" ]; then su postgres -c "\${PG_BIN}/initdb -D \${PGDATA} -A trust" >/dev/null; fi
+        su postgres -c "\${PG_BIN}/pg_ctl -D \${PGDATA} -l /tmp/pg.log -o '-h 127.0.0.1 -p 5432' start" >/dev/null
+        for _ in $(seq 1 50); do
+          if su postgres -c "\${PG_BIN}/pg_isready -h 127.0.0.1 -p 5432" >/dev/null 2>&1; then
+            # Create 'root' superuser to match the libkrun image entrypoint
+            # — runTests.js connects as 'root'.
+            su postgres -c "\${PG_BIN}/createuser -h 127.0.0.1 -p 5432 -s root" 2>&1 | grep -v 'already exists' || true
+            exit 0
+          fi
+          sleep 0.1
+        done
+        cat /tmp/pg.log
+        exit 1
+      `],
+      timeoutMs: 30_000,
+    });
+    if (pgR.exitCode !== 0) {
+      console.error('[runVm] postgres start failed:', pgR.stderr.toString());
+      process.exit(1);
+    }
+    console.error(`[runVm] postgres: ${((performance.now() - tPg) / 1000).toFixed(2)} s`);
+
+    // Xvfb: snapshot/restore preserves /tmp/.X11-unix/X99 (socket
+    // file) AND /tmp/.X99-lock (lock file). After restore, the
+    // entrypoint's `Xvfb :99 &` call refuses to start ("server :99
+    // already in use") because the stale lock is present — but the
+    // STALE SOCKET file is also there, so a `[ -e socket ]` check
+    // passes spuriously and Chrome gets "Missing X server or
+    // $DISPLAY" when it tries to actually connect. Same failure
+    // mode we hit in runVmAuth.ts; same fix: kill any
+    // existing Xvfb, remove the stale lock/socket, start fresh.
+    // Always start Xvfb — storePool launches HEADED chromium (matches
+    // captureAuth's fingerprint for cf_clearance carryover), and
+    // headed chromium needs an X server regardless of arch.
+    const needsXvfb = true;
+    if (needsXvfb) {
+      const tXvfb = performance.now();
+      const xR = await vm.exec({
+        argv: ['bash', '-c', `
+          # pkill -x (process-name exact match) — NOT pkill -f, which
+          # would also match the script's own argv and kill ourselves.
+          pkill -x Xvfb 2>/dev/null || true
+          rm -f /tmp/.X11-unix/X99 /tmp/.X99-lock
+          # -ac: no Xauthority required (other vm.exec / Playwright
+          # processes can connect without the cookie context from
+          # the start). Background via nohup + & so the daemon
+          # outlives this exec call.
+          nohup Xvfb :99 -screen 0 1600x1000x24 -nolisten tcp -ac \
+            >/var/log/xvfb.log 2>&1 &
+          for _ in $(seq 1 150); do
+            [ -e /tmp/.X11-unix/X99 ] && echo ready && exit 0
+            sleep 0.1
+          done
+          echo "Xvfb did not bind /tmp/.X11-unix/X99 within 15s"
+          cat /var/log/xvfb.log
+          exit 1
+        `],
+        timeoutMs: 30_000,
+      });
+      if (xR.exitCode !== 0) {
+        console.error(`[runVm] Xvfb wait failed: ${xR.stderr.toString()}`);
+        process.exit(1);
+      }
+      console.error(`[runVm] Xvfb: ${((performance.now() - tXvfb) / 1000).toFixed(2)} s (${xR.stdout.toString().trim()})`);
+    }
+
+    // Forward a curated env subset into the test process. Anything
+    // beyond this is intentionally not visible to the in-VM Node
+    // (hermetic, same policy as runTests.js itself).
+    const forwardEnv: Record<string, string> = {};
+    for (const k of [
+      'TEST_VISIBLE',
+      'TEST_WORKERS',
+      'TEST_PRESERVE_DB',
+      // TEST_ONLINE_STORE_CLEANUP_URL / TEST_ONLINE_CLEANUP_SECRET intentionally not
+      // forwarded — runTests.ts generates the secret per-run and
+      // builds the URL from devAppUrl. Forwarding stale values from
+      // .env.test would override that.
+      'TEST_OFFLINE_STRICT_GRAPHQL',
+      // TEST_FORCE_REAL_CHROME: storePool flips chromium.launch to
+      // `channel: 'chrome'` (real Google Chrome amd64 installed in
+      // the libkrun-style image). Set this together with
+      // TEST_ONLINE_VM_IMAGE=…shopify-test:latest +
+      // TEST_ONLINE_VM_PLATFORM=linux/amd64.
+      'TEST_FORCE_REAL_CHROME',
+      // PLAYWRIGHT_GREP narrows the test set inside the VM. runTests.ts
+      // reads this and forwards as `playwright test --grep`. Without
+      // this passthrough, an env var the user sets on the host invocation
+      // would silently get dropped and the whole suite would run.
+      'PLAYWRIGHT_GREP',
+      'CI',
+      'DEBUG',
+    ]) {
+      const v = process.env[k];
+      if (v !== undefined) forwardEnv[k] = v;
+    }
+    // Mark we're inside the test container — storePool reads this to
+    // adjust chromium launch flags.
+    forwardEnv['TEST_IN_CONTAINER'] = 'true';
+    // Wire DISPLAY for headed Chrome. Matches the Xvfb start above.
+    if (needsXvfb) forwardEnv['DISPLAY'] = ':99';
+
+    // Spawn the test runner. Streaming stdout/stderr via spawn so
+    // the user sees Playwright output as it lands rather than at end.
+    console.error('[runVm] launching runTests.js…');
+    const tTests = performance.now();
+    const testProc = await vm.spawn({
+      argv: ['sh', '-c', `
+        cd /workspace
+        # node_modules/.bin on PATH so test code can shell out to
+        # local CLIs (shopify, prisma, playwright). Matches the
+        # libkrun image's entrypoint.sh.
+        export PATH=/workspace/node_modules/.bin:$PATH
+        # Merge stderr → stdout so the stall guard sees Node errors
+        # (which Node writes to stderr) and surfaces them to the
+        # operator instead of dying silently after the stall timeout.
+        exec node ${envFileArgs(repoRoot)} node_modules/@essential-apps/shopify-test-runner/dist/scripts/runTests.js 2>&1
+      `],
+      env: forwardEnv,
+    });
+
+    // Stream + collect output. Hard 10-min cap by default, with a
+    // 60 s no-output stall guard (mirrors the offline-full bench's
+    // proven pattern for live processes).
+    const maxMs = Number(process.env['TEST_ONLINE_VM_TIMEOUT_MS'] ?? 10 * 60 * 1000);
+    // Stall guard: kill the test process if no output for N seconds.
+    // Default 60s; bump via TEST_ONLINE_VM_STALL_MS. amd64+Rosetta
+    // can take >60s for Vite/Remix initial compile so bump for that
+    // path explicitly.
+    const stallMs = Number(
+      process.env['TEST_ONLINE_VM_STALL_MS'] ??
+        (platform === 'linux/amd64' ? 300_000 : 60_000),
+    );
+    const start = Date.now();
+    let lastByteAt = Date.now();
+    while (true) {
+      const out = await testProc.readStdout(64 * 1024);
+      const now = Date.now();
+      if (out.length === 0) {
+        if (now - start > maxMs) {
+          console.error(`\n[runVm] HARD TIMEOUT ${maxMs / 1000}s — killing`);
+          await testProc.signal(15).catch(() => {});
+          break;
+        }
+        if (now - lastByteAt > stallMs) {
+          console.error(`\n[runVm] no output for ${stallMs / 1000}s — killing`);
+          await testProc.signal(15).catch(() => {});
+          break;
+        }
+        await new Promise((r) => setTimeout(r, 200));
+        continue;
+      }
+      lastByteAt = now;
+      process.stdout.write(out);
+      // Playwright summary lines look like "  17 passed (45.6s)" or
+      // "  3 failed". Once we see one, drain the tail and break.
+      if (/\b\d+ (passed|failed)\b/.test(out.toString())) {
+        await new Promise((r) => setTimeout(r, 500));
+        const tail = await testProc.readStdout(64 * 1024);
+        if (tail.length > 0) process.stdout.write(tail);
+        break;
+      }
+    }
+    const wait = await testProc.wait();
+    console.error(`[runVm] tests: ${((performance.now() - tTests) / 1000).toFixed(1)} s`);
+    console.error(`[runVm] grand: ${((performance.now() - tBake) / 1000).toFixed(1)} s`);
+    process.exit(wait.exitCode ?? 0);
+  } finally {
+    await vm.release().catch(() => {});
+    await pool.shutdown().catch(() => {});
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});