Use pytest-isolated for tests that need a fresh process

Add pytest-isolated to the hatch test environment and use it where a test
needs a clean interpreter:

- Rewrite test_cuda_init_before_nsight as an isolated test that asserts on
  the raised ProfilerException instead of matching subprocess stderr.
- Add unit tests for nsight.activate, deactivate and get_active_tool. The
  active tool is module-global state, so each test runs in its own process
  with the tool loaders mocked.
- Make conftest.py skip its tool setup inside the isolated child process, so
  the tests control import order themselves.

Rename the --tool-init mode ncu-lazy to none, since it means that no tool is
active up front.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Alok Joshi <aljoshi@nvidia.com>

Author: Alok-Joshi

AGENTS.md

@@ -291,7 +291,7 @@ are skipped without them.
 
 ```bash
 pip install -e ".[cu13]"           # or [cu12]; add ,cupti for the CUPTI backend
-pip install pytest torch           # pick the torch build matching your CUDA, see pytorch.org
+pip install pytest pytest-isolated torch           # pick the torch build matching your CUDA, see pytorch.org
 hatch run lint:check               # black --check, isort --check, mypy --strict (whole repo, incl. examples/tests)
 hatch run lint:format              # apply black + isort
 hatch run docs:build               # sphinx-build -W (warnings are errors)

conftest.py

@@ -12,7 +12,7 @@
     "ncu-at-import": ("1", None),
     # Nothing is active up front, so nsight.analyze.kernel activates NCU on the
     # first call to a decorated function.
-    "ncu-lazy": ("0", None),
+    "none": ("0", None),
     # CUPTI is activated here instead; nsight must not claim NCU at import.
     "cupti": ("0", "cupti"),
 }
@@ -26,7 +26,7 @@ def pytest_addoption(parser: pytest.Parser) -> None:
         help=(
             "How the nsight tool is initialized for the suite. 'ncu-at-import' "
             "(the default) lets nsight activate NCU while it is imported. "
-            "'ncu-lazy' leaves no tool active so the lazy NCU load in "
+            "'none' leaves no tool active so the lazy NCU load in "
             "nsight.analyze.kernel is exercised on the first decorated call. "
             "'cupti' activates CUPTI before the suite runs. Only one tool can be "
             "active per process, so this mode fully determines both "
@@ -36,6 +36,14 @@ def pytest_addoption(parser: pytest.Parser) -> None:
 
 
 def pytest_configure(config: pytest.Config) -> None:
+    # pytest-isolated re-runs selected tests in a fresh child pytest process
+    # with the same arguments. That child must start with nsight unimported and
+    # no tool active, since the isolated tests control import order themselves
+    # (e.g. initializing CUDA before importing nsight). The parent's
+    # NSPY_NCU_INIT_AT_IMPORT is inherited by the child through the environment.
+    if os.environ.get("PYTEST_RUNNING_IN_SUBPROCESS") == "1":
+        return
+
     init_at_import, tool_name = _INIT_MODES[config.getoption("--tool-init")]
 
     # Set before nsight is imported: it reads this while importing, which is why

pyproject.toml

@@ -105,6 +105,7 @@ format = [
 dependencies = [
   "pytest",
   "pytest-cov",
+  "pytest-isolated",
 ]
 system-packages = true
 [tool.hatch.envs.test.scripts]

tests/test_cuda_init_before_nsight.py

@@ -5,65 +5,47 @@
 This is used to test the scenario when a user initializes CUDA before importing nsight.
 NCU attach-mode requires CUDA to not be initialized before the injection library is loaded
 so profiling fails with an error like "Cuda is initialized before the tool".
-"""
 
-import subprocess
-import sys
-from pathlib import Path
+The test runs in a fresh subprocess via pytest-isolated, because nsight must not have
+been imported yet. The root conftest.py skips its tool setup in that subprocess.
+"""
 
 import pytest
 import torch
 
 
-def main() -> None:
-
-    torch.cuda.init()  # any torch call that initializes CUDA would do
-    import nsight  # this loads NCU, and the test needs it loaded after CUDA init
-
-    @nsight.analyze.kernel()
-    def run_simple_kernel(n: int) -> None:
-        a = torch.randn(n, n, device="cuda")
-        b = torch.randn(n, n, device="cuda")
-        with nsight.annotate("test"):
-            _ = a @ b
-
-    # under NSPY_NCU_INIT_AT_IMPORT=0 the load is deferred to here instead, still after CUDA init
-    run_simple_kernel(64)
-
-
-def test() -> None:
-    """Run this program as a subprocess; profiling must fail with the expected error."""
-    # Imported here, not at module scope: importing nsight before torch.cuda.init()
-    # in main() would defeat what this test exercises.
-    import nsight
-
-    if nsight.get_active_tool() == nsight.Tool.CUPTI:
+@pytest.mark.isolated
+def test_cuda_init_before_nsight(request: pytest.FixtureRequest) -> None:
+    """Profiling must fail with the expected error when CUDA is initialized first."""
+    if request.config.getoption("--tool-init") == "cupti":
         pytest.skip(
             "NCU-only test: validates injection failure when CUDA is pre-initialized"
         )
 
-    this_file = Path(__file__).resolve()
-    result = subprocess.run(
-        [sys.executable, str(this_file)],
-        capture_output=True,
-        text=True,
-        timeout=120,
-        cwd=this_file.parent.parent,
-    )
-
-    # Process should fail with a ProfilerException raised by begin_profiling()
-    assert result.returncode != 0, "Subprocess unexpectedly succeeded"
-
-    stderr_lower = (result.stderr or "").lower()
-    # Expect the standardized injection error message with the code emitted by ncu injection
-    # When CUDA is already initialized before injection, we expect code 3 (NV_INJ_ERROR_NOT_INITIALIZED)
-    assert (
-        "failed to begin profiling" in stderr_lower
-    ), f"Unexpected stderr: {result.stderr}"
-    assert (
-        "(code=3)" in stderr_lower
-    ), f"Expected injection error code 3 in stderr, got: {result.stderr}"
-
+    torch.cuda.init()  # any torch call that initializes CUDA would do
 
-if __name__ == "__main__":
-    main()
+    # Importing nsight (or, with --tool-init=none, the first decorated call) loads NCU,
+    # and the test needs that to happen after CUDA init.
+    with pytest.raises(Exception) as exc_info:
+        import nsight
+
+        @nsight.analyze.kernel()
+        def run_simple_kernel(n: int) -> None:
+            a = torch.randn(n, n, device="cuda")
+            b = torch.randn(n, n, device="cuda")
+            with nsight.annotate("test"):
+                _ = a @ b
+
+        run_simple_kernel(64)
+
+    from nsight.exceptions import ProfilerException
+
+    assert isinstance(
+        exc_info.value, ProfilerException
+    ), f"Unexpected exception: {exc_info.value!r}"
+    message = str(exc_info.value).lower()
+    # Expect the standardized injection error message with the code emitted by ncu injection.
+    # When CUDA is already initialized before injection, we expect code 3
+    # (NV_INJ_ERROR_NOT_INITIALIZED)
+    assert "failed to begin profiling" in message, f"Unexpected error: {message}"
+    assert "(code=3)" in message, f"Expected injection error code 3, got: {message}"

tests/test_tools_manager.py

@@ -0,0 +1,114 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Unit tests for nsight.activate / nsight.deactivate / nsight.get_active_tool.
+
+The active tool is module-global state, and NCU cannot be unloaded once loaded, so
+every test runs in its own subprocess via pytest-isolated. The root conftest.py
+leaves the subprocess with no tool active. The tool loaders are replaced with
+recorders, so no GPU, ncu or CUPTI is needed.
+"""
+
+import warnings
+from typing import Any
+
+import pytest
+
+
+class Recorder:
+    """Stands in for the tool loaders and records how often each was called."""
+
+    def __init__(self) -> None:
+        self.calls: list[str] = []
+
+
+@pytest.fixture
+def tools(monkeypatch: pytest.MonkeyPatch) -> Any:
+    # Keep `import nsight` from loading NCU itself, which would make NCU active.
+    monkeypatch.setenv("NSPY_NCU_INIT_AT_IMPORT", "0")
+
+    import nsight
+    from nsight.collection import cupti, ncu
+
+    assert nsight.get_active_tool() is None, "child must start with no tool active"
+
+    rec = Recorder()
+    monkeypatch.setattr(ncu, "init_injection", lambda: rec.calls.append("ncu.init"))
+    monkeypatch.setattr(cupti, "init", lambda: rec.calls.append("cupti.init"))
+    monkeypatch.setattr(cupti, "finalize", lambda: rec.calls.append("cupti.finalize"))
+    return nsight, rec
+
+
+@pytest.mark.isolated
+def test_no_tool_active_initially(tools: Any) -> None:
+    nsight, rec = tools
+    assert nsight.get_active_tool() is None
+    assert rec.calls == []
+
+
+@pytest.mark.isolated
+def test_activate_rejects_non_tool(tools: Any) -> None:
+    nsight, rec = tools
+    with pytest.raises(ValueError, match="nsight.Tool"):
+        nsight.activate("ncu")
+    assert nsight.get_active_tool() is None
+    assert rec.calls == []
+
+
+@pytest.mark.isolated
+@pytest.mark.parametrize(
+    "tool_name, load_call", [("NCU", "ncu.init"), ("CUPTI", "cupti.init")]
+)
+def test_activate_loads_tool_once(tools: Any, tool_name: str, load_call: str) -> None:
+    nsight, rec = tools
+    tool = nsight.Tool[tool_name]
+    nsight.activate(tool)
+    assert nsight.get_active_tool() == tool
+    nsight.activate(tool)  # same tool again is a no-op
+    assert nsight.get_active_tool() == tool
+    assert rec.calls == [load_call]
+
+
+@pytest.mark.isolated
+@pytest.mark.parametrize("first, second", [("NCU", "CUPTI"), ("CUPTI", "NCU")])
+def test_activate_different_tool_raises(tools: Any, first: str, second: str) -> None:
+    nsight, rec = tools
+    nsight.activate(nsight.Tool[first])
+    with pytest.raises(RuntimeError, match="already active"):
+        nsight.activate(nsight.Tool[second])
+    assert nsight.get_active_tool() == nsight.Tool[first]
+
+
+@pytest.mark.isolated
+def test_deactivate_without_active_tool_is_noop(tools: Any) -> None:
+    nsight, rec = tools
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        nsight.deactivate()
+    assert nsight.get_active_tool() is None
+    assert rec.calls == []
+
+
+@pytest.mark.isolated
+def test_deactivate_ncu_warns_and_stays_active(tools: Any) -> None:
+    nsight, rec = tools
+    nsight.activate(nsight.Tool.NCU)
+    with pytest.warns(RuntimeWarning, match="cannot be deactivated"):
+        nsight.deactivate()
+    assert nsight.get_active_tool() == nsight.Tool.NCU
+    # NCU stays loaded, so no other tool can take over.
+    with pytest.raises(RuntimeError):
+        nsight.activate(nsight.Tool.CUPTI)
+
+
+@pytest.mark.isolated
+def test_deactivate_cupti_clears_selection(tools: Any) -> None:
+    nsight, rec = tools
+    nsight.activate(nsight.Tool.CUPTI)
+    nsight.deactivate()
+    assert nsight.get_active_tool() is None
+    assert rec.calls == ["cupti.init", "cupti.finalize"]
+    # With CUPTI torn down, another tool can be activated.
+    nsight.activate(nsight.Tool.NCU)
+    assert nsight.get_active_tool() == nsight.Tool.NCU