diff --git a/devcapsule-src/devcapsule/commands/presentations.py b/devcapsule-src/devcapsule/commands/presentations.py index 461ab391..522e005e 100644 --- a/devcapsule-src/devcapsule/commands/presentations.py +++ b/devcapsule-src/devcapsule/commands/presentations.py @@ -63,7 +63,7 @@ def run(cls, arguments: argparse.Namespace, context: object | None) -> int: token_path = arguments.token_file or Path(os.environ.get("DEVCAPSULE_CONSOLE_TOKEN_FILE") or "/run/devcapsule-console-token") try: token = token_path.read_text(encoding="utf-8").strip() - except OSError: + except (OSError, UnicodeError): token = "" try: if not (folder / "presentation.json").is_file(): diff --git a/devcapsule-src/devcapsule/presentation_authoring.py b/devcapsule-src/devcapsule/presentation_authoring.py index 2620bfe6..9258448d 100644 --- a/devcapsule-src/devcapsule/presentation_authoring.py +++ b/devcapsule-src/devcapsule/presentation_authoring.py @@ -33,8 +33,15 @@ def presentation_link(folder: Path, *, project: Path, console_url: str, token: s part in ("..", "node_modules") or part.startswith(".") for part in relative.parts ): raise ValueError("presentation must be in a visible subdirectory of the console project") + if not console_url or any(ch.isspace() for ch in console_url): + raise ValueError("supply the capsule's HTTP(S) console URL") origin = urlsplit(console_url) - if origin.scheme not in ("http", "https") or not origin.netloc or origin.username or origin.password: + try: + _ = origin.port + except ValueError as error: + raise ValueError("supply the capsule's HTTP(S) console URL") from error + if (origin.scheme not in ("http", "https") or not origin.hostname + or origin.username is not None or origin.password is not None): raise ValueError("supply the capsule's HTTP(S) console URL") path = "/presentations/" + quote(relative.as_posix(), safe="/") return urlunsplit((origin.scheme, origin.netloc, path, urlencode({"token": token}) if token else "", "")) diff --git a/devcapsule-src/devcapsule/presentation_tools/README.md b/devcapsule-src/devcapsule/presentation_tools/README.md index 1312b689..44868692 100644 --- a/devcapsule-src/devcapsule/presentation_tools/README.md +++ b/devcapsule-src/devcapsule/presentation_tools/README.md @@ -84,8 +84,10 @@ Print the engineer's link with the installed CLI: devcapsule presentations hand-off evidence/login-success/run-001 --project "$PROJECT_PATH" ``` -It uses `$DEVCAPSULE_CONSOLE_URL` and the mounted console token; `--console-url` -and `--token-file` supply explicit values. Keep tokened links in chat only, never +Run this from the console project root: a relative evidence folder resolves +from the current working directory, and `--project` supplies the console root +used to form the relative link. It uses `$DEVCAPSULE_CONSOLE_URL` and the +mounted console token; `--console-url` and `--token-file` supply explicit values. Keep tokened links in chat only, never in a source file, log or committed record. If no token can be read, the link requires a browser session that already opened the console. If there is no console URL, report that missing environment input rather than inventing a URL. diff --git a/devcapsule-src/devcapsule/presentation_tools/producer.py b/devcapsule-src/devcapsule/presentation_tools/producer.py index f4f2ea38..16718f0a 100644 --- a/devcapsule-src/devcapsule/presentation_tools/producer.py +++ b/devcapsule-src/devcapsule/presentation_tools/producer.py @@ -299,6 +299,19 @@ def plan_presentation(scenario: Mapping[str, Any], script: Script) -> Presentati if not isinstance(value, str) or not value.strip(): raise PresentationError(f"the scenario has no {key}") texts[key] = value.strip() + if not isinstance(script.goal, str) or not script.goal.strip(): + raise PresentationError("the script has no goal") + if not script.steps: + raise PresentationError("the script has no steps") + for index, step in enumerate(script.steps, start=1): + for field_name, field_value in (("title", step.title), ("action", step.action), ("expected", step.expected)): + if not isinstance(field_value, str) or not field_value.strip(): + raise PresentationError(f"script step {index} has no {field_name}") + if any(not isinstance(item, str) or not item.strip() for item in script.illustrates): + raise PresentationError("script illustrations must be non-empty texts") + if any(not isinstance(name, str) or not name.strip() or not isinstance(detail, str) or not detail.strip() + for name, detail in script.stack): + raise PresentationError("script stack entries must have non-empty name and detail") actions = scenario.get("actions") if not isinstance(actions, list) or not actions: raise PresentationError("the scenario has no actions") diff --git a/devcapsule-src/devcapsule/presentation_tools/recording.py b/devcapsule-src/devcapsule/presentation_tools/recording.py index 4db0dceb..4b418c88 100644 --- a/devcapsule-src/devcapsule/presentation_tools/recording.py +++ b/devcapsule-src/devcapsule/presentation_tools/recording.py @@ -35,7 +35,7 @@ def __init__( "actions": [{"reason": f"{n}. {step.action}"} for n, step in enumerate(script.steps, 1)]} plan_presentation(scenario, script) - if not ffmpeg or not all(isinstance(part, str) and part for part in ffmpeg): + if isinstance(ffmpeg, (str, bytes)) or not ffmpeg or not all(isinstance(part, str) and part for part in ffmpeg): raise PresentationError("supply the ffmpeg command from the browser-automation environment") evidence.mkdir(parents=True, exist_ok=False) self.evidence = evidence @@ -124,18 +124,20 @@ def finish(self) -> Path: raise PresentationError("no complete visual evidence; inspect scenario-result.json and action-log.json") complete = self.last_step == len(self.script.steps) and not self.failure suffix = "" if complete else " (FAILED)" if self.failure else " (INCOMPLETE)" - scenario = dict(self.scenario, title=self.scenario["title"] + suffix, actions=self.actions) + scenario = dict(self.scenario, title=self.scenario["title"].strip() + suffix, actions=self.actions) reached = Script(self.script.goal, self.script.stack, self.script.illustrates, self.script.steps[:self.last_step]) plan = plan_presentation(scenario, reached) document = plan.timed(self.frames_after_actions, self.frame_count, 12, video="scenario-video.webm", poster="poster.png", screenshots=self.screenshots) + video = self.evidence / "scenario-video.webm" with self.frames.open("rb") as frames, (self.evidence / "ffmpeg.log").open("wb") as log: subprocess.run( [*self.ffmpeg, "-y", "-f", "image2pipe", "-vcodec", "mjpeg", "-r", "12", - "-i", "pipe:0", "-c:v", "libvpx", "-b:v", "3M", "-crf", "10", - str(self.evidence / "scenario-video.webm")], + "-i", "pipe:0", "-c:v", "libvpx", "-b:v", "3M", "-crf", "10", str(video)], stdin=frames, stdout=log, stderr=log, check=True, timeout=120, ) + if not video.is_file() or video.stat().st_size == 0: + raise PresentationError("video encoding produced no scenario-video.webm; inspect ffmpeg.log") (self.evidence / "poster.png").write_bytes((self.evidence / self.screenshots[0]).read_bytes()) return write_presentation(self.evidence, document) diff --git a/devcapsule-src/tests/integration/test_pex_runtime.py b/devcapsule-src/tests/integration/test_pex_runtime.py index 78f4b45e..10e64d5d 100644 --- a/devcapsule-src/tests/integration/test_pex_runtime.py +++ b/devcapsule-src/tests/integration/test_pex_runtime.py @@ -288,3 +288,44 @@ def invoke(*arguments: str) -> subprocess.CompletedProcess[str]: saved = invoke("run", "--ide", "codium", "--force", "--save", "--print-command") assert saved.returncode == 2 and "cannot be combined with --save" in saved.stderr assert {path: path.read_bytes() for path in before} == before, "no refusal writes anything" + + +def test_built_pex_exports_standalone_presentation_tools( + built_pex: Path, tmp_path: Path, environment: dict[str, str], +) -> None: + """The built executable prints the guide and exports a standalone ``presentation_tools`` kit.""" + guide = subprocess.run( + [str(built_pex), "presentations", "guide"], + cwd=tmp_path, env=environment, text=True, capture_output=True, check=False, + ) + assert guide.returncode == 0, guide.stderr + assert "# Run an E2E scenario with recording and presentation" in guide.stdout + + kit = tmp_path / "exported-kit" + exported = subprocess.run( + [str(built_pex), "presentations", "export", str(kit)], + cwd=tmp_path, env=environment, text=True, capture_output=True, check=False, + ) + assert exported.returncode == 0, exported.stderr + package = kit / "presentation_tools" + assert (package / "README.md").read_text(encoding="utf-8") + "\n" == guide.stdout + assert {path.name for path in package.iterdir()} == { + "__init__.py", "README.md", "example.py", "producer.py", "recording.py", + } + + isolated = subprocess.run( + [ + sys.executable, "-I", "-c", + ( + "import sys; sys.path.insert(0, sys.argv[1]); " + "from presentation_tools.producer import Script, ScriptStep; " + "from presentation_tools.recording import Recording; " + "import presentation_tools.example; " + "assert 'devcapsule' not in sys.modules and 'tests' not in sys.modules" + ), + str(kit), + ], + cwd=tmp_path, env={"PATH": os.defpath, "PYTHONDONTWRITEBYTECODE": "1"}, + text=True, capture_output=True, check=False, + ) + assert isolated.returncode == 0, isolated.stderr diff --git a/devcapsule-src/tests/integration/test_presentations_cli.py b/devcapsule-src/tests/integration/test_presentations_cli.py new file mode 100644 index 00000000..db382efe --- /dev/null +++ b/devcapsule-src/tests/integration/test_presentations_cli.py @@ -0,0 +1,107 @@ +"""Integration tests of ``devcapsule presentations``: real CLI subprocesses with explicit environments.""" +from __future__ import annotations + +import os +from pathlib import Path +import subprocess +import sys + +import pytest + +pytestmark = pytest.mark.integration + + +def _run_presentations( + tmp_path: Path, *arguments: str, extra_env: dict[str, str] | None = None, +) -> subprocess.CompletedProcess[str]: + environment = { + "PATH": os.defpath, + "PYTHONDONTWRITEBYTECODE": "1", + "HOME": str(tmp_path / "home"), + "DEVCAPSULE_CONFIG_HOME": str(tmp_path / "config"), + } + if extra_env: + environment.update(extra_env) + return subprocess.run( + [sys.executable, "-m", "devcapsule", "presentations", *arguments], + cwd=tmp_path, env=environment, capture_output=True, text=True, timeout=120, check=False, + ) + + +def test_guide_and_export_supply_an_importable_standalone_kit(tmp_path: Path) -> None: + """``presentations guide`` and ``export`` deliver the guide and a stdlib-only kit, refusing overwrites.""" + guide = _run_presentations(tmp_path, "guide") + assert guide.returncode == 0, guide.stderr + assert "# Run an E2E scenario with recording and presentation" in guide.stdout + + kit = tmp_path / "kit" + exported = _run_presentations(tmp_path, "export", str(kit)) + assert exported.returncode == 0, exported.stderr + assert f"Presentation tools: {kit / 'presentation_tools'}" in exported.stdout + assert (kit / "presentation_tools" / "README.md").read_text(encoding="utf-8") + "\n" == guide.stdout + + isolated = subprocess.run( + [ + sys.executable, "-I", "-c", + ( + "import sys; sys.path.insert(0, sys.argv[1]); " + "from presentation_tools.producer import Script; " + "from presentation_tools.recording import Recording; " + "import presentation_tools.example; " + "assert 'devcapsule' not in sys.modules and 'tests' not in sys.modules" + ), + str(kit), + ], + cwd=tmp_path, env={"PATH": os.defpath, "PYTHONDONTWRITEBYTECODE": "1"}, + capture_output=True, text=True, timeout=120, check=False, + ) + assert isolated.returncode == 0, isolated.stderr + + refused = _run_presentations(tmp_path, "export", str(kit)) + assert refused.returncode == 2 + assert "cannot export presentation tools" in refused.stderr + + +def test_hand_off_reads_environment_and_handles_token_states(tmp_path: Path) -> None: + """``presentations hand-off`` prints a tokenized link, falls back cleanly on missing or non-UTF-8 tokens, and refuses missing decks or origins.""" + project = tmp_path / "project" + evidence = project / "evidence" / "run-001" + evidence.mkdir(parents=True) + (evidence / "presentation.json").write_text("{}", encoding="utf-8") + token_file = tmp_path / "console-token" + token_file.write_text("secret-token\n", encoding="utf-8") + + with_token = _run_presentations( + tmp_path, "hand-off", str(evidence), + extra_env={ + "PROJECT_PATH": str(project), + "DEVCAPSULE_CONSOLE_URL": "http://127.0.0.1:8787", + "DEVCAPSULE_CONSOLE_TOKEN_FILE": str(token_file), + }, + ) + assert with_token.returncode == 0, with_token.stderr + assert with_token.stdout.strip() == "http://127.0.0.1:8787/presentations/evidence/run-001?token=secret-token" + + token_file.write_bytes(b"\xff\xfe\xfd") + corrupt_token = _run_presentations( + tmp_path, "hand-off", str(evidence), + "--project", str(project), "--console-url", "http://127.0.0.1:8787", "--token-file", str(token_file), + ) + assert corrupt_token.returncode == 0, corrupt_token.stderr + assert "no readable run token was found" in corrupt_token.stdout + assert corrupt_token.stdout.splitlines()[-1] == "http://127.0.0.1:8787/presentations/evidence/run-001" + + missing_url = _run_presentations( + tmp_path, "hand-off", str(evidence), "--project", str(project), "--token-file", str(tmp_path / "absent"), + ) + assert missing_url.returncode == 2 + assert "HTTP(S) console URL" in missing_url.stderr + + empty_dir = project / "evidence" / "empty" + empty_dir.mkdir(parents=True) + missing_deck = _run_presentations( + tmp_path, "hand-off", str(empty_dir), + "--project", str(project), "--console-url", "http://127.0.0.1:8787", + ) + assert missing_deck.returncode == 2 + assert "no presentation.json" in missing_deck.stderr diff --git a/devcapsule-src/tests/unit/devcapsule/presentation_tools/test_producer.py b/devcapsule-src/tests/unit/devcapsule/presentation_tools/test_producer.py index 36ccda2b..2643f304 100644 --- a/devcapsule-src/tests/unit/devcapsule/presentation_tools/test_producer.py +++ b/devcapsule-src/tests/unit/devcapsule/presentation_tools/test_producer.py @@ -216,6 +216,24 @@ def test_plan_presentation_refuses_a_scenario_that_does_not_join_its_script(docu plan_presentation(document, SCRIPT) +@pytest.mark.parametrize( + ("bad_script", "message"), + [ + (Script("", (), (), SCRIPT.steps), "the script has no goal"), + (Script("Goal", (), (), ()), "the script has no steps"), + (Script("Goal", (), (), (ScriptStep(" ", "Open", "Visible"),)), "script step 1 has no title"), + (Script("Goal", (), (), (ScriptStep("Open", " ", "Visible"),)), "script step 1 has no action"), + (Script("Goal", (), (), (ScriptStep("Open", "Open", ""),)), "script step 1 has no expected"), + (Script("Goal", (), (" ",), SCRIPT.steps[:1]), "script illustrations must be non-empty texts"), + (Script("Goal", (("Editor", ""),), (), SCRIPT.steps[:1]), "script stack entries must have non-empty name and detail"), + ], +) +def test_plan_presentation_refuses_incomplete_python_script(bad_script: Script, message: str) -> None: + """``plan_presentation`` refuses Python-constructed scripts with missing goal, steps, step fields, stack or illustrations.""" + with pytest.raises(PresentationError, match=re.escape(message)): + plan_presentation(scenario(action("1. One")), bad_script) + + def test_plan_for_scenario_reads_the_named_script_below_the_root(tmp_path: Path) -> None: """A scenario that names its script is planned from the file at that path below the root.""" (tmp_path / "scripts").mkdir() diff --git a/devcapsule-src/tests/unit/devcapsule/presentation_tools/test_recording.py b/devcapsule-src/tests/unit/devcapsule/presentation_tools/test_recording.py index 5f94ff89..300e9c6f 100644 --- a/devcapsule-src/tests/unit/devcapsule/presentation_tools/test_recording.py +++ b/devcapsule-src/tests/unit/devcapsule/presentation_tools/test_recording.py @@ -1,18 +1,84 @@ -"""Recorder preconditions require no browser, clock or external process.""" +"""Unit tests for ``devcapsule.presentation_tools.recording``.""" +from __future__ import annotations + +import json from pathlib import Path +import subprocess +import sys import pytest from devcapsule.presentation_tools.producer import PresentationError, Script, ScriptStep from devcapsule.presentation_tools.recording import Recording +SCRIPT = Script( + goal="Verify the application flow.", + stack=(("Browser", "Chromium"),), + illustrates=("A passing and failing check.",), + steps=( + ScriptStep("Open", "Open the app", "The heading appears"), + ScriptStep("Reload", "Reload the page", "The heading stays"), + ), +) + + +class _StubPage: + """In-memory Playwright page double recording captured bytes and wait calls.""" + + def __init__(self, *, fail_jpeg_at: int | None = None, fail_png_at: int | None = None) -> None: + self.fail_jpeg_at = fail_jpeg_at + self.fail_png_at = fail_png_at + self.jpeg_calls = 0 + self.png_calls = 0 + self.captured_jpeg_bytes = bytearray() + self.waits: list[int] = [] + + def screenshot(self, *, type: str = "png", quality: int | None = None, path: str | None = None) -> bytes: + del quality + if path is None: + self.jpeg_calls += 1 + if self.fail_jpeg_at is not None and self.jpeg_calls >= self.fail_jpeg_at: + raise RuntimeError("page disconnected during frame capture") + assert type == "jpeg" + chunk = f"FRAME-{self.jpeg_calls}:".encode("ascii") + self.captured_jpeg_bytes.extend(chunk) + return chunk + self.png_calls += 1 + if self.fail_png_at is not None and self.png_calls >= self.fail_png_at: + raise RuntimeError("page disconnected during step screenshot") + Path(path).write_bytes(f"PNG-{self.png_calls}".encode("ascii")) + return b"" + + def wait_for_timeout(self, ms: int) -> None: + self.waits.append(ms) + + +def _encoder_command(*, exit_code: int = 0, write_video: bool = True) -> tuple[str, ...]: + program = ( + "import pathlib, sys; " + "data = sys.stdin.buffer.read(); " + "sys.stderr.write(f'bytes={len(data)}\\n'); " + f"pathlib.Path(sys.argv[-1]).write_bytes(b'WEBM:' + data) if {write_video!r} else None; " + f"sys.exit({exit_code})" + ) + return (sys.executable, "-I", "-S", "-c", program) -@pytest.mark.parametrize("steps", [(), (ScriptStep("Open", "Open the app", "The heading appears"),)]) -def test_recording_rejects_invalid_setup_before_creating_evidence(tmp_path: Path, steps: tuple[ScriptStep, ...]) -> None: - """An empty script or absent encoder is refused before an evidence folder exists.""" + +@pytest.mark.parametrize( + ("steps", "ffmpeg"), + [ + ((), ("encoder",)), + ((ScriptStep("Open", "Open the app", "The heading appears"),), ()), + ((ScriptStep("Open", "Open the app", "The heading appears"),), "ffmpeg"), + ], +) +def test_recording_rejects_invalid_setup_before_creating_evidence( + tmp_path: Path, steps: tuple[ScriptStep, ...], ffmpeg: tuple[str, ...] | str, +) -> None: + """An empty script, absent encoder or unsplit string encoder is refused before an evidence folder exists.""" with pytest.raises(PresentationError): Recording(tmp_path / "run", script=Script("Goal", (), (), steps), scenario_id="example", - title="Example", summary="Example run", ffmpeg=()) + title="Example", summary="Example run", ffmpeg=ffmpeg) assert not (tmp_path / "run").exists() @@ -20,7 +86,248 @@ def test_recording_rejects_invalid_setup_before_creating_evidence(tmp_path: Path def test_recording_preserves_existing_evidence(tmp_path: Path) -> None: """A recording cannot overwrite a prior attempt, even if that directory is empty.""" with pytest.raises(FileExistsError): - Recording(tmp_path, script=Script("Goal", (), (), (ScriptStep("Open", "Open", "Visible"),)), - scenario_id="example", title="Example", summary="Example run", ffmpeg=("encoder",)) + Recording(tmp_path, script=SCRIPT, scenario_id="example", title="Example", + summary="Example run", ffmpeg=("encoder",)) assert list(tmp_path.iterdir()) == [] + + +def test_recording_finish_writes_aligned_deck_and_media_for_passing_run(tmp_path: Path) -> None: + """Finishing a complete multi-action run encodes captured bytes and aligns chapters to frame boundaries.""" + # Precondition: record a complete two-step run (two actions in step 1, one in step 2). + evidence = tmp_path / "run-pass" + page = _StubPage() + recording = Recording(evidence, script=SCRIPT, scenario_id="example", title=" Example ", + summary="Example run", ffmpeg=_encoder_command()) + recording.action(page, 1, "Navigate to page", lambda: None) + recording.action(page, 1, "Confirm heading", lambda: None) + recording.action(page, 2, "Reload page", lambda: None) + + # Action: finalize the recording. + manifest = recording.finish() + + # Postcondition: logs record increasing frame boundaries, deck aligns to them, and encoder gets captured bytes. + result = json.loads((evidence / "scenario-result.json").read_text(encoding="utf-8")) + actions = json.loads((evidence / "action-log.json").read_text(encoding="utf-8")) + boundaries = [entry["frames_after"] for entry in actions] + deck = json.loads(manifest.read_text(encoding="utf-8")) + assert result == {"status": "passed", "error": "", "steps_reached": 2, "steps_planned": 2} + assert len(boundaries) == 3 and 0 < boundaries[0] < boundaries[1] < boundaries[2] + assert deck["title"] == "Example" + assert deck["video"]["file"] == "scenario-video.webm" + assert deck["video"]["poster"] == "poster.png" + assert deck["video"]["duration"] > 0 + step1, step2 = deck["steps"] + assert (step1["screenshot"], step2["screenshot"]) == ("step-002.png", "step-003.png") + assert step1["start"] == 0.0 + assert 0.0 < step1["end"] == step2["start"] < step2["end"] == deck["video"]["duration"] + assert [c["text"] for c in step1["captions"]] == ["Navigate to page", "Confirm heading"] + assert [c["text"] for c in step2["captions"]] == ["Reload page"] + assert step1["captions"][0]["start"] == step1["start"] + assert step1["captions"][0]["end"] == step1["captions"][1]["start"] + assert step1["captions"][1]["end"] == step1["end"] + assert step2["captions"][0]["start"] == step2["start"] and step2["captions"][0]["end"] == step2["end"] + assert (evidence / "poster.png").read_bytes() == (evidence / "step-001.png").read_bytes() + assert (evidence / "scenario-video.webm").read_bytes() == b"WEBM:" + bytes(page.captured_jpeg_bytes) + assert f"bytes={len(page.captured_jpeg_bytes)}\n" in (evidence / "ffmpeg.log").read_text(encoding="utf-8") + + +def test_recording_action_reraises_callback_failure_and_records_failed_state(tmp_path: Path) -> None: + """A failing action callback propagates its exception while preserving failed logs and screenshot.""" + # Precondition: step 1 succeeded. + evidence = tmp_path / "run-fail-action" + page = _StubPage() + recording = Recording(evidence, script=SCRIPT, scenario_id="example", title="Example", + summary="Example run", ffmpeg=_encoder_command()) + recording.action(page, 1, "Open app", lambda: None) + + def fail_reload() -> None: + raise AssertionError("heading missing") + + # Action: execute a failing callback in step 2. + with pytest.raises(AssertionError, match="heading missing"): + recording.action(page, 2, "Reload app", fail_reload) + + # Postcondition: failure state, action log and failure screenshot are recorded on disk. + result = json.loads((evidence / "scenario-result.json").read_text(encoding="utf-8")) + actions = json.loads((evidence / "action-log.json").read_text(encoding="utf-8")) + assert result == { + "status": "failed", + "error": "AssertionError: heading missing", + "steps_reached": 2, + "steps_planned": 2, + } + assert actions[1]["status"] == "failed" and actions[1]["error"] == "AssertionError: heading missing" + assert (evidence / "step-002.png").is_file() + + +def test_recording_action_refuses_calls_after_failure(tmp_path: Path) -> None: + """Once an action fails, any subsequent action call is refused before capturing frames.""" + # Precondition: step 1 failed. + page = _StubPage() + recording = Recording(tmp_path / "run-after-fail", script=SCRIPT, scenario_id="example", title="Example", + summary="Example run", ffmpeg=_encoder_command()) + with pytest.raises(AssertionError): + recording.action(page, 1, "Open app", lambda: (_ for _ in ()).throw(AssertionError("boom"))) + calls_before = page.jpeg_calls + + # Action: attempt another action on the failed recording. + with pytest.raises(PresentationError, match="finished or failed"): + recording.action(page, 2, "Reload app", lambda: None) + + # Postcondition: no further frames were captured. + assert page.jpeg_calls == calls_before + + +def test_recording_finish_writes_failed_deck_for_reached_steps(tmp_path: Path) -> None: + """Finishing a failed run keeps the failed result and labels the presentation FAILED.""" + # Precondition: step 1 passed and step 2 failed with visual evidence intact. + evidence = tmp_path / "run-finish-fail" + page = _StubPage() + recording = Recording(evidence, script=SCRIPT, scenario_id="example", title=" Example ", + summary="Example run", ffmpeg=_encoder_command()) + recording.action(page, 1, "Open app", lambda: None) + with pytest.raises(AssertionError): + recording.action(page, 2, "Reload app", lambda: (_ for _ in ()).throw(AssertionError("heading missing"))) + + # Action: finalize the failed recording. + manifest = recording.finish() + + # Postcondition: result remains failed and presentation is labelled FAILED for the two reached steps. + result = json.loads((evidence / "scenario-result.json").read_text(encoding="utf-8")) + deck = json.loads(manifest.read_text(encoding="utf-8")) + assert result["status"] == "failed" and result["error"] == "AssertionError: heading missing" + assert deck["title"] == "Example (FAILED)" + assert len(deck["steps"]) == 2 + + +def test_recording_labels_incomplete_run_with_only_reached_steps(tmp_path: Path) -> None: + """Finishing before all script steps run keeps an incomplete status and an INCOMPLETE deck.""" + # Precondition: only step 1 of 2 ran. + evidence = tmp_path / "run-incomplete" + page = _StubPage() + recording = Recording(evidence, script=SCRIPT, scenario_id="example", title="Example", + summary="Example run", ffmpeg=_encoder_command()) + recording.action(page, 1, "Open app", lambda: None) + + # Action: finalize the partial recording. + manifest = recording.finish() + + # Postcondition: result stays incomplete and deck contains only the reached step. + result = json.loads((evidence / "scenario-result.json").read_text(encoding="utf-8")) + deck = json.loads(manifest.read_text(encoding="utf-8")) + assert result == {"status": "incomplete", "error": "", "steps_reached": 1, "steps_planned": 2} + assert deck["title"] == "Example (INCOMPLETE)" + assert len(deck["steps"]) == 1 + + +@pytest.mark.parametrize(("step", "caption"), [(0, "Open"), (True, "Open"), (2, "Skipped"), (1, " ")]) +def test_recording_refuses_invalid_step_order_or_empty_caption( + tmp_path: Path, step: int | bool, caption: str, +) -> None: + """Out-of-order steps, boolean steps and blank captions are refused before capturing frames.""" + page = _StubPage() + recording = Recording(tmp_path / "run", script=SCRIPT, scenario_id="example", title="Example", + summary="Example run", ffmpeg=_encoder_command()) + + with pytest.raises(PresentationError): + recording.action(page, step, caption, lambda: None) + + assert page.jpeg_calls == 0 + + +def test_recording_finish_refuses_second_call(tmp_path: Path) -> None: + """Finishing an already finished recording raises PresentationError.""" + # Precondition: recording is already finished. + page = _StubPage() + recording = Recording(tmp_path / "run", script=SCRIPT, scenario_id="example", title="Example", + summary="Example run", ffmpeg=_encoder_command()) + recording.action(page, 1, "Open", lambda: None) + recording.finish() + + # Action: call finish a second time. + with pytest.raises(PresentationError, match="already been finished"): + recording.finish() + + +def test_recording_action_refuses_calls_after_finish(tmp_path: Path) -> None: + """Calling action after finish raises PresentationError without capturing frames.""" + # Precondition: recording is already finished. + page = _StubPage() + recording = Recording(tmp_path / "run", script=SCRIPT, scenario_id="example", title="Example", + summary="Example run", ffmpeg=_encoder_command()) + recording.action(page, 1, "Open", lambda: None) + recording.finish() + calls_before = page.jpeg_calls + + # Action: attempt another action after finish. + with pytest.raises(PresentationError, match="finished or failed"): + recording.action(page, 2, "Reload", lambda: None) + + assert page.jpeg_calls == calls_before + + +def test_recording_finish_refuses_run_with_no_actions(tmp_path: Path) -> None: + """Finishing with zero actions writes an incomplete result and refuses writing a presentation.""" + evidence = tmp_path / "empty" + recording = Recording(evidence, script=SCRIPT, scenario_id="example", title="Example", + summary="Example run", ffmpeg=_encoder_command()) + + with pytest.raises(PresentationError, match="no complete visual evidence"): + recording.finish() + + assert json.loads((evidence / "scenario-result.json").read_text(encoding="utf-8"))["status"] == "incomplete" + assert not (evidence / "presentation.json").exists() + + +def test_recording_finish_refuses_run_with_missing_step_screenshot(tmp_path: Path) -> None: + """Finishing when a failed action could not save a screenshot keeps the failed result and writes no deck.""" + # Precondition: step 1 callback failed and screenshot capture also failed. + evidence = tmp_path / "broken-capture" + page = _StubPage(fail_png_at=1) + recording = Recording(evidence, script=SCRIPT, scenario_id="example", title="Example", + summary="Example run", ffmpeg=_encoder_command()) + with pytest.raises(AssertionError, match="original test assertion"): + recording.action(page, 1, "Open", lambda: (_ for _ in ()).throw(AssertionError("original test assertion"))) + + # Action: finalize the recording without complete screenshots. + with pytest.raises(PresentationError, match="no complete visual evidence"): + recording.finish() + + assert json.loads((evidence / "scenario-result.json").read_text(encoding="utf-8"))["status"] == "failed" + assert not (evidence / "presentation.json").exists() + + +def test_recording_finish_preserves_logs_when_encoder_fails(tmp_path: Path) -> None: + """A non-zero encoder exit leaves result and encoder logs intact and writes neither poster nor presentation.""" + # Precondition: step 1 succeeded with an encoder configured to exit 1. + evidence = tmp_path / "encode-fail" + recording = Recording(evidence, script=SCRIPT, scenario_id="example", title="Example", + summary="Example run", ffmpeg=_encoder_command(exit_code=1, write_video=False)) + recording.action(_StubPage(), 1, "Open", lambda: None) + + # Action: finalize the recording. + with pytest.raises(subprocess.CalledProcessError): + recording.finish() + + assert json.loads((evidence / "scenario-result.json").read_text(encoding="utf-8"))["status"] == "incomplete" + assert (evidence / "ffmpeg.log").is_file() + assert not (evidence / "presentation.json").exists() + assert not (evidence / "poster.png").exists() + + +def test_recording_finish_withholds_deck_when_encoder_writes_no_video(tmp_path: Path) -> None: + """An encoder that exits zero without writing scenario-video.webm raises PresentationError and writes no deck.""" + # Precondition: step 1 succeeded with an encoder that exits 0 without producing video output. + evidence = tmp_path / "encode-empty" + recording = Recording(evidence, script=SCRIPT, scenario_id="example", title="Example", + summary="Example run", ffmpeg=_encoder_command(exit_code=0, write_video=False)) + recording.action(_StubPage(), 1, "Open", lambda: None) + + # Action: finalize the recording. + with pytest.raises(PresentationError, match="scenario-video.webm"): + recording.finish() + + assert (evidence / "ffmpeg.log").is_file() + assert not (evidence / "presentation.json").exists() + assert not (evidence / "poster.png").exists() diff --git a/devcapsule-src/tests/unit/devcapsule/test_presentation_authoring.py b/devcapsule-src/tests/unit/devcapsule/test_presentation_authoring.py index 8535f983..ac2e3c8b 100644 --- a/devcapsule-src/tests/unit/devcapsule/test_presentation_authoring.py +++ b/devcapsule-src/tests/unit/devcapsule/test_presentation_authoring.py @@ -61,7 +61,19 @@ def test_link_refuses_folders_the_console_cannot_list(folder: str) -> None: console_url="http://localhost:8000", token="") -@pytest.mark.parametrize("url", ["", "file:///tmp", "https:///missing-host", "https://user:secret@example.org"]) +@pytest.mark.parametrize( + "url", + [ + "", + "file:///tmp", + "https:///missing-host", + "http://:8000", + "http://@example.org", + "http://localhost:bad", + "http://localhost:8000 ", + "https://user:secret@example.org", + ], +) def test_link_refuses_invalid_console_origins(url: str) -> None: """The console origin must be HTTP(S) and must not embed user credentials.""" with pytest.raises(ValueError):