docker-test-shell
Use when testing in a clean throwaway container.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 2
- Forks
- 2
01 前言 Front Matter
- name
- docker-test-shell
- author
- Hermes Agent
- license
- MIT
- version
- 1.0.0
- platforms
- [ "linux" ]
- description
- Use when testing in a clean throwaway container.
02 资源文件 1
- 参考文档references/dts-usage.md4.1 KB
03 SKILL.md 正文
Docker Test Shell (dts)
Test ANY tool inside a fresh, throwaway Linux container — never trust the host.
The one concept
Test inside a throwaway container so your own environment's installed libs, stale state, and services do not pollute the test.
That is the entire tool. No test framework, no schema, no verify primitives. Just: get me into a clean container with my repo mounted in, and let me run commands. Target logic is PLAIN SHELL composed of dts exec + bash checks.
Quickstart
# from the repo you want to test (it gets bind-mounted at /src)
./scripts/dts.sh up
./scripts/dts.sh exec "bash /src/install.sh"
./scripts/dts.sh exec "my-tool --version"
./scripts/dts.sh clean
For convenience, add the script dir to PATH or alias dts:
export PATH="$PWD/scripts:$PATH" # or symlink dts.sh -> /usr/local/bin/dts
Commands
| Command | Job |
|---|---|
dts up |
Create container (fresh base, repo bind-mounted at /src, uid-1000 user). Installs NOTHING. |
dts exec "<cmd>" |
Run <cmd> inside the container as the uid-1000 user, bash -l. TTY-aware. |
dts apt "<pkgs>" |
Run apt-get update && install -y <pkgs> as ROOT. The one privileged path (apt needs root; normal user can't). |
dts shell |
Drop into an interactive shell (-it). For a human at a terminal. |
dts clean |
Remove the container (no orphans). |
dts status |
Show container state + note the mount is present. |
When to use dts exec vs raw docker exec
| Scenario | Use | Why | Notes |
|---|---|---|---|
| Normal test commands (build, version check, API call) | dts exec |
Runs as uid-1000, bash -l, -i no -t — matches CI/Codespace parity |
|
Install apt packages (apt-get install) |
dts apt |
Dedicated root path; apt needs root, uid-1000 can't | |
| Debug interactively (human at terminal) | dts shell |
-it gives full interactive TTY |
|
| One-off root inspection (logs, sqlite, config files) | docker exec -u 0:0 dts-test <cmd> |
Root-only operations outside apt; explicit docker exec -u 0:0 signals intent |
|
| Multi-step stateful commands from a script | dts exec with piped stdin |
printf 'cmd1\ncmd2\n' | dts exec bash — stdin stays open, runs sequentially |
Rule of thumb: dts exec = the test harness path (uid-1000, parity). Raw docker exec -u 0:0 = the escape hatch for root-only ops that aren't apt installs (e.g. reading sqlite DBs, checking process ports, killing stuck processes). Don't run test commands as root — it masks permission bugs that would fail in CI/Codespace.
Config
- Base image: configurable via
IMAGE, defaults toubuntu:24.04:IMAGE=debian:12 dts up IMAGE=node:22 dts up - Container name:
CONTAINER(defaultdts-test). - Mount target: always
/src. Static, predictable. - uid/gid:
CONTAINER_UID/CONTAINER_GID(default 1000).
The golden rules (each verified by live testing)
- Never trust the host. Always repro in the container. The host has stale packages, leftover venvs, running services — a passing host test proves nothing about a fresh install.
- Drive with
docker exec -i, never-it, when scripted.-itfails with "the input device is not a TTY" when stdin is piped (an agent's normal mode).-ikeeps stdin open, runs scripted AND stateful REPL-style commands fine. Reserve-itfor a real human typing. - Use
bash -l(login shell). Plainbash -cis non-interactive and doesn't source.profile. Login shell gives host/CI parity. - Run as uid 1000, never root. CI runner + Codespaces both run uid 1000; root masks permission bugs.
dtsdoes this automatically. - Install apt packages with
dts apt, neverdts exec— apt (and other package managers) need root, but the container's normal user runs as uid 1000 and can't. Use the dedicated root path:dts apt "curl g++ make" # apt-get update && install -y, as rootdts execis the uid-1000 path for the actual test commands. Different targets need different prereqs; keep the tool minimal and make the choice explicit per test. - Verify the mount with md5, not just listing. Listing can lie; md5 proves same file (host write appears in container, container write appears on host, file md5-identical both sides).
- Clean up after yourself. No orphan containers.
dts clean.
Verification is plain shell
There are no verify subcommands. Check exit codes, grep output, curl endpoints:
dts exec "hermes --version" && echo "install OK"
dts exec "curl -sf http://127.0.0.1:20128/healthz && echo server-up"
Non-goals
- No test-definition / YAML schema (target logic = a short bash script).
- No
verifysubcommands. - No Dockerfile / image build (bind-mount + base image, no rebuild cycle).
- No persistent SSH-like daemon (
docker exec -i+ piped stdin reproduces a stateful session). - No bundled apt prereqs.
How to teach/perpetuate this
- Never trust the host — always repro in a fresh container.
- Learn the target iteratively in
shellmode (or one-offexec): poke, observe, confirm, then codify. - Codify as a short bash script of
dts exec+ checks — repeatable, and arguably CI-run-able. - Record each pitfall with root cause + fix (as references/ here or a wiki article).
Pitfalls table (hard-won)
| Pitfall | Root cause | Fix |
|---|---|---|
| "input device is not a TTY" when scripted | docker exec -it needs a host PTY |
Use -i (no -t) when stdin is piped; -it only for a real human |
No .profile sourced |
bash -c is non-interactive |
Use bash -l (login shell) |
| Permission bugs masked | Tested as root | Always run as uid 1000 (CI/Codespace parity) |
| Mount "works" but file is stale | Bind-mount created once; container cached | Verify with md5 both sides; never trust a listing |
| Orphan containers eat disk | No cleanup | dts clean after each session |
rm -rf ~/.minions fails "Device or resource busy" in DTS |
Host ollama cache mounted at $MINIONS_HOME/lib/ollama via -v /tmp/...:/home/.../lib/ollama — rm -rf cannot remove a mountpoint |
Mount cache outside the tree (/tmp/cache:ro) instead; if legacy mount remains, unmount with umount -l plus sudo umount -l fallback (container runs as uid 1000) |
mkdir -p lib/ollama fails "Read-only filesystem" through symlink |
Dir symlink lib/ollama -> /tmp/cache:ro makes mkdir -p traverse the ro target |
Symlink files not dirs: lib/ollama/ollama -> /tmp/cache/ollama; mkdir -p lib/ollama then creates a real dir |
mkdir ~/.minions fails "Permission denied" in DTS |
Base image pre-creates $HOME owned by root; conditional [ -d $home ] or chown skipped the fix |
Always mkdir -p $home && chown $uid:$gid $home unconditionally in dts up |
| Cache not mounted so install re-downloads and fails | Version string v0.40.0 vs cache dir ollama-0.40.0-... — un-stripped v leaves OLLAMA_HOST_CACHE empty |
Normalize version=${version#v} and map arch aliases before building the cache path |
bash install.sh | tee log reports success while install failed |
Pipe exit is tee's 0 when pipefail is off, masking left-side failure |
Prefix with set -o pipefail; cmd | tee log |
npm install OOM JavaScript heap out of memory |
NODE_OPTIONS --max-old-space-size=512 too small for large package in constrained DTS/CI |
Raise to 2048 in shared install_npm_package wrapper |
.tar.zst fails stdin: not in gzip format or zstd required |
Missing zstd in DTS container and tar -xzf used for .tar.zst (needs --zstd/-I zstd) |
Install zstd in dts apt prereqs; extract via zstd -dc | tar -xf or tar --zstd -xf; prefer host cache copy /tmp/ollama-cache/ollama on reinstall to avoid re-download |
| New optional binary re-downloads every DTS run | No *_HOST_CACHE mount for the new dep — same trap as Ollama before OLLAMA_HOST_CACHE |
Mirror the Ollama pattern: mount host cache at /tmp/<name>-cache:ro (outside MINIONS_HOME), add TAILSCALE_HOST_CACHE handling in scripts/dts.sh and a fast-path if [ -f /tmp/<name>-cache/<bin> ] in lib/<name>.sh |
Daemon needs TUN/NET_ADMIN but tests run as uid 1000 |
tailscaled fails to create TUN, or second daemon collides on control socket when systemd already runs one |
Default to --tun=userspace-networking with --statedir + --socket under MINIONS_HOME (TAILSCALE_SOCKET), presence-gate boot on command -v, guard systemctl is-active/pgrep before start_service, and keep status.sh/self-check.sh set -e-safe |
Support files
scripts/dts.sh— the tool itself (up/exec/shell/clean/status).references/dts-usage.md— worked examples + how the golden rules were validated.
Related
- Wiki: docker-test-shell-proposal.md — full design rationale.
- This skill replaces the project-specific
minions-docker-testingapproach with a standalone primitive.
04 同仓库更多 Skills
version-single-source
Use when adding a new component dependency or versioning a binary in install/boot scripts.
tdd
Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
shell-path-login
Use when a binary or script works in one shell context but not another (interactive vs non-interactive login vs non-login shell).
self-update-fix
Fix a failing dependency update PR. Use when a self-update PR's CI fails, or when invoked by scripts/self-update-fix.sh.
pr-change-log
Use when a multi-commit PR needs its description written/updated, or when closing out a long branch with many fix commits.
persistent-knowledge
Persistent skills/knowledge in Codespace via symlinks.