Files
UniversalTrain-ai/tests/test_dotenv.py
T
chenlin c32df70326
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
release: v0.1 generic robot training and application platform
2026-11-05 11:05:01 +08:00

349 lines
14 KiB
Python

"""Parsing `.env` and its precedence chain.
The chain rests on one rule: **`load_dotenv` does not overwrite existing
environment variables**. argparse defaults then read from `os.environ`, so
command line > shell environment > .env.local > .env > built-in default
follows for free, with no need to ask "did the user give this explicitly" -- which
is exactly the kind of judgement a config layer gets wrong.
"""
from __future__ import annotations
import importlib.util
import os
from pathlib import Path
import pytest
from mjrl.dotenv import env_choice, env_default, env_flag, load_dotenv, parse_dotenv
REPO = Path(__file__).resolve().parents[1]
# ── Parsing ───────────────────────────────────────────────────────────────
def test_basic_key_value() -> None:
assert parse_dotenv("A=1\nB=two\n") == {"A": "1", "B": "two"}
def test_comments_and_blank_lines_ignored() -> None:
text = "# a comment\n\n \nA=1\n # an indented comment\n"
assert parse_dotenv(text) == {"A": "1"}
def test_export_prefix_accepted() -> None:
assert parse_dotenv("export A=1\n") == {"A": "1"}
def test_inline_comment_stripped() -> None:
assert parse_dotenv("A=1 # explanation\n") == {"A": "1"}
def test_quoted_value_keeps_spaces_and_hash() -> None:
"""A `#` inside quotes is not a comment. A path containing one is rare, but
silent truncation would be very hard to trace."""
assert parse_dotenv('A="a b # c"\n') == {"A": "a b # c"}
assert parse_dotenv("A='x y'\n") == {"A": "x y"}
def test_empty_value_is_kept_as_empty_string() -> None:
assert parse_dotenv("A=\n") == {"A": ""}
def test_line_without_equals_is_ignored() -> None:
"""Tolerate stray prose, so one line of notes does not stop every entry point
from starting."""
assert parse_dotenv("this is a sentence\nA=1\n") == {"A": "1"}
def test_value_containing_equals_is_not_split_again() -> None:
assert parse_dotenv("A=k=v\n") == {"A": "k=v"}
# ── Precedence ────────────────────────────────────────────────────────────
def test_existing_env_var_is_not_overwritten(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A value exported explicitly in the shell must beat .env -- the whole
precedence chain rests on this."""
monkeypatch.setenv("MJRL_TEST_KEY", "from_shell")
env = tmp_path / ".env"
env.write_text("MJRL_TEST_KEY=from_file\n", encoding="utf-8")
applied = load_dotenv(env)
assert "MJRL_TEST_KEY" not in applied
assert os.environ["MJRL_TEST_KEY"] == "from_shell"
def test_later_file_wins(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
""".env.local comes after .env and therefore overrides it."""
monkeypatch.delenv("MJRL_TEST_KEY", raising=False)
(tmp_path / ".env").write_text("MJRL_TEST_KEY=base\n", encoding="utf-8")
(tmp_path / ".env.local").write_text("MJRL_TEST_KEY=local\n", encoding="utf-8")
load_dotenv(tmp_path / ".env", tmp_path / ".env.local")
assert os.environ["MJRL_TEST_KEY"] == "local"
def test_missing_file_is_not_an_error(tmp_path: Path) -> None:
""".env.local usually does not exist, and a missing file must not crash an
entry point."""
assert load_dotenv(tmp_path / "nope.env") == {}
def test_empty_value_counts_as_unset(monkeypatch: pytest.MonkeyPatch) -> None:
"""`MJRL_MODEL=` in `.env` means "leave it empty, use the built-in default",
not the empty string as a value."""
monkeypatch.setenv("MJRL_TEST_KEY", " ")
assert env_default("MJRL_TEST_KEY") is None
assert env_default("MJRL_TEST_KEY", "fallback") == "fallback"
# ── Switches ──────────────────────────────────────────────────────────────
@pytest.mark.parametrize("raw", ["on", "ON", "On", "true", "TRUE", "yes", "1", " on "])
def test_every_spelling_of_on(raw: str, monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setenv("MJRL_TEST_FLAG", raw)
assert env_flag("MJRL_TEST_FLAG", fallback=False) is True
@pytest.mark.parametrize("raw", ["off", "OFF", "Off", "false", "FALSE", "no", "0", " off "])
def test_every_spelling_of_off(raw: str, monkeypatch: pytest.MonkeyPatch) -> None:
"""`MJRL_TENSORBOARD=OFF` must turn it off.
This was the whole bug: the test was `!= "off"`, so every spelling but the
lowercase one left the feature **on** -- and there is nothing in the output to
say the setting was ignored, so it reads as a switch that does not work.
"""
monkeypatch.setenv("MJRL_TEST_FLAG", raw)
assert env_flag("MJRL_TEST_FLAG", fallback=True) is False
def test_unset_or_empty_takes_the_fallback(monkeypatch: pytest.MonkeyPatch) -> None:
"""`MJRL_TENSORBOARD=` in `.env` means "use the built-in default", exactly as
an empty `MJRL_MODEL` does."""
monkeypatch.delenv("MJRL_TEST_FLAG", raising=False)
assert env_flag("MJRL_TEST_FLAG", fallback=True) is True
monkeypatch.setenv("MJRL_TEST_FLAG", " ")
assert env_flag("MJRL_TEST_FLAG", fallback=False) is False
@pytest.mark.parametrize("raw", ["of", "nope", "onn", "2", "-"])
def test_anything_else_raises_rather_than_falling_back(
raw: str, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A value that is not a switch must not quietly become the default.
`MJRL_TENSORBOARD=of` reading as "on" is invisible: the feature behaves
normally and nothing mentions the setting. Erroring names the value, the way
a non-integer `MJRL_NUM_ENVS` does.
"""
monkeypatch.setenv("MJRL_TEST_FLAG", raw)
with pytest.raises(ValueError, match="MJRL_TEST_FLAG"):
env_flag("MJRL_TEST_FLAG", fallback=True)
# ── One of a fixed set of values ──────────────────────────────────────────
def test_a_choice_is_matched_case_insensitively(monkeypatch: pytest.MonkeyPatch) -> None:
"""And comes back in the spelling the choices use, so callers can compare it."""
monkeypatch.setenv("MJRL_TEST_CHOICE", "OFF")
assert env_choice("MJRL_TEST_CHOICE", ("auto", "on", "off"), "auto") == "off"
monkeypatch.setenv("MJRL_TEST_CHOICE", " Auto ")
assert env_choice("MJRL_TEST_CHOICE", ("auto", "on", "off"), "auto") == "auto"
def test_a_choice_outside_the_set_raises(monkeypatch: pytest.MonkeyPatch) -> None:
"""The value must not travel on to whatever consumes the argument.
`MJRL_STRIP_VISUAL=gpu` reaching the backend is not a config error any more --
it is a `KeyError` or a wrong run, somewhere with no mention of `.env`.
"""
monkeypatch.setenv("MJRL_TEST_CHOICE", "gpu")
with pytest.raises(ValueError, match="auto, on, off"):
env_choice("MJRL_TEST_CHOICE", ("auto", "on", "off"), "auto")
def test_an_unset_choice_takes_the_fallback(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.delenv("MJRL_TEST_CHOICE", raising=False)
assert env_choice("MJRL_TEST_CHOICE", ("auto", "on"), "auto") == "auto"
# ── Reaching argparse: where these defaults actually land ─────────────────
def _parse(
argv: list[str],
env: dict[str, str],
monkeypatch: pytest.MonkeyPatch,
*,
replay: bool = False,
):
"""Parse arguments the way an entry point does, and hand back `_cli` with them.
`replay` builds play's parser rather than train's.
`scripts/` is not a package and no test may put it on `sys.path`
(`test_no_sys_path_mutation` in test_layout.py), so `_cli` is loaded from its
file. Going through the real parser is the point: **argparse checks `choices`
only for values typed on the command line, never for a default**, so a bad
value in `.env` is caught here or not at all.
"""
for key, value in env.items():
monkeypatch.setenv(key, value)
spec = importlib.util.spec_from_file_location("_cli_under_test", REPO / "scripts" / "_cli.py")
assert spec and spec.loader
cli = importlib.util.module_from_spec(spec)
spec.loader.exec_module(cli)
prog = "play.py" if replay else "train.py"
return cli, cli.build_parser(prog, "", replay=replay).parse_args(argv)
def test_a_choice_from_dotenv_is_normalised(monkeypatch: pytest.MonkeyPatch) -> None:
"""`MJRL_STRIP_VISUAL=OFF` used to reach `resolve_all` verbatim and die there
as `KeyError: 'OFF'`, with `.env` nowhere in the traceback."""
cli, args = _parse([], {"MJRL_STRIP_VISUAL": "OFF", "MJRL_BACKEND": "WARP"}, monkeypatch)
assert args.strip_visual == "off"
assert args.backend == "warp"
# The value has to be usable by what consumes it, which is the lookup table.
assert cli.STRIP_VISUAL[args.strip_visual] is False
@pytest.mark.parametrize(
"env", [{"MJRL_STRIP_VISUAL": "nope"}, {"MJRL_BACKEND": "gpu"}]
)
def test_a_bad_choice_in_dotenv_stops_the_run(
env: dict, monkeypatch: pytest.MonkeyPatch
) -> None:
with pytest.raises(SystemExit):
_parse([], env, monkeypatch)
def test_the_command_line_still_wins(monkeypatch: pytest.MonkeyPatch) -> None:
_, args = _parse(["--strip-visual", "on"], {"MJRL_STRIP_VISUAL": "OFF"}, monkeypatch)
assert args.strip_visual == "on"
def test_the_choices_and_the_lookup_table_are_one_definition(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""What argparse accepts and what `resolve` is handed must not drift apart.
They were two separate literals, so a fourth `--strip-visual` state added to
the argument alone would pass the parser and be a `KeyError` in `resolve_all`.
"""
cli, _ = _parse([], {}, monkeypatch)
action = next(a for a in cli.build_parser("t", "")._actions if a.dest == "strip_visual")
assert set(action.choices) == set(cli.STRIP_VISUAL)
# ── Two counts under one flag ─────────────────────────────────────────────
def test_play_does_not_take_trainings_batch_size(monkeypatch: pytest.MonkeyPatch) -> None:
"""`MJRL_NUM_ENVS` is PPO's batch size, and a replay does not read it.
Sharing one key, the repository's 4096 built 4096 native CPU environments to
replay an app's controller that reads one, and never got past building them.
`MJRL_PLAY_NUM_ENVS` is set empty so that this pins the built-in 1 rather than
whatever `.env` says. Train, parsed from the same environment, is the
control: it still gets 4096, so the key was not simply dropped.
"""
env = {"MJRL_NUM_ENVS": "4096", "MJRL_PLAY_NUM_ENVS": ""}
_, play = _parse([], env, monkeypatch, replay=True)
_, train = _parse([], env, monkeypatch)
assert play.num_envs == 1
assert train.num_envs == 4096
def test_play_reads_its_own_key_and_the_command_line_still_wins(
monkeypatch: pytest.MonkeyPatch,
) -> None:
env = {"MJRL_NUM_ENVS": "4096", "MJRL_PLAY_NUM_ENVS": "16"}
_, play = _parse([], env, monkeypatch, replay=True)
_, train = _parse([], env, monkeypatch)
_, typed = _parse(["--num_envs", "8"], env, monkeypatch, replay=True)
assert (play.num_envs, train.num_envs, typed.num_envs) == (16, 4096, 8)
def test_only_training_is_warned_about_its_batch_size(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""`resolve()` decides the warning; this pins that `resolve_all` tells it which
entry point is asking. A flag handed to a function and never passed on is the
failure this checks for, so train with the same count is the control."""
import tasks.registry as registry
monkeypatch.setitem(registry._REGISTRY, "fixture", registry.TaskSpec("fixture"))
argv = ["--task", "fixture", "--backend", "native", "--device", "cpu",
"--num_envs", "8"]
cli, play = _parse(argv, {}, monkeypatch, replay=True)
_, train = _parse(argv, {}, monkeypatch)
_, play_res, _ = cli.resolve_all(play)
_, train_res, _ = cli.resolve_all(train, for_training=True)
assert play_res.num_envs == train_res.num_envs == 8
assert not any("batch size" in n for n in play_res.notes), play_res.notes
assert any("batch size" in n for n in train_res.notes), train_res.notes
# ── The repository's own .env ─────────────────────────────────────────────
@pytest.mark.parametrize("raw", ["0", "-4", "2.5"])
def test_warp_capacity_flags_reject_invalid_integers(raw, monkeypatch) -> None:
with pytest.raises(SystemExit) as error:
_parse(["--warp-max-constraints", raw], {}, monkeypatch)
assert error.value.code == 2
def test_warp_capacity_flags_are_rejected_for_native(monkeypatch) -> None:
import tasks.registry as registry
monkeypatch.setitem(registry._REGISTRY, "fixture", registry.TaskSpec("fixture"))
cli, args = _parse([
"--task", "fixture", "--backend", "native", "--device", "cpu",
"--warp-max-constraints", "300", "--warp-max-contacts", "56",
], {}, monkeypatch)
assert (args.warp_max_constraints, args.warp_max_contacts) == (300, 56)
with pytest.raises(SystemExit, match="require Warp"):
cli.resolve_all(args)
def test_repo_dotenv_is_present_and_parses() -> None:
"""The committed example provides optional local defaults without secrets."""
env = REPO / ".env.example"
assert env.is_file(), "the repository root should have a .env.example"
parse_dotenv(env.read_text(encoding="utf-8"))
def test_repo_dotenv_declares_every_cli_backed_key() -> None:
"""Everything the CLI can set should have an entry in `.env`, or that file is
incomplete."""
keys = set(parse_dotenv((REPO / ".env.example").read_text(encoding="utf-8")))
expected = {
"MJRL_TASK",
"MJRL_MODEL",
"MJRL_BACKEND",
"MJRL_DEVICE",
"MJRL_NUM_ENVS",
"MJRL_PLAY_NUM_ENVS",
"MJRL_CPU_THREADS",
"MJRL_TENSORBOARD",
"MJRL_TB_PORT",
}
assert expected <= keys, f"`.env` is missing: {sorted(expected - keys)}"
def test_repo_dotenv_task_is_registered() -> None:
"""The default task in `.env` must really exist, or every entry point errors
out of the box."""
import tasks
task = parse_dotenv((REPO / ".env.example").read_text(encoding="utf-8")).get("MJRL_TASK", "")
if task.strip():
tasks.get(task.strip()) # raises KeyError when not registered