test(e2e): replace the Linux compose runners with a dev container (#37)

Author: linghengqian

.devcontainer/Dockerfile

@@ -0,0 +1,82 @@
+# Copyright 2026 Han Li and contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# The repository dev container (see docs/e2e.md): a Linux userland that is
+# identical on every host platform — Linux amd64/arm64 natively, Windows
+# amd64/arm64 through Docker Desktop's Linux-container mode. It carries the
+# pinned Go toolchain the E2E suites and the local checks need, matching the
+# setup-go version CI uses, plus the Lua and license tooling pinned in the
+# lint and license workflows.
+#
+# The suites themselves run testcontainers against the host daemon through
+# the socket mounted by devcontainer.json (Docker-out-of-Docker), so the
+# target containers are spawned exactly as a native CI runner spawns them.
+#
+# The image is multi-arch (linux/amd64 and linux/arm64); the Lua downloads
+# below select their asset per target arch.
+
+FROM golang:1.27.1
+
+# Docker CLI (client only): drives the host daemon from the shell, the same
+# daemon the suites drive through the Docker Go API. Engine 29 is the line
+# tests/e2e/windows/install-docker-arm64.ps1 builds for Windows arm64.
+COPY --from=docker:29-cli /usr/local/bin/docker /usr/local/bin/docker
+
+# Keep the tool versions below in step with .github/workflows/lint.yml
+# (stylua-action's version and the `mise x aqua:...` line).
+ARG STYLUA_VERSION=2.5.2
+ARG LUA_LANGUAGE_SERVER_VERSION=3.19.1
+
+# Heredocs need BuildKit, which the dev container tooling uses by default. The
+# E2E target Dockerfiles stay on the chained-`;` form: testcontainers-go's
+# build path cannot use BuildKit (see tests/e2e/linux/Dockerfile).
+
+RUN <<EOF
+set -o errexit -o nounset -o xtrace
+apt-get update
+apt-get install --assume-yes --no-install-recommends \
+    ca-certificates \
+    curl \
+    git \
+    unzip \
+    zip
+rm --recursive --force /var/lib/apt/lists/*
+case "$(dpkg --print-architecture)" in
+    amd64) stylua_asset=stylua-linux-x86_64.zip; luals_asset="lua-language-server-${LUA_LANGUAGE_SERVER_VERSION}-linux-x64.tar.gz" ;;
+    arm64) stylua_asset=stylua-linux-aarch64.zip; luals_asset="lua-language-server-${LUA_LANGUAGE_SERVER_VERSION}-linux-arm64.tar.gz" ;;
+    *) echo "FAIL unsupported architecture $(dpkg --print-architecture)" >&2; exit 1 ;;
+esac
+curl --fail --silent --show-error --location --output /tmp/stylua.zip \
+    "https://github.com/JohnnyMorganz/StyLua/releases/download/v${STYLUA_VERSION}/${stylua_asset}"
+unzip -q /tmp/stylua.zip -d /usr/local/bin
+rm --force /tmp/stylua.zip
+curl --fail --silent --show-error --location --output /tmp/luals.tar.gz \
+    "https://github.com/LuaLS/lua-language-server/releases/download/${LUA_LANGUAGE_SERVER_VERSION}/${luals_asset}"
+mkdir --parents /opt/lua-language-server
+tar --extract --gzip --file /tmp/luals.tar.gz --directory /opt/lua-language-server
+rm --force /tmp/luals.tar.gz
+ln --symbolic /opt/lua-language-server/bin/lua-language-server /usr/local/bin/lua-language-server
+stylua --version
+lua-language-server --version
+EOF
+
+# License-header tooling at the versions pinned by .github/workflows/license.yml
+# (SkyWalking Eyes v0.9.0 for the header check, addlicense v1.2.0 for the
+# PowerShell files).
+RUN <<EOF
+set -o errexit -o nounset -o xtrace
+GOBIN=/usr/local/bin go install github.com/apache/skywalking-eyes/cmd/license-eye@v0.9.0
+GOBIN=/usr/local/bin go install github.com/google/addlicense@v1.2.0
+command -v license-eye addlicense
+EOF

.devcontainer/devcontainer.json

@@ -0,0 +1,19 @@
+{
+  "name": "vfox-nodejs (Linux)",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": "."
+  },
+  "mounts": [
+    "source=${localEnv:DOCKER_SOCK:/var/run/docker.sock},target=/var/run/docker.sock,type=bind"
+  ],
+  "containerEnv": {
+    "TESTCONTAINERS_RYUK_DISABLED": "true"
+  },
+  "postCreateCommand": "cd tests/e2e && go mod download",
+  "customizations": {
+    "vscode": {
+      "extensions": ["golang.go", "sumneko.lua"]
+    }
+  }
+}

.dockerignore

@@ -18,6 +18,7 @@
 .git
 .gitignore
 .gitattributes
+.devcontainer
 .idea
 .github
 *.md

.github/workflows/e2e.yml

@@ -26,6 +26,13 @@ concurrency:
   group: e2e-${{ github.ref }}
   cancel-in-progress: true
 
+# The Linux and WSL jobs run the suite natively, the way the dev container
+# runs it locally: Go at the dev container's version (.devcontainer/Dockerfile)
+# plus the runner's stock Docker, with the same TESTCONTAINERS_RYUK_DISABLED
+# knob. The Windows jobs keep the compose runner image
+# (tests/e2e/windows/Dockerfile-runner), which carries its own Go toolchain,
+# so a Windows host needs only Docker. See docs/e2e.md.
+
 jobs:
   e2e-linux:
     if: github.repository == 'version-fox/vfox-nodejs'
@@ -36,11 +43,22 @@ jobs:
         runs-on: [ubuntu-latest, ubuntu-26.04-arm]
     runs-on: ${{ matrix.runs-on }}
     timeout-minutes: 60
+    env:
+      # Ryuk publishes a port on the host daemon and waits for the suite to
+      # dial back to it; the dev container disables it (it runs
+      # Docker-out-of-Docker), and CI matches so both paths stay identical.
+      # Containers are terminated explicitly via t.Cleanup instead.
+      TESTCONTAINERS_RYUK_DISABLED: "true"
     steps:
       - uses: actions/checkout@v7
         with:
           persist-credentials: false
-      - run: docker compose -f tests/e2e/linux/compose.yaml run --rm e2e
+      - uses: actions/setup-go@v6
+        with:
+          go-version: 1.27.1
+          cache: false
+      - run: go test -v -timeout 55m -run TestE2E ./linux
+        working-directory: tests/e2e
 
   e2e-linux-musl:
     if: github.repository == 'version-fox/vfox-nodejs'
@@ -51,11 +69,21 @@ jobs:
         runs-on: [ubuntu-latest, ubuntu-26.04-arm]
     runs-on: ${{ matrix.runs-on }}
     timeout-minutes: 60
+    env:
+      TESTCONTAINERS_RYUK_DISABLED: "true"
+      # Selects the Alpine userland in the Linux suite; the dev container
+      # equivalent is the same variable set on the interactive shell.
+      E2E_LINUX_BASE: alpine
     steps:
       - uses: actions/checkout@v7
         with:
           persist-credentials: false
-      - run: docker compose -f tests/e2e/linux/compose.alpine.yaml run --rm e2e
+      - uses: actions/setup-go@v6
+        with:
+          go-version: 1.27.1
+          cache: false
+      - run: go test -v -timeout 55m -run TestE2E ./linux
+        working-directory: tests/e2e
 
   e2e-windows:
     if: github.repository == 'version-fox/vfox-nodejs'

docs/e2e.md

@@ -3,7 +3,54 @@
 The offline Lua hook tests (`tests/hooks_test.lua`) run in the **Test Plugin**
 workflow. The end-to-end suite runs in containers against real vfox on Linux
 and Windows; each `vfox` x `mirror` combination gets its own throwaway
-container.
+container. On Linux, CI runs the suite natively on the stock runners (Docker
+plus Go from `actions/setup-go`), the way the repository dev container
+reproduces it locally. On Windows it runs through a Docker Compose runner
+image, since dev containers cannot host Windows container images (see below).
+
+## Dev container
+
+`.devcontainer/` opens a Linux development environment that works on all four
+host platforms:
+
+| Host                  | How the dev container runs                     |
+| --------------------- | ---------------------------------------------- |
+| Linux amd64 / arm64   | natively                                       |
+| Windows amd64 / arm64 | Docker Desktop in Linux-container mode (WSL 2) |
+
+It carries Go 1.27.1 (the version CI installs), the Docker CLI, stylua,
+lua-language-server, and the license tools — all pinned to the versions in
+`.github/workflows/lint.yml` and `license.yml` — and mounts the host Docker
+daemon socket. The suites then run testcontainers against that daemon
+(Docker-out-of-Docker), spawning the same target containers a native CI
+runner spawns; this is deliberately not Docker-in-Docker, so image cache and
+networking stay the host's. The image needs no workspace files, so the build
+context stays at `.devcontainer/`; `postCreateCommand` warms the Go module
+cache for `tests/e2e` so the first test run does not stop to download.
+
+Open it with any Dev Containers spec tool — **Dev Containers: Reopen in
+Container** in VS Code/Cursor, or the CLI:
+
+```bash
+devcontainer up --workspace-folder .
+devcontainer exec --workspace-folder . bash
+```
+
+`TESTCONTAINERS_RYUK_DISABLED=true` is preset: Ryuk publishes a port on the
+host daemon and waits for the suite to dial it back, which a
+Docker-out-of-Docker container cannot do. The suites terminate every
+container explicitly via `t.Cleanup` instead; leftovers from killed runs
+share the `vfox-nodejs-e2e-` name prefix for pruning. Rootless Docker users
+export `DOCKER_SOCK="$XDG_RUNTIME_DIR/docker.sock"` on the host before
+opening the container. On Windows hosts, keeping the checkout inside WSL 2
+(e.g. under `\\wsl$`) keeps file and bind-mount access fast; a checkout on
+the Windows filesystem works too.
+
+Windows *container* coverage (`tests/e2e/windows`) cannot run in a dev
+container: the Dev Containers spec does not support Windows container images
+([vscode-remote-release#445](https://github.com/microsoft/vscode-remote-release/issues/445)),
+and Windows containers only run on a Windows daemon. That suite keeps its
+Docker Compose runner on a Windows host; see [Windows 11](#windows-11) below.
 
 ## What the suite verifies
 
@@ -62,55 +109,59 @@ pin `VFOX_VERSION` and `MIRROR` explicitly to widen or narrow the matrix.
 | `E2E_RETRY_ATTEMPTS`| `3`                | Attempts per network-touching exec (linear 10s backoff)                 |
 | `E2E_LINUX_BASE`    | `ubuntu`           | Linux userland: `ubuntu` (glibc) or `alpine` (musl, see docs/musl.md)   |
 
-## Ubuntu
-
-Only Docker Engine (in either rootful or rootless mode) is required on the
-host. ARM64 runs the default mirror only.
+## Linux (Ubuntu)
 
-### rootful Docker
-
-Execute in Bash,
+Inside the dev container, from the repository root:
 
 ```bash
-sudo apt install --assume-yes git
-git clone git@github.com:version-fox/vfox-nodejs.git
-cd ./vfox-nodejs/
-docker compose -f tests/e2e/linux/compose.yaml run --rm e2e
+cd tests/e2e
+go test -v -timeout 55m -run TestE2E ./linux
 ```
 
-### rootless Docker
-
-With rootless Docker the daemon socket lives elsewhere; point `DOCKER_SOCK`
-at it instead:
+Scope it down while iterating the same way:
 
 ```bash
-sudo apt install --assume-yes git
-git clone git@github.com:version-fox/vfox-nodejs.git
-cd ./vfox-nodejs/
-DOCKER_SOCK="$XDG_RUNTIME_DIR/docker.sock" docker compose -f tests/e2e/linux/compose.yaml run --rm e2e
+VFOX_VERSION=latest MIRROR=default E2E_MAX_JOBS=1 go test -v -timeout 55m -run TestE2E ./linux
 ```
 
+On a native host the same command works with two prerequisites — Docker
+Engine (rootful or rootless) and Go 1.27.1 — which is exactly what CI
+provisions. Rootless Docker users point the Docker client at their socket
+(`export DOCKER_HOST="unix://$XDG_RUNTIME_DIR/docker.sock"`); the dev
+container's socket mount covers that case for you. ARM64 runs the default
+mirror only.
+
 ## Alpine (musl)
 
-Same host requirement. The Alpine suite builds
-`tests/e2e/linux/Dockerfile-alpine` (musl userland with `libstdc++`) and
-asserts the musl userland before running the standard flow, proving the
-plugin selects the `*-musl` tarballs
+The Alpine suite builds `tests/e2e/linux/Dockerfile-alpine` (musl userland
+with `libstdc++`) and asserts the musl userland before running the standard
+flow, proving the plugin selects the `*-musl` tarballs
 ([issue #29](https://github.com/version-fox/vfox-nodejs/issues/29)).
 See [docs/musl.md](musl.md) for the tarball matrix.
 
+Set `E2E_LINUX_BASE` to switch the same Linux suite onto the Alpine image:
+
 ```bash
-docker compose -f tests/e2e/linux/compose.alpine.yaml run --rm e2e
+cd tests/e2e
+E2E_LINUX_BASE=alpine go test -v -timeout 55m -run TestE2E ./linux
 ```
 
-Scope it down locally the same way, e.g.
-`VFOX_VERSION=latest MIRROR=default E2E_MAX_JOBS=1` in front of the command.
+CI exports the same variable in its musl job; the dev container needs
+nothing else.
 
-## Windows 11 Pro
+## Windows 11
 
 Windows containers cannot be emulated across architectures, so the ARM64
 suite needs an ARM64 host (a Copilot+ PC or the `windows-11-arm` CI runner).
 
+There is no dev container for this suite — the Dev Containers spec rejects
+Windows container images (see [Dev container](#dev-container)) — so it keeps
+its Docker Compose runner. The runner image (`Dockerfile-runner`: stock
+servercore plus the pinned Go MSI) drives the host daemon through the mounted
+named pipe; the host requirement is Docker in Windows-container mode plus the
+Compose v5 plugin (installed once per machine below). Go never touches the
+host, so it cannot conflict with a vfox-managed toolchain.
+
 The `windows-11-arm` runner has no Windows Hypervisor Platform feature, so
 Hyper-V isolation is unavailable; process isolation needs only the
 Containers feature.
@@ -191,6 +242,12 @@ curl.exe -fsSL `
 docker compose -f tests/e2e/windows/compose.arm64.yaml run --rm --build e2e
 ```
 
+On arm64, Go is also what builds the engine, so `install-docker-arm64.ps1`
+runs before the suite; the compose runner image then carries its own pinned
+Go for the tests, and the host Go is not used again. Scope the run down with
+`$env:VFOX_VERSION = 'latest'; $env:MIRROR = 'default'` in front of the
+compose command, as on the other platforms.
+
 ## WSL
 
 The WSL suite (`tests/e2e/wsl/`) drives the Ubuntu distribution on the
@@ -208,6 +265,9 @@ Combos share one distro and run sequentially, each isolated in
 its own `HOME`/`VFOX_HOME` slot. `MIRROR` defaults apply as usual; CI pins
 `MIRROR=default` to keep the run to the `latest`/`main` vfox channels.
 
+It runs from the Windows host (it needs `wsl.exe` and the installed distro),
+not from the dev container.
+
 ### CI
 
 The `WSL (windows-2025)` job installs `Ubuntu-24.04` with
@@ -231,14 +291,11 @@ go test -v -timeout 55m -run TestE2E ./wsl
 
 ## Local checks
 
-Execute in Bash on Ubuntu before pushing.
+Execute from the dev container — everything below is preinstalled and pinned
+to the versions the workflows use — or provision the same tools on a host.
 
 ```bash
-docker run --rm -v "$PWD:/work" -w /work apache/skywalking-eyes:0.9.0 header check
-docker run --rm -v "$PWD:/work" -w /work apache/skywalking-eyes:0.9.0 header fix
-docker run --rm -v "$PWD:/src" ghcr.io/google/addlicense:v1.2.0 -check -f .license.tpl tests/e2e/windows/*.ps1
-docker run --rm -v "$PWD:/src" ghcr.io/google/addlicense:v1.2.0 -f .license.tpl tests/e2e/windows/*.ps1
-
+# Lua and Go checks (.github/workflows/lint.yml).
 cd tests/e2e
 go test -short ./...
 test -z "$(gofmt -l .)"
@@ -248,5 +305,23 @@ cd ../..
 go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/hooks_test.lua
 
 stylua --check .
-mise x aqua:LuaLS/lua-language-server@3.19.1 -- lua-language-server --check . --checklevel=Warning
+lua-language-server --check . --checklevel=Warning
+```
+
+```bash
+# License headers (.github/workflows/license.yml).
+license-eye header check
+license-eye header fix
+addlicense -check -f .license.tpl tests/e2e/windows/*.ps1
+addlicense -f .license.tpl tests/e2e/windows/*.ps1
+```
+
+On a Docker-only host the license checks run as containers instead (the same
+images CI uses):
+
+```bash
+docker run --rm -v "$PWD:/work" -w /work apache/skywalking-eyes:0.9.0 header check
+docker run --rm -v "$PWD:/work" -w /work apache/skywalking-eyes:0.9.0 header fix
+docker run --rm -v "$PWD:/src" ghcr.io/google/addlicense:v1.2.0 -check -f .license.tpl tests/e2e/windows/*.ps1
+docker run --rm -v "$PWD:/src" ghcr.io/google/addlicense:v1.2.0 -f .license.tpl tests/e2e/windows/*.ps1
 ```

tests/e2e/doc.go

@@ -21,7 +21,7 @@
 //   - common: target-independent shared logic (matrix expansion, version
 //     defaults, retry counts, name handling);
 //   - linux: the Linux container suite (bash-driven), run in CI and locally
-//     via tests/e2e/linux/compose.yaml;
+//     through the repository dev container (.devcontainer/, see docs/e2e.md);
 //   - windows: the Windows container suite (pwsh-driven), run via
 //     tests/e2e/windows/compose.amd64.yaml (amd64) or
 //     tests/e2e/windows/compose.arm64.yaml (arm64).