Files
UniversalTrain-ai/tests/test_setup_skill.py
T
chenlin d5e9004f6c
Checks / Layout, translation and Colab checks (push) Has been cancelled
Checks / Ruff (push) Has been cancelled
Checks / Framework tests (native backend, CPU) (push) Has been cancelled
Checks / Portable Rust controller (push) Has been cancelled
docs: add AI agent workflow guide and clean up residual single-robot references
2026-11-05 11:52:07 +08:00

259 lines
11 KiB
Python

"""The environment-setup skill under `.claude/skills/setup-env/`.
The skill exists so that getting this repository running on a new machine is a
measured procedure rather than a remembered one. Its two scripts are the part
that can rot silently: they encode decisions (which torch wheel, which paths
count as "this checkout") that are right today and would keep printing confident
output after becoming wrong.
They are checked here rather than by running them, because what matters is the
decisions, and the decisions can be exercised on any machine -- including the
Blackwell case, which no CI runner is going to have.
"""
from __future__ import annotations
import importlib.util
import subprocess
import sys
from pathlib import Path
import pytest
REPO = Path(__file__).resolve().parents[1]
SKILL = REPO / ".claude" / "skills" / "setup-env"
def _load(name: str):
spec = importlib.util.spec_from_file_location(name, SKILL / "scripts" / f"{name}.py")
assert spec and spec.loader
mod = importlib.util.module_from_spec(spec)
spec.loader.exec_module(mod)
return mod
def test_the_skill_is_complete() -> None:
"""A skill missing a piece fails at the moment someone needs it most."""
assert (SKILL / "SKILL.md").is_file()
for script in ("detect.py", "gates.py"):
assert (SKILL / "scripts" / script).is_file(), f"{script} is missing"
def test_frontmatter_declares_name_and_description() -> None:
"""Both are required, and the description is what decides whether the skill
is ever consulted -- it is the only part most readers see."""
text = (SKILL / "SKILL.md").read_text(encoding="utf-8")
assert text.startswith("---\n"), "SKILL.md needs YAML frontmatter"
front = text.split("---", 2)[1]
assert "\nname: setup-env" in front
assert "\ndescription:" in front
body = text.split("---", 2)[2]
assert "docs/AGENT_SETUP.md" in body, (
"the skill must point at the reference doc rather than replace it"
)
def test_detect_runs_on_an_interpreter_it_cannot_choose() -> None:
"""`detect.py` answers "is this Python usable", so it must run on one that
is not.
It is invoked with whatever the machine already has -- possibly a 3.8 that
the repository does not support. Importing a dependency, or using syntax
newer than it needs, would turn "your interpreter is too old" into a
SyntaxError with no explanation attached.
"""
src = (SKILL / "scripts" / "detect.py").read_text(encoding="utf-8")
imports = {
ln.split()[1].split(".")[0]
for ln in src.splitlines()
if ln.startswith("import ") or ln.startswith("from ")
}
# All of these predate 3.6; `shutil.which` is the newest, from 3.3.
stdlib = {"__future__", "glob", "os", "platform", "re", "shutil", "subprocess", "sys"}
assert imports <= stdlib, (
f"detect.py may only use the standard library, found: {sorted(imports)}"
)
assert ":=" not in src, "the walrus operator needs 3.8; keep this runnable on older ones"
# And it must actually run to completion, exit 0, on this interpreter.
out = subprocess.run([sys.executable, str(SKILL / "scripts" / "detect.py")],
cwd=REPO, capture_output=True, text=True, timeout=120)
assert out.returncode == 0, out.stderr
assert "== commands ==" in out.stdout
@pytest.mark.parametrize(
("has_gpu", "cap", "expect"),
[
(True, "12.0", "cu128"), # Blackwell: cu126 installs cleanly and dies in CUDA init
(True, "8.9", "cu128"), # Ada: cu128 is backward compatible, so it is never wrong here
(True, "8.6", "cu128"), # Ampere: same
(False, None, None), # no GPU (all of macOS): CPU build, and no --index-url
],
)
def test_the_torch_wheel_follows_from_the_measured_capability(has_gpu, cap, expect) -> None:
"""Choosing the wheel is the only step that branches, and the expensive
direction is asymmetric.
Too new a CUDA build costs nothing on Ada/Ampere; too old a one on Blackwell
installs without complaint and fails when CUDA initialises, which reads as a
driver problem. So "unknown or >= 8.0 -> cu128" is deliberate, not vague.
"""
cmd, _why = _load("detect").torch_plan(has_gpu, cap)
if expect is None:
assert "--index-url" not in cmd, "the CPU build must not be pointed at a CUDA index"
assert "torch" in cmd
else:
assert expect in cmd, cmd
def test_an_ancient_card_is_referred_upward_rather_than_guessed() -> None:
"""Below 8.0 there is no single right answer, and inventing one would send
someone down a long wrong path."""
cmd, why = _load("detect").torch_plan(True, "7.5")
assert "pytorch.org" in cmd or "pytorch.org" in why
assert "cu128" not in cmd
def test_the_repo_is_found_by_content_not_by_name() -> None:
"""The checkout is routinely named something else.
`mjrl-lab` on the training machine, or a hashed path inside `.claude/
worktrees/` here. Matching on the directory name would fail on exactly the
machines this is needed for.
"""
gates = _load("gates")
assert gates.find_repo(Path(__file__).parent) == REPO
assert gates.find_repo(Path(REPO.anchor)) is None
def test_gate_c_compares_against_this_checkout_not_site_packages() -> None:
"""The published gate rules out `site-packages`, which is not enough.
An editable install left pointing at an older copy of the repository passes
that check and still runs another checkout's code -- measured on a training
machine on 2026-09-04, where `tasks` resolved from the current repository
and `mjlab` from a snapshot three days stale. Everything imported; the seam
being edited was not the seam being run. So the comparison has to be against
the repository root.
"""
src = (SKILL / "scripts" / "gates.py").read_text(encoding="utf-8")
body = src.split("def gate_c_vendored", 1)[1].split("\n # ", 1)[0]
code = "\n".join(ln for ln in body.splitlines() if not ln.strip().startswith("#"))
assert "self.repo" in code, "gate C must compare against the repository root"
assert '"site-packages"' not in code, (
"a site-packages substring check is the weaker test this replaces"
)
def test_wasm_bindgen_is_held_to_the_lock_not_the_manifest() -> None:
"""The CLI must equal the crate's wasm-bindgen exactly, and only
`Cargo.lock` says what that is.
`Cargo.toml` says `"0.2"`, a range every 0.2.x satisfies. Both scripts read
the lock, as `scripts/deploy.py` does, and agree.
The control is the manifest's own version: if it ever named the full
version, the lock and the manifest would be indistinguishable here and
this test would pass whichever file the scripts read.
"""
import re
detect, gates = _load("detect"), _load("gates")
locked = detect.locked_version(str(REPO), "wasm-bindgen")
assert locked == gates.locked_version(REPO, "wasm-bindgen")
assert locked and re.fullmatch(r"\d+\.\d+\.\d+", locked), locked
manifest = (REPO / "deploy" / "fsm" / "Cargo.toml").read_text(encoding="utf-8")
declared = re.search(r'^wasm-bindgen\s*=\s*\{[^}]*version\s*=\s*"([^"]+)"', manifest, re.M)
assert declared and declared.group(1) != locked, (
"the manifest now pins the full version; this test no longer tells the files apart"
)
rust = _complete_rust(wasm_bindgen="0.2.0")
assert f"cargo install wasm-bindgen-cli --version {locked} --locked" in (
detect.rust_commands("Linux", dict(rust, wasm_bindgen_wanted=locked)))
def _complete_rust(**changes):
"""`detect_rust`'s answer for a machine that has everything."""
rust = {
"cargo": "/c/cargo", "on_path": True, "rustup": "/c/rustup",
"rustc_text": "1.98.1", "rustc": (1, 98, 1), "wasm32": True,
"wasm_bindgen": "0.2.128", "wasm_bindgen_wanted": "0.2.128", "cc": "/usr/bin/cc",
"idlc": "/usr/local/bin/idlc", "idlc_text": "11.0.1", "dds_home": "/usr/local",
"dds_headers": True, "libclang": "/usr/lib/libclang.so", "npu_header": True,
}
rust.update(changes)
return rust
def test_only_the_missing_rust_steps_are_printed() -> None:
"""The toolchain is per machine, not per checkout, so a second checkout
must be told "nothing missing" rather than handed an installer to re-run.
And the step that is printed has to be the one that is missing: a
distribution's cargo answers `cargo --version` and cannot add the wasm
target, so its presence must not suppress the rustup install.
"""
detect = _load("detect")
assert detect.rust_commands("Linux", _complete_rust()) == []
assert detect.device_commands("Linux", _complete_rust()) == []
distro = detect.rust_commands("Linux", _complete_rust(rustup=None, wasm32=False))
assert any("sh.rustup.rs" in step for step in distro), distro
assert "rustup target add wasm32-unknown-unknown" in distro
assert detect.rust_commands("Linux", _complete_rust(wasm32=False)) == [
"rustup target add wasm32-unknown-unknown"]
assert detect.rust_commands("Linux", _complete_rust(rustc=(1, 75, 0))) == [
"rustup update stable"]
# An idlc that is installed and does not run is the loader, not a missing
# CycloneDDS: the answer is ldconfig, not a second source build.
broken = detect.device_commands("Linux", _complete_rust(idlc_text=None))
assert len(broken) == 1 and "ldconfig" in broken[0], broken
# Rockchip's NPU header is the one per-checkout step: a checkout without it
# is told to fetch it on a machine that has everything else. The complete
# case above is the control.
assert detect.device_commands("Linux", _complete_rust(npu_header=False)) == [
"bash deploy/fsm/vendor/rknpu2/fetch.sh # Rockchip's NPU header, once per checkout"]
# macOS gets a measured procedure of its own rather than the "measured on
# Linux only" comment it used to: a source build into a prefix under $HOME,
# with no sudo and no ldconfig (the crate writes its rpath instead), and the
# exports the build takes the rpath from. The complete case is the control
# again: a machine with everything is told nothing on this platform too.
assert detect.device_commands("Darwin", _complete_rust()) == []
mac = detect.device_commands("Darwin", _complete_rust(idlc=None, idlc_text=None,
dds_headers=False))
assert not any("sudo" in step or "ldconfig" in step for step in mac), mac
assert any("CMAKE_INSTALL_PREFIX=$HOME/" in step for step in mac), mac
assert any(step.startswith("export CYCLONEDDS_HOME=$HOME/") for step in mac), mac
def test_gate_d_accepts_empty_registry_and_checks_discovered_ids(tmp_path, monkeypatch) -> None:
gates = _load("gates")
task_root = tmp_path / "tasks"
task_root.mkdir()
output = {"text": "The registry is empty.\n"}
def listing(*args, **kwargs):
return subprocess.CompletedProcess(args, 0, stdout=output["text"], stderr="")
monkeypatch.setattr(gates.subprocess, "run", listing)
check = gates.Gates(tmp_path)
check.gate_d_registry()
assert check.failed == []
task = task_root / "sample_robot"
task.mkdir()
(task / "robot_spec.py").touch()
output["text"] = "task id description\n------- -----------\nsample_robot Biped\n\nscene\nstudio\n"
check.gate_d_registry()
assert check.failed == []
output["text"] = output["text"].replace("sample_robot", "wrong_robot")
check.gate_d_registry()
assert check.failed == ["D task registry"]