test_kwarg_launch.py

# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md).
# All rights reserved.
#
# SPDX-License-Identifier: BSD-3-Clause

import argparse
import logging

import pytest
from isaaclab_newton.physics import NewtonCfg, VBDSolverCfg

import isaaclab.app as app_module
import isaaclab.app.app_launcher as app_launcher_module
import isaaclab.app.sim_launcher as sim_launcher
import isaaclab.utils as utils_module
from isaaclab.app import AppLauncher
from isaaclab.app.sim_launcher import Scan, _ensure_livestream_kit_visualizer, _get_kit_runtime_sources

pytestmark = pytest.mark.integration


def test_make_physics_cfg_builds_core_vbd():
    physics_cfg = sim_launcher.make_physics_cfg("newton_vbd")

    assert isinstance(physics_cfg, NewtonCfg)
    assert isinstance(physics_cfg.solver_cfg, VBDSolverCfg)


@pytest.mark.usefixtures("mocker")
def test_livestream_launch_with_kwargs(mocker):
    """Test launching with keyword arguments."""
    # everything defaults to None
    app_launcher = AppLauncher(headless=True, livestream=1)
    app = app_launcher.app
    assert app_launcher._livestream == 1
    assert app_launcher._headless is True

    # close the app on exit
    app.close()


def test_livestream_injects_kit_visualizer_when_missing():
    args = argparse.Namespace(livestream=2, visualizer=None, visualizer_explicit=False)

    _ensure_livestream_kit_visualizer(args)

    assert args.visualizer == ["kit"]


def test_livestream_rejects_disabled_visualizers():
    args = argparse.Namespace(livestream=2, visualizer=None, visualizer_explicit=True)

    with pytest.raises(ValueError, match="Livestreaming requires the Kit visualizer"):
        _ensure_livestream_kit_visualizer(args)


def test_explicit_experience_requires_isaac_sim_runtime():
    """An explicit Kit experience must override a kitless physics configuration."""
    scan = Scan(
        resolved_physics_cfg=None,
        effective_cfg=object(),
        visualizer_intent={"has_any_visualizers": False, "has_kit_visualizer": False},
        has_ovrtx=False,
        has_kit_camera=False,
        has_kit_physics=False,
        has_kitless_physics=True,
        has_ovphysx_physics=False,
        needs_kit=False,
    )
    args = argparse.Namespace(experience="isaaclab.python.kit", visualizer=None)

    assert _get_kit_runtime_sources(scan, args)


_XR_KIT = {"xr": True, "visualizer": ["kit"], "visualizer_explicit": True}


@pytest.mark.parametrize(
    "launcher_args, headless_env, livestream, expected_headless, expected_has_window",
    [
        # XR with no CLI visualizer: headless even though the task config asks for a window.
        ({"xr": True}, 0, 0, True, False),
        # An explicit '--viz kit' is the only way to get a viewport alongside XR.
        (_XR_KIT, 0, 0, False, True),
        ({"xr": True, "visualizer": ["none"], "visualizer_explicit": True}, 0, 0, True, False),
        # ...but an explicit '--viz kit' cannot override HEADLESS=1.
        (_XR_KIT, 1, 0, True, False),
        # Livestreaming forces headless yet still presents a window to the remote client.
        (_XR_KIT, 0, 1, True, True),
        ({}, 0, 1, True, True),
        # Without XR or livestream the task config still decides.
        ({}, 0, 0, False, True),
    ],
)
def test_xr_without_explicit_windowed_visualizer_forces_headless(
    launcher_args: dict,
    headless_env: int,
    livestream: int,
    expected_headless: bool,
    expected_has_window: bool,
    monkeypatch: pytest.MonkeyPatch,
):
    """Test that enabling XR runs headless unless a windowed visualizer is explicitly requested.

    A task config declaring a windowed visualizer must not leave ``--xr`` opening a window nobody
    asked for, and ``HEADLESS=1`` / livestreaming must keep forcing headless even when one was
    explicitly requested. Resolution is exercised directly to avoid launching Isaac Sim; what the
    resolved state then publishes is asserted by
    :func:`test_load_extensions_publishes_has_gui_setting`.

    ``has_window`` is asserted alongside because it is deliberately *not* the negation of
    headless: livestreaming is headless but windowed.
    """
    monkeypatch.setenv("HEADLESS", str(headless_env))
    # XR is read from the environment too, and is routinely exported by people working on this
    # feature -- pin it so the parametrization is what decides.
    monkeypatch.delenv("XR", raising=False)
    launcher = AppLauncher.__new__(AppLauncher)
    launcher._livestream = livestream
    args = {
        "visualizer_intent": {"has_any_visualizers": True, "has_kit_visualizer": True},
        **launcher_args,
    }

    launcher._resolve_visualizer_settings(args)
    launcher._resolve_xr_settings(args)
    launcher._resolve_headless_settings(args, livestream_arg=-1, livestream_env=0)

    assert launcher._headless is expected_headless
    assert launcher.has_window is expected_has_window


