Files
SkillFactory/tests/test_part_contracts.py
T
2026-10-10 16:34:40 +08:00

389 lines
17 KiB
Python

"""Body-part independent v2 contracts: static capability matching, not simulation claims."""
import copy
import hashlib
import importlib.util
import json
import shutil
from pathlib import Path
import pytest
import tomllib
from jsonschema import Draft202012Validator
ROOT = Path(__file__).resolve().parents[1]
def module(name, relative):
spec = importlib.util.spec_from_file_location(name, ROOT / relative)
result = importlib.util.module_from_spec(spec)
spec.loader.exec_module(result)
return result
validator = module("part_validator", "scripts/validate_descriptions.py")
examples = module("part_examples", "scripts/examples/generate_part_descriptions.py")
migration = module("part_migration", "scripts/migrate_leg_description.py")
def save(path, data):
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(json.dumps(data, allow_nan=False), encoding="utf-8")
return path
def replace(data, dotted, value):
keys = dotted.split(".")
current = data
for key in keys[:-1]:
current = current[int(key)] if isinstance(current, list) else current[key]
current[int(keys[-1]) if isinstance(current, list) else keys[-1]] = value
@pytest.fixture
def repo(tmp_path):
root = tmp_path / "repo"
shutil.copytree(ROOT / "configs", root / "configs")
return root
@pytest.fixture
def software(repo):
return validator.read_json(repo / "configs/software/part_position_control.json")
@pytest.mark.parametrize("name", ["part_spec.v2.schema.json", "software_spec.v2.schema.json"])
def test_v2_schemas(name):
Draft202012Validator.check_schema(validator.read_json(ROOT / "docs/schemas" / name))
@pytest.mark.parametrize("path", sorted((ROOT / "configs/parts").glob("*.json")), ids=lambda path: path.stem)
def test_different_body_parts_use_same_schema(path):
data = validator.validate_hardware(path)
assert data["schema_version"] == 2 and data["kind"] == "robot_part"
assert data["description_role"] == ("asset_reference" if path.stem == "go2_fl" else "design_template")
@pytest.mark.parametrize("name", ["part_position_control", "wheel_velocity_control", "part_rgb_perception"])
def test_software_profiles(name):
data = validator.validate_software(ROOT / f"configs/software/{name}.json")
assert data["runtime"]["implementation"] == "unimplemented"
assert data["artifact"]["trained_skill"] is False
def test_examples_are_deterministic_and_explicitly_synthetic():
for relative, expected in examples.build_examples().items():
assert validator.read_json(ROOT / relative) == expected
if relative.startswith("configs/parts/"):
assert expected["source"]["format"] == "design"
assert expected["extensions"]["skillfactory.example"]["not_manufacturer_data"] is True
def test_variable_dof_actuation_and_effector_counts():
hand = validator.validate_hardware(ROOT / "configs/parts/example_hand.json")
entities = validator._entities(hand)
assert [len(entities[name]) for name in ("joint", "actuator", "end_effector")] == [4, 2, 2]
assert hand["topology"]["joints"][1]["coupling"]["joint_id"] == "joint_0"
pod = validator.validate_hardware(ROOT / "configs/parts/example_sensor.json")
entities = validator._entities(pod)
assert all(not entities[name] for name in ("joint", "actuator", "end_effector"))
assert len(entities["sensor"]) == 2
torso = validator.validate_hardware(ROOT / "configs/parts/example_torso.json")
assert torso["end_effectors"] == []
@pytest.mark.parametrize(
("field", "value"),
[
("schema_version", 2.0),
("typo", True),
("source.path", "fake_factory_asset.urdf"),
("topology.root_body", "missing"),
("topology.joints.0.parent", "link_5"),
("topology.joints.0.position_unit", "m"),
("topology.joints.0.axis", [0, 0, 0]),
("topology.joints.0.axis", [1e200, 0, 0]),
("topology.joints.0.origin.quat_xyzw", [0, 0, 0, 0]),
("topology.joints.0.limits.position", [1, -1]),
("topology.joints.0.limits", None),
("topology.joints.0.actuation", "passive"),
("frames.0.body", "missing"),
("frames.0.quat_xyzw", [0, 0, 0, 2]),
("attachment.frame_id", "missing"),
("actuators.0.neutral_position", 2),
("actuators.0.commands.position_pd.unit", "m"),
("actuators.0.commands.position_pd.gains", None),
("end_effectors.0.frame_id", "missing"),
("end_effectors.0.contact", {"source_collision_index": 0.0, "gap_method": "sphere"}),
("sensors.0.target.ids", ["missing"]),
("timing.control_dt_s", 0.003),
("safety.command_timeout_s", 0.005),
("extensions", {"unnamespaced": {}}),
],
)
def test_invalid_part_semantics(tmp_path, field, value):
data = validator.read_json(ROOT / "configs/parts/example_arm.json")
replace(data, field, value)
with pytest.raises(ValueError):
validator.validate_hardware(save(tmp_path / "part.json", data))
def test_actuator_coverage_and_duplicate_names(tmp_path):
data = validator.read_json(ROOT / "configs/parts/example_arm.json")
data["actuators"].pop()
with pytest.raises(ValueError, match="one independent actuator"):
validator.validate_hardware(save(tmp_path / "part.json", data))
data = validator.read_json(ROOT / "configs/parts/example_arm.json")
data["actuators"].append(copy.deepcopy(data["actuators"][0]))
with pytest.raises(ValueError, match="Duplicate"):
validator.validate_hardware(save(tmp_path / "part.json", data))
data = validator.read_json(ROOT / "configs/parts/example_arm.json")
data["topology"]["joints"][1]["source_name"] = "joint_0"
with pytest.raises(ValueError, match="source joint names"):
validator.validate_hardware(save(tmp_path / "part.json", data))
def test_coupling_cycles_rejected(tmp_path):
data = validator.read_json(ROOT / "configs/parts/example_hand.json")
data["topology"]["joints"][1]["coupling"]["joint_id"] = "joint_3"
data["topology"]["joints"][3]["coupling"]["joint_id"] = "joint_1"
with pytest.raises(ValueError, match="Cyclic joint coupling"):
validator.validate_hardware(save(tmp_path / "part.json", data))
def test_explicit_closed_chain_frames_not_a_cyclic_tree(tmp_path):
data = validator.read_json(ROOT / "configs/parts/example_arm.json")
data["topology"]["structure"] = "closed_chain"
data["topology"]["constraints"] = [
{"id": "loop", "type": "loop_closure", "parent_frame": "root", "child_frame": "tool_frame"}
]
assert validator.validate_hardware(save(tmp_path / "part.json", data))["topology"]["structure"] == "closed_chain"
data["topology"]["constraints"][0]["child_frame"] = "missing"
with pytest.raises(ValueError, match="Loop constraint"):
validator.validate_hardware(save(tmp_path / "part.json", data))
@pytest.mark.parametrize(
("field", "value"),
[
("requirements.capacities.Jmax", 3),
("requirements.capacities.Amax", 1),
("requirements.capacities.Emax", 1),
("requirements.capacities.Smax", 1),
("requirements.capacities.Amax", 32.0),
("requirements.supports_coupling", False),
("requirements.joint_types", ["revolute"]),
("requirements.required_control_modes", ["effort"]),
("requirements.required_sensor_kinds", ["wrench"]),
("requirements.required_effector_roles", ["tool"]),
("interface.ports.3.shape", ["B", "Jmax", 1]),
("interface.ports.3.mask", "joint_mask"),
("interface.ports.3.command.clip", [-2, 2]),
("interface.ports.3.features.0.unit", "rad"),
("interface.ports.1.features.0.unit", "m"),
("interface.ports.1.features.0.unit", "degree"),
("interface.ports.1.features.1.name", "position"),
("interface.ports.1.shape", ["B", "Jmax", 3]),
("runtime.implementation", "available"),
("runtime.adapter_id", "imaginary_adapter"),
("artifact.trained_skill", True),
],
)
def test_software_binding_and_port_rejections(tmp_path, repo, software, field, value):
replace(software, field, value)
with pytest.raises(ValueError):
validator.validate_software(save(tmp_path / "software.json", software), repo)
def test_overlapping_command_ports_rejected(tmp_path, repo, software):
command = copy.deepcopy(software["interface"]["ports"][3])
command["name"] = "conflicting_command"
software["interface"]["ports"].append(command)
with pytest.raises(ValueError, match="Conflicting command ports"):
validator.validate_software(save(tmp_path / "software.json", software), repo)
def test_per_part_timing_and_explicit_common_control_contract(tmp_path, repo, software):
path = repo / "configs/parts/example_arm.json"
data = validator.read_json(path)
data["timing"]["control_dt_s"] = 0.02
save(path, data)
target = save(tmp_path / "software.json", software)
assert validator.validate_software(target, repo)["runtime"]["timing"]["policy"] == "per_part"
software["runtime"]["timing"]["policy"] = "common_control_dt"
with pytest.raises(ValueError, match="common control dt"):
validator.validate_software(save(target, software), repo)
data["timing"].update(control_dt_s=0.01, physics_dt_s=0.005)
save(path, data)
software["runtime"]["timing"]["control_dt_s"] = 0.01
assert validator.validate_software(save(target, software), repo)
def test_joint_sensor_coverage_is_per_entity_not_just_kind(tmp_path, repo, software):
path = repo / "configs/parts/example_hand.json"
data = validator.read_json(path)
data["sensors"][0]["target"]["ids"] = ["joint_0"]
save(path, data)
with pytest.raises(ValueError, match="sensor coverage"):
validator.validate_software(save(tmp_path / "software.json", software), repo)
def test_camera_requires_rgb_semantics_not_just_camera_kind(tmp_path, repo):
path = repo / "configs/parts/example_sensor.json"
data = validator.read_json(path)
data["sensors"][0]["outputs"] = ["image.depth_m"]
save(path, data)
with pytest.raises(ValueError, match="sensor output semantics"):
validator.validate_software(ROOT / "configs/software/part_rgb_perception.json", repo)
def test_normal_force_cannot_satisfy_wrench_observation(tmp_path, software):
software["hardware_bindings"] = software["hardware_bindings"][:1]
force = copy.deepcopy(software["interface"]["ports"][-1])
force.update(name="force", kind="state", required=True, frame="entity")
force["features"] = [examples.feature(axis, "contact.normal_force." + axis, "N") for axis in ("x", "y", "z")]
software["interface"]["ports"].append(force)
path = save(tmp_path / "software.json", software)
assert validator.validate_software(path)
force["features"][0]["quantity"] = "contact.wrench.fx"
with pytest.raises(ValueError, match="sensor coverage"):
validator.validate_software(save(path, software))
def test_version_boundaries_and_require_runtime(tmp_path, repo, software):
software["hardware_bindings"][0]["spec_path"] = "configs/legs/go2_fl.json"
with pytest.raises(ValueError, match="Only schema_version=2"):
validator.validate_software(save(tmp_path / "software.json", software), repo)
with pytest.raises(ValueError, match="adapter is unimplemented"):
validator.validate_software(ROOT / "configs/software/part_position_control.json", require_runtime=True)
def test_selector_preserves_hardware_order_not_requested_id_order():
data = validator.validate_hardware(ROOT / "configs/parts/example_arm.json")
selector = {"entity": "actuator", "selector": {"type": "ids", "values": ["drive_joint_2", "drive_joint_0"]}}
records = validator._select(selector, validator._entities(data))
assert [item["id"] for item in records] == ["drive_joint_0", "drive_joint_2"]
def test_migration_preserves_actuator_order_fixed_branches_and_mount(tmp_path):
controls = [{"name": name, "q_default": 0.1, "action_scale": 0.25, "kp": 25, "kd": 0.5} for name in ("knee", "hip")]
spec = {
"schema_version": 1,
"part_id": "test_leg",
"source_root": str(tmp_path / "source"),
"urdf": "robot.urdf",
"package_name": "test",
"license_file": "LICENSE",
"license_id": "test",
"mount_joint": "hip",
"auxiliary_root_joints": [],
"joints": controls,
"foot_body": "toe",
"foot_collision_index": 0,
"physics_dt": 0.002,
"decimation": 5,
"soft_limit_factor": 0.9,
}
tree = [
{
"name": name,
"type": kind,
"parent": parent,
"child": child,
"axis": [0, 1, 0],
"xyz": [0, 0, 0],
"rpy": [0, 0, 0],
}
for name, kind, parent, child in (
("hip", "revolute", "anchor_base", "thigh"),
("knee", "revolute", "thigh", "calf"),
("toe_joint", "fixed", "calf", "toe"),
)
]
bundle = {
"schema_version": 2,
"kind": "single_leg",
"spec": spec,
"tree": tree,
"anchor_body": "anchor_base",
"joint_order": ["knee", "hip"],
"links": {"thigh": None, "calf": None, "toe": None},
"joints": [
{"name": item["name"], "limits": {"lower": -1, "upper": 1, "velocity": 10, "effort": 10}}
for item in controls
],
"source": {"commit": None, "sha256": "0" * 64},
"derived_urdf_sha256": "1" * 64,
"mount": {"source_parent": "trunk", "source_parent_T_anchor": {"xyz": [0.1, 0.2, 0.3], "rpy": [0, 0, 0]}},
"foot": {"body": "toe", "type": "sphere"},
"length_scale_m": 0.5,
"known_mass_scale_kg": 0.2,
}
result = migration.part_from_leg_bundle(bundle)
validator.validate_hardware(save(tmp_path / "part.json", result))
assert [item["joint_id"] for item in result["actuators"]] == ["knee", "hip"]
assert [item["id"] for item in result["topology"]["joints"]] == ["hip", "knee", "toe_joint"]
assert result["attachment"]["source_parent_transform"]["xyz"] == [0.1, 0.2, 0.3]
assert result["source"]["sha256"] == "0" * 64
@pytest.mark.parametrize("text", ['{"a": 1, "a": 2}', '{"a": NaN}', '{"a": Infinity}', '{"a": 1e999}'])
def test_invalid_json_values(tmp_path, text):
path = tmp_path / "invalid.json"
path.write_text(text)
with pytest.raises(ValueError):
validator.read_json(path)
def test_checkpoint_hash_without_loading_weights(tmp_path, software, repo):
weights = repo / "sampling_policy.pt"
payload = b"Static validation does not deserialize this fixture."
weights.write_bytes(payload)
software["artifact"]["format"] = "torch_save_state_dict"
software["artifact"]["checkpoint"] = {"path": weights.name, "sha256": hashlib.sha256(payload).hexdigest()}
path = save(tmp_path / "software.json", software)
assert validator.validate_software(path, repo)["artifact"]["trained_skill"] is False
weights.write_bytes(b"tampered")
with pytest.raises(ValueError, match="SHA256"):
validator.validate_software(path, repo)
@pytest.mark.parametrize("invalid", ["id", "duplicate", "missing", "escape"])
def test_invalid_cross_file_bindings(tmp_path, software, repo, invalid):
if invalid == "id":
software["hardware_bindings"][0]["part_id"] = "wrong"
elif invalid == "duplicate":
software["hardware_bindings"][1]["part_id"] = "go2_fl"
elif invalid == "missing":
(repo / "configs/parts/go2_fl.json").unlink()
else:
path = repo / "configs/parts/go2_fl.json"
path.unlink()
path.symlink_to(ROOT / "configs/parts/go2_fl.json")
with pytest.raises((ValueError, OSError)):
validator.validate_software(save(tmp_path / "software.json", software), repo)
def test_cli_success_and_failure(tmp_path, capsys):
validator.main(["--software", str(ROOT / "configs/software/part_position_control.json")])
assert "NOT verified" in capsys.readouterr().out
with pytest.raises(SystemExit) as error:
validator.main(["--hardware", str(tmp_path / "missing.json")])
assert error.value.code == 1
def test_release_has_only_latest_description_specs():
assert {path.name for path in (ROOT / "docs/schemas").glob("*.json")} == {
"part_spec.v2.schema.json",
"software_spec.v2.schema.json",
}
assert not (ROOT / "docs/legacy_single_leg_spec.md").exists()
assert not (ROOT / "configs/software/leg_skill.json").exists()
assert validator.read_json(ROOT / "configs/legs/go2_fl.json")["schema_version"] == 1 # runtime input retained
version = tomllib.loads((ROOT / "source/SkillFactory/config/extension.toml").read_text())["package"]["version"]
assert version == "0.0.2"
assert (ROOT / "README.md").read_text().startswith(f"# SkillFactory v{version}\n")
for path in (ROOT / "configs/software").glob("*.json"):
data = validator.read_json(path)
assert data["schema_version"] == 2 and data["software_version"] == version