vcrtrace: improve API doc

CMK-27519

Change-Id: I4b15ed856a1d72b24474c1c1ecda711ec18bab16

Author: mo-ki

packages/cmk-plugin-apis/cmk/server_side_programs/v1_unstable/_vcrtrace.py

@@ -20,6 +20,8 @@ def _check_path(filename: str) -> None:
     allowed_path = (Path.home() / "tmp" / "debug").resolve()
     if not p.is_relative_to(allowed_path):
         raise ValueError(f"Traces can only be stored in {allowed_path}")
+    if not (p_dir := p.parent).is_dir():
+        raise NotADirectoryError(f"Directory {p_dir} does not exist")
 
 
 def vcrtrace(
@@ -40,6 +42,7 @@ def vcrtrace(
     all requests the program sends and their corresponding answers will be recorded in said file.
     If the file already exists, no requests are sent to the server, but the responses will be
     replayed from the tracefile.
+    TRACEFILE must be a file path within the directory `~/tmp/debug`; `~/tmp/debug` must exist.
 
     The destination attribute will be set to `True` if the option was specified, the
     provided default otherwise.

packages/cmk-plugin-apis/tests/cmk/server_side_programs/v1/test_vcrtrace.py

@@ -19,21 +19,40 @@ def _mocked_home(tmp_path: Path) -> Iterator[Path]:
         yield tmp_path
 
 
-def test_check_path_relative(mocked_home: Path) -> None:
+def test_check_path_relative_ok(mocked_home: Path) -> None:
+    (mocked_home / "tmp/debug").mkdir(parents=True, exist_ok=True)
     with chdir(mocked_home):
-        with pytest.raises(ValueError):
-            _check_path("foo")
         _check_path("tmp/debug/foo")
 
-    some_dir = mocked_home / "foobar"
-    some_dir.mkdir()
-    with chdir(some_dir):
-        with pytest.raises(ValueError):
-            _check_path("tmp/debug/foo")
-        _check_path("../tmp/debug/foo")
+
+def test_check_path_relative_missing(mocked_home: Path) -> None:
+    with chdir(mocked_home), pytest.raises(NotADirectoryError):
+        _check_path("tmp/debug/foo")
+
+
+def test_check_path_relative_too_far_down(mocked_home: Path) -> None:
+    (mocked_home / "tmp/debug").mkdir(parents=True, exist_ok=True)
+    with chdir(mocked_home / "tmp"), pytest.raises(ValueError):
+        _check_path("tmp/debug/foo")
+
+
+def test_check_path_relative_too_far_up(mocked_home: Path) -> None:
+    (mocked_home / "tmp/debug").mkdir(parents=True, exist_ok=True)
+    with chdir(mocked_home / ".."), pytest.raises(ValueError):
+        _check_path("tmp/debug/foo")
+
+
+def test_check_path_absolute_ok(mocked_home: Path) -> None:
+    (mocked_home / "tmp/debug").mkdir(parents=True, exist_ok=True)
+    _check_path(str(mocked_home / "tmp/debug/foo"))
+
+
+def test_check_path_absolute_missing(mocked_home: Path) -> None:
+    with pytest.raises(NotADirectoryError):
+        _check_path(str(mocked_home / "tmp/debug/foo"))
 
 
-def test_check_path_absolute(mocked_home: Path) -> None:
-    with pytest.raises(ValueError):
-        _check_path(str(mocked_home / "foo"))
-    _check_path(str(mocked_home / "tmp" / "debug" / "foo"))
+def test_check_path_absolute_invalid(mocked_home: Path) -> None:
+    (mocked_home / "tmp/debug").mkdir(parents=True, exist_ok=True)
+    with chdir(mocked_home / "tmp"), pytest.raises(ValueError):
+        _check_path(str(mocked_home / "tmp/degug/foo"))