def test_launch_simulation_preserves_failure_exit_code(monkeypatch: pytest.MonkeyPatch):
    close_args = {}

    class _FakeApp:
        def close(self, *, exit_code: int = 0) -> None:
            close_args["exit_code"] = exit_code

    class _FakeAppLauncher:
        def __init__(self, _launcher_args):
            self.app = _FakeApp()

    scan = sim_launcher.Scan(
        resolved_physics_cfg=None,
        effective_cfg=object(),
        visualizer_intent={"has_any_visualizers": False, "has_kit_visualizer": False},
        has_ovrtx=False,
        has_kit_camera=False,
        has_kit_physics=True,
        has_kitless_physics=False,
        has_ovphysx_physics=False,
        needs_kit=True,
    )
    monkeypatch.setattr(sim_launcher, "scan", lambda cfg, physics: scan)
    monkeypatch.setattr(sim_launcher, "_ensure_isaac_sim_available", lambda: None)
    monkeypatch.setattr(app_module, "AppLauncher", _FakeAppLauncher)
    monkeypatch.setattr(utils_module, "has_kit", lambda: False)

    with pytest.raises(RuntimeError, match="sentinel"):
        with sim_launcher.launch_simulation(object(), argparse.Namespace()):
            raise RuntimeError("sentinel")

    assert close_args == {"exit_code": 1}


def test_launch_simulation_auto_enables_kit_camera_without_launcher_args(monkeypatch: pytest.MonkeyPatch):
    monkeypatch.delenv("LIVESTREAM", raising=False)
    received_args = {}

    class _FakeApp:
        def close(self) -> None:
            pass

    class _FakeAppLauncher:
        def __init__(self, launcher_args):
            received_args.update(launcher_args)
            self.app = _FakeApp()

    scan = sim_launcher.Scan(
        resolved_physics_cfg=None,
        effective_cfg=object(),
        visualizer_intent={"has_any_visualizers": False, "has_kit_visualizer": False},
        has_ovrtx=False,
        has_kit_camera=True,
        has_kit_physics=False,
        has_kitless_physics=False,
        has_ovphysx_physics=False,
        needs_kit=True,
    )

    def _scan(_cfg, launcher_args):
        assert launcher_args == {}
        return scan

    monkeypatch.setattr(sim_launcher, "scan", _scan)
    monkeypatch.setattr(sim_launcher, "_ensure_isaac_sim_available", lambda: None)
    monkeypatch.setattr(app_module, "AppLauncher", _FakeAppLauncher)
    monkeypatch.setattr(utils_module, "has_kit", lambda: False)

    with sim_launcher.launch_simulation(object()):
        pass

    assert received_args["enable_cameras"] is True


def test_deferred_cuda_device_synchronizes_torch_and_warp(monkeypatch: pytest.MonkeyPatch):
    """The post-Kit device hook must synchronize both CUDA runtimes."""
    devices = []
    monkeypatch.setattr(app_launcher_module, "set_cuda_device", devices.append)
    launcher = AppLauncher.__new__(AppLauncher)
    launcher._deferred_cuda_device_id = 2

    launcher._set_deferred_cuda_device()

    assert devices == [2]


def test_limit_cpu_threads_forwarded_to_simulation_app(monkeypatch: pytest.MonkeyPatch):
    """A SimulationApp thread limit must survive AppLauncher config resolution."""
    monkeypatch.setenv("HEADLESS", "0")
    monkeypatch.setenv("LIVESTREAM", "0")
    monkeypatch.setenv("XR", "0")

    launcher = AppLauncher.__new__(AppLauncher)
    monkeypatch.setattr(launcher, "_resolve_experience_file", lambda _launcher_args: None)

    launcher._config_resolution({"headless": True, "device": "cpu", "limit_cpu_threads": 1})

    assert launcher._sim_app_config["limit_cpu_threads"] == 1


class _DummySettings:
    def __init__(self):
        self.values = {}

    def set_string(self, path: str, value: str) -> None:
        self.values[path] = value

    def set_int(self, path: str, value: int) -> None:
        self.values[path] = value

    def set_bool(self, path: str, value: bool) -> None:
        self.values[path] = value


@pytest.mark.parametrize("deterministic", [True, False])
def test_load_extensions_publishes_deterministic_setting(monkeypatch: pytest.MonkeyPatch, deterministic: bool):
    """Publish ``/isaaclab/render/deterministic`` from ``_load_extensions``."""
    launcher = AppLauncher.__new__(AppLauncher)
    launcher._deterministic_rendering = deterministic
    launcher._python_logging_level = logging.ERROR
    launcher._headless = True
    launcher._livestream = 0
    launcher._enable_cameras = False
    launcher._offscreen_render = False
    launcher._render_viewport = False
    launcher._xr = False
    launcher._video_enabled = False

    settings = _DummySettings()
    monkeypatch.setattr(app_launcher_module, "initialize_carb_settings", lambda: None)
    monkeypatch.setattr(app_launcher_module, "get_settings_manager", lambda: settings)
    monkeypatch.setattr(app_launcher_module, "apply_python_logging_level", lambda _level: None)

    launcher._load_extensions()

    assert settings.values["/isaaclab/render/deterministic"] is deterministic


@pytest.mark.parametrize(
    ("headless", "livestream", "xr", "expected_has_gui", "expected_xr_auto_start"),
    [
        pytest.param(False, 0, False, True, False, id="local-window"),
        pytest.param(True, 0, False, False, False, id="headless"),
        pytest.param(True, 1, False, True, False, id="livestream"),
        pytest.param(True, 0, True, True, True, id="xr"),
        # XR with a window: the operator starts the session, so it must not auto-start.
        pytest.param(False, 0, True, True, False, id="xr-windowed"),
        # ...but a windowless XR run must, however that windowless state was reached.
        pytest.param(True, 1, True, True, True, id="xr-livestream"),
    ],
)
def test_load_extensions_publishes_has_gui_setting(
    monkeypatch: pytest.MonkeyPatch,
    headless: bool,
    livestream: int,
    xr: bool,
    expected_has_gui: bool,
    expected_xr_auto_start: bool,
):
    """Publish the GUI and XR auto-start state consumed by SimulationContext and the teleop stack.

    Asserted at the publication site rather than by recomputing the expression, so that changing
    what is published fails here instead of silently agreeing with a restated formula.
    """
    launcher = AppLauncher.__new__(AppLauncher)
    launcher._deterministic_rendering = False
    launcher._python_logging_level = logging.ERROR
    launcher._headless = headless
    launcher._livestream = livestream
    launcher._enable_cameras = False
    launcher._offscreen_render = False
    launcher._render_viewport = False
    launcher._xr = xr
    launcher._video_enabled = False

    settings = _DummySettings()
    monkeypatch.setattr(app_launcher_module, "initialize_carb_settings", lambda: None)
    monkeypatch.setattr(app_launcher_module, "get_settings_manager", lambda: settings)
    monkeypatch.setattr(app_launcher_module, "apply_python_logging_level", lambda _level: None)

    launcher._load_extensions()

    assert settings.values["/isaaclab/has_gui"] is expected_has_gui
    assert settings.values["/isaaclab/xr/auto_start"] is expected_xr_auto_start


def test_set_visualizer_settings_stores_values(monkeypatch: pytest.MonkeyPatch):
    settings = _DummySettings()
    monkeypatch.setattr(app_launcher_module, "get_settings_manager", lambda: settings)

    launcher = AppLauncher.__new__(AppLauncher)
    launcher._set_visualizer_settings({"visualizer": ["viser", "rerun"], "max_visible_envs": 0})

    assert settings.values == {
        "/isaaclab/visualizer/types": "viser rerun",
        "/isaaclab/visualizer/explicit": False,
        "/isaaclab/visualizer/disable_all": False,
        "/isaaclab/visualizer/max_visible_envs": 0,
    }


def test_set_visualizer_settings_rejects_negative_max_visible_envs(
    monkeypatch: pytest.MonkeyPatch,
):
    def _unexpected_settings_manager():
        raise AssertionError("settings manager should not be queried for invalid values")

    monkeypatch.setattr(app_launcher_module, "get_settings_manager", _unexpected_settings_manager)

    launcher = AppLauncher.__new__(AppLauncher)
    with pytest.raises(ValueError, match="Invalid value for --max_visible_envs: -5"):
        launcher._set_visualizer_settings({"visualizer": ["viser"], "max_visible_envs": -5})


def test_set_visualizer_settings_suppresses_settings_manager_errors(monkeypatch: pytest.MonkeyPatch):
    def _raise_settings_error():
        raise RuntimeError("settings unavailable")

    monkeypatch.setattr(app_launcher_module, "get_settings_manager", _raise_settings_error)

    launcher = AppLauncher.__new__(AppLauncher)
    launcher._set_visualizer_settings({"visualizer": ["viser"], "max_visible_envs": 3})


def test_parse_visualizer_csv_accepts_comma_delimited_values():
    parsed = app_launcher_module.AppLauncher._parse_visualizer_csv("kit,newton,rerun,viser")
    assert parsed == ["kit", "newton_gl", "rerun", "viser"]


def test_parse_visualizer_csv_rejects_spaces_between_entries():
    with pytest.raises(argparse.ArgumentTypeError, match="spaces are not allowed"):
        app_launcher_module.AppLauncher._parse_visualizer_csv("kit, newton")


def test_resolve_visualizer_settings_rejects_none_with_others():
    launcher = AppLauncher.__new__(AppLauncher)
    with pytest.raises(ValueError, match="'none' cannot be combined"):
        launcher._resolve_visualizer_settings(
            {"visualizer": ["none", "kit"], "visualizer_explicit": True},
        )


def test_visualizer_csv_does_not_swallow_hydra_overrides():
    parser = argparse.ArgumentParser(add_help=False)
    app_launcher_module.AppLauncher.add_app_launcher_args(parser)

    args, hydra_args = parser.parse_known_args(
        ["--visualizer", "kit,newton,rerun", "presets=newton_mjwarp", "env.episode_length=10"]
    )

    assert args.visualizer == ["kit", "newton_gl", "rerun"]
    assert hydra_args == ["presets=newton_mjwarp", "env.episode_length=10"]


def _resolve_headless_for_case(monkeypatch: pytest.MonkeyPatch, launcher_args: dict) -> tuple[bool, AppLauncher]:
    monkeypatch.setenv("HEADLESS", "0")
    launcher = AppLauncher.__new__(AppLauncher)
    launcher._livestream = 0
    launcher._resolve_visualizer_settings(launcher_args)
    launcher._resolve_headless_settings(launcher_args, livestream_arg=-1, livestream_env=0)
    return launcher._headless, launcher


def test_matrix_cli_kit_newton_with_custom_kit_cfg_intent_non_headless(monkeypatch: pytest.MonkeyPatch):
    headless, launcher = _resolve_headless_for_case(
        monkeypatch,
        {
            "visualizer": ["kit", "newton"],
            "visualizer_explicit": True,
            "visualizer_intent": {"has_any_visualizers": True, "has_kit_visualizer": True},
        },
    )
    assert headless is False
    assert launcher._cli_visualizer_types == ["kit", "newton_gl"]


def test_matrix_cli_rerun_with_custom_kit_cfg_intent_headless(monkeypatch: pytest.MonkeyPatch):
    headless, launcher = _resolve_headless_for_case(
        monkeypatch,
        {
            "visualizer": ["rerun"],
            "visualizer_explicit": True,
            "visualizer_intent": {"has_any_visualizers": True, "has_kit_visualizer": True},
        },
    )
    assert headless is True
    assert launcher._cli_visualizer_types == ["rerun"]


def test_matrix_no_cli_with_cfg_kit_newton_non_headless(monkeypatch: pytest.MonkeyPatch):
    headless, launcher = _resolve_headless_for_case(
        monkeypatch,
        {
            "visualizer_intent": {"has_any_visualizers": True, "has_kit_visualizer": True},
        },
    )
    assert headless is False
    assert launcher._cli_visualizer_explicit is False


def test_matrix_empty_dict_resolves_headless(monkeypatch: pytest.MonkeyPatch):
    # tools that launch Kit only to reach an extension API pass no visualizer, and must stay headless
    headless, _ = _resolve_headless_for_case(monkeypatch, {})
    assert headless is True


def test_matrix_viz_kit_dict_resolves_windowed(monkeypatch: pytest.MonkeyPatch):
    # a Kit viewport only exists when the launcher is told to create it
    headless, launcher = _resolve_headless_for_case(monkeypatch, {"visualizer": ["kit"]})
    assert headless is False
    assert launcher._cli_visualizer_types == ["kit"]


@pytest.mark.parametrize("visualizer", [None, ["none"]])
def test_matrix_viz_none_disables_all_and_headless(monkeypatch: pytest.MonkeyPatch, visualizer):
    headless, launcher = _resolve_headless_for_case(
        monkeypatch,
        {
            "visualizer": visualizer,
            "visualizer_explicit": True,
            "visualizer_intent": {"has_any_visualizers": True, "has_kit_visualizer": True},
        },
    )
    assert headless is True
    assert launcher._cli_visualizer_disable_all is True
    assert launcher._cli_visualizer_types == []


def test_matrix_headless_flag_deprecated_takes_precedence(monkeypatch: pytest.MonkeyPatch):
    headless, launcher = _resolve_headless_for_case(
        monkeypatch,
        {
            "headless": True,
            "headless_explicit": True,
            "visualizer_intent": {"has_any_visualizers": True, "has_kit_visualizer": True},
        },
    )
    assert headless is True
    assert launcher._cli_visualizer_types == []


def test_matrix_headless_with_viz_names_takes_precedence(monkeypatch: pytest.MonkeyPatch):
    headless, launcher = _resolve_headless_for_case(
        monkeypatch,
        {
            "headless": True,
            "headless_explicit": True,
            "visualizer": ["kit", "newton"],
            "visualizer_explicit": True,
            "visualizer_intent": {"has_any_visualizers": True, "has_kit_visualizer": True},
        },
    )
    assert headless is True
    assert launcher._cli_visualizer_disable_all is False
    assert launcher._cli_visualizer_types == ["kit", "newton_gl"]


def test_no_cli_and_no_cfg_visualizers_defaults_headless(monkeypatch: pytest.MonkeyPatch):
    headless, _ = _resolve_headless_for_case(monkeypatch, {})
    assert headless is True


def test_no_cli_and_non_kit_cfg_visualizers_defaults_headless(monkeypatch: pytest.MonkeyPatch):
    headless, _ = _resolve_headless_for_case(
        monkeypatch,
        {"visualizer_intent": {"has_any_visualizers": True, "has_kit_visualizer": False}},
    )
    assert headless is True


def test_invalid_visualizer_intent_rejected(monkeypatch: pytest.MonkeyPatch):
    monkeypatch.setenv("HEADLESS", "0")
    launcher = AppLauncher.__new__(AppLauncher)
    with pytest.raises(ValueError, match="visualizer_intent"):
        launcher._resolve_visualizer_settings({"visualizer_intent": {"has_any_visualizers": "yes"}})


def _new_launcher_for_experience_check():
    launcher = AppLauncher.__new__(AppLauncher)
    launcher._enable_cameras = False
    launcher._headless = False
    launcher._xr = False
    launcher._deterministic_rendering = False
    launcher.is_isaac_sim_version_5 = lambda: False
    return launcher


def test_rejects_isaacsim_full_streaming_experience_with_livestream(tmp_path, monkeypatch: pytest.MonkeyPatch):
    experience = tmp_path / "isaacsim.exp.full.streaming.kit"
    experience.write_text('[dependencies]\n"isaacsim.exp.full" = {}\n', encoding="utf-8")
    monkeypatch.setenv("EXP_PATH", str(tmp_path))
    launcher = _new_launcher_for_experience_check()
    launcher._livestream = 2

    with pytest.raises(ValueError, match="depends on 'isaacsim.exp.full'"):
        launcher._resolve_experience_file({"experience": str(experience)})


def test_rejects_custom_experience_with_isaacsim_full_dependency_and_livestream(
    tmp_path, monkeypatch: pytest.MonkeyPatch
):
    experience = tmp_path / "merged.kit"
    experience.write_text('[dependencies]\n"isaaclab.python" = {}\n"isaacsim.exp.full" = {}\n', encoding="utf-8")
    monkeypatch.setenv("EXP_PATH", str(tmp_path))
    launcher = _new_launcher_for_experience_check()
    launcher._livestream = 2

    with pytest.raises(ValueError, match="depends on 'isaacsim.exp.full'"):
        launcher._resolve_experience_file({"experience": str(experience)})


def test_allows_isaacsim_full_streaming_experience_when_livestream_disabled(tmp_path, monkeypatch: pytest.MonkeyPatch):
    experience = tmp_path / "isaacsim.exp.full.streaming.kit"
    experience.write_text('[dependencies]\n"isaacsim.exp.full" = {}\n', encoding="utf-8")
    monkeypatch.setenv("EXP_PATH", str(tmp_path))
    launcher = _new_launcher_for_experience_check()
    launcher._livestream = 0

    launcher._resolve_experience_file({"experience": str(experience)})

    assert launcher._sim_experience_file == str(experience)


def test_constructor_reports_missing_isaac_sim(monkeypatch: pytest.MonkeyPatch):
    monkeypatch.setattr(app_launcher_module, "SimulationApp", None)

    with pytest.raises(ImportError, match="requires the full Isaac Sim runtime"):
        AppLauncher()


def test_is_available_reflects_simulation_app_presence(monkeypatch: pytest.MonkeyPatch):
    monkeypatch.setattr(app_launcher_module, "SimulationApp", None)
    assert AppLauncher.is_available() is False

    monkeypatch.setattr(app_launcher_module, "SimulationApp", object())
    assert AppLauncher.is_available() is True


def test_has_gui_reads_published_setting():
    from isaaclab.app.settings_manager import get_settings_manager

    settings = get_settings_manager()
    original = settings.get("/isaaclab/has_gui")
    try:
        settings.set_bool("/isaaclab/has_gui", True)
        assert AppLauncher.has_gui() is True

        settings.set_bool("/isaaclab/has_gui", False)
        assert AppLauncher.has_gui() is False
    finally:
        settings.set_bool("/isaaclab/has_gui", bool(original))


def test_visualizer_argparse_set_defaults_is_not_explicit():
    parser = argparse.ArgumentParser(add_help=False)
    app_launcher_module.AppLauncher.add_app_launcher_args(parser)
    parser.set_defaults(visualizer=["kit"])

    args, _ = parser.parse_known_args([])
    launcher = AppLauncher.__new__(AppLauncher)
    launcher._resolve_visualizer_settings(vars(args))

    assert launcher._cli_visualizer_explicit is False
    assert launcher._cfg_has_any_visualizers is True
    assert launcher._cfg_has_kit_visualizer is True


def test_visualizer_direct_kwargs_is_explicit():
    launcher = AppLauncher.__new__(AppLauncher)
    launcher._resolve_visualizer_settings({"visualizer": ["kit"]})

    assert launcher._cli_visualizer_explicit is True


def test_matrix_headless_env_with_kit_visualizer(monkeypatch: pytest.MonkeyPatch):
    monkeypatch.setenv("HEADLESS", "1")
    launcher = AppLauncher.__new__(AppLauncher)
    launcher._livestream = 0
    launcher._resolve_visualizer_settings({"visualizer": ["kit"], "visualizer_explicit": True})
    launcher._resolve_headless_settings(
        {"visualizer": ["kit"], "visualizer_explicit": True}, livestream_arg=-1, livestream_env=0
    )

    assert launcher._headless is True
    # Kit visualizer shouldn't be disabled just because of HEADLESS=1
    assert launcher._cli_visualizer_disable_all is False