Skip to content

A visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.

11.4 KB
Raw Blame
"""Tests for the Pele rendering glue (pele_renderer.py + pele_render.mjs)."""

from __future__ import annotations

import json
import logging
import os
import shutil
import subprocess
import sys
from pathlib import Path
from typing import Any

import pytest

sys.path.insert(0, str(Path(__file__).parent.parent))

import pele_renderer
from pele_renderer import (
    HELPER,
    PeleHelperError,
    PeleUnavailableError,
    find_node,
    render_diagrams,
)

# Read once at import time on purpose: fixtures that clear CI for other tests
# must not turn the "fail instead of skip in CI" rule below into a skip.
_IN_CI = os.environ.get("CI", "").strip().lower() in {"1", "true", "yes"}

# A stand-in for dist/pele.js that speaks the same protocol as the real
# bundle: render() returns {svg, type, width, height} or throws an object
# carrying a PeleError-style code/line/column.
STUB_BUNDLE = """\
export function render(source, options) {
  if (source.includes('SYNTAX_ERROR')) {
    throw { code: 'syntax', message: 'Unexpected token', line: 2, column: 3 };
  }
  if (source.includes('CRASH')) {
    throw new TypeError('boom');
  }
  const kind = source.startsWith('sequenceDiagram') ? 'sequence' : 'flowchart';
  return { svg: '<svg xmlns="http://www.w3.org/2000/svg"/>', type: kind,
           width: 1, height: 1, links: [] };
}
"""


@pytest.fixture
def logger() -> logging.Logger:
    return logging.getLogger("test_pele_renderer")


@pytest.fixture
def real_node() -> str:
    """A real Node.js binary; skip locally without one, but fail in CI."""
    node = shutil.which("node")
    if node is None:
        if _IN_CI:
            pytest.fail("node is required in CI to test the Pele helper")
        pytest.skip("node is not installed")
    return node


def _completed(
    stdout: str = "", returncode: int = 0, stderr: str = ""
) -> subprocess.CompletedProcess[str]:
    return subprocess.CompletedProcess(
        args=["node"], returncode=returncode, stdout=stdout, stderr=stderr
    )


# =============================================================================
# find_node
# =============================================================================


class TestFindNode:
    def test_missing_node(self, monkeypatch: pytest.MonkeyPatch) -> None:
        monkeypatch.setattr(pele_renderer.shutil, "which", lambda _name: None)
        with pytest.raises(PeleUnavailableError, match=r"Node\.js >= 20"):
            find_node()

    def test_node_too_old(self, monkeypatch: pytest.MonkeyPatch) -> None:
        monkeypatch.setattr(pele_renderer.shutil, "which", lambda _name: "/x/node")
        monkeypatch.setattr(
            pele_renderer.subprocess,
            "run",
            lambda *_a, **_k: _completed("v18.19.1\n"),
        )
        with pytest.raises(PeleUnavailableError, match="too old"):
            find_node()

    def test_node_20_is_accepted(self, monkeypatch: pytest.MonkeyPatch) -> None:
        monkeypatch.setattr(pele_renderer.shutil, "which", lambda _name: "/x/node")
        monkeypatch.setattr(
            pele_renderer.subprocess,
            "run",
            lambda *_a, **_k: _completed("v20.1.0\n"),
        )
        assert find_node() == "/x/node"

    def test_unreadable_version(self, monkeypatch: pytest.MonkeyPatch) -> None:
        monkeypatch.setattr(pele_renderer.shutil, "which", lambda _name: "/x/node")
        monkeypatch.setattr(
            pele_renderer.subprocess,
            "run",
            lambda *_a, **_k: _completed("", returncode=1),
        )
        with pytest.raises(PeleUnavailableError, match="version"):
            find_node()


# =============================================================================
# render_diagrams (helper process mocked)
# =============================================================================


class TestRenderDiagramsMocked:
    @pytest.fixture
    def env(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> dict[str, Any]:
        """Stub node discovery and the bundle so only the protocol is tested."""
        monkeypatch.setattr(pele_renderer, "find_node", lambda: "/x/node")
        monkeypatch.setattr(
            pele_renderer, "ensure_pele_bundle", lambda _logger: tmp_path
        )
        calls: dict[str, Any] = {}
        return calls

    def _fake_run(
        self, monkeypatch: pytest.MonkeyPatch, calls: dict[str, Any], **result: Any
    ) -> None:
        def fake_run(cmd: list[str], **kwargs: Any) -> Any:
            calls["cmd"] = cmd
            calls["input"] = kwargs.get("input")
            if isinstance(result.get("raise"), BaseException):
                raise result["raise"]
            return _completed(
                result.get("stdout", ""),
                result.get("returncode", 0),
                result.get("stderr", ""),
            )

        monkeypatch.setattr(pele_renderer.subprocess, "run", fake_run)

    def test_parses_results_in_order(
        self,
        env: dict[str, Any],
        monkeypatch: pytest.MonkeyPatch,
        tmp_path: Path,
        logger: logging.Logger,
    ) -> None:
        payload = {
            "results": [
                {"svg": "<svg/>", "type": "flowchart", "width": 1, "height": 1},
                {
                    "error": {
                        "code": "syntax",
                        "message": "Unexpected token",
                        "line": 2,
                        "column": 3,
                    }
                },
            ]
        }
        self._fake_run(monkeypatch, env, stdout=json.dumps(payload))

        results = render_diagrams(["graph TD\n A-->B", "graph TD\n A-->"], logger)

        assert env["cmd"] == ["/x/node", str(HELPER), str(tmp_path / "pele.mjs")]
        assert json.loads(env["input"])["diagrams"] == [
            "graph TD\n A-->B",
            "graph TD\n A-->",
        ]
        assert results[0].svg == "<svg/>"
        assert results[0].diagram_type == "flowchart"
        assert results[0].error is None
        assert results[1].svg is None
        assert results[1].error is not None
        assert results[1].error.code == "syntax"
        assert results[1].error.line == 2
        assert results[1].error.describe() == (
            "[syntax] Unexpected token (diagram line 2, column 3)"
        )

    def test_wrong_result_count(
        self, env: dict[str, Any], monkeypatch: pytest.MonkeyPatch, logger: Any
    ) -> None:
        self._fake_run(monkeypatch, env, stdout=json.dumps({"results": []}))
        with pytest.raises(PeleHelperError, match="0 result"):
            render_diagrams(["graph TD\n A-->B"], logger)

    def test_invalid_json(
        self, env: dict[str, Any], monkeypatch: pytest.MonkeyPatch, logger: Any
    ) -> None:
        self._fake_run(monkeypatch, env, stdout="not json")
        with pytest.raises(PeleHelperError, match="invalid JSON"):
            render_diagrams(["graph TD\n A-->B"], logger)

    def test_missing_svg_is_malformed(
        self, env: dict[str, Any], monkeypatch: pytest.MonkeyPatch, logger: Any
    ) -> None:
        self._fake_run(
            monkeypatch, env, stdout=json.dumps({"results": [{"type": "flowchart"}]})
        )
        with pytest.raises(PeleHelperError, match="no SVG"):
            render_diagrams(["graph TD\n A-->B"], logger)

    def test_nonzero_exit(
        self, env: dict[str, Any], monkeypatch: pytest.MonkeyPatch, logger: Any
    ) -> None:
        self._fake_run(monkeypatch, env, returncode=1, stderr="SyntaxError: x")
        with pytest.raises(PeleHelperError, match="status 1: SyntaxError"):
            render_diagrams(["graph TD\n A-->B"], logger)

    def test_timeout(
        self, env: dict[str, Any], monkeypatch: pytest.MonkeyPatch, logger: Any
    ) -> None:
        self._fake_run(
            monkeypatch, env, **{"raise": subprocess.TimeoutExpired("node", 5)}
        )
        with pytest.raises(PeleHelperError, match="timed out"):
            render_diagrams(["graph TD\n A-->B"], logger, timeout=5)

    @pytest.mark.parametrize(
        "error",
        [
            RuntimeError("Checksum mismatch for Pele"),
            OSError("network is unreachable"),
        ],
    )
    def test_bundle_failure_is_unavailable(
        self,
        monkeypatch: pytest.MonkeyPatch,
        logger: logging.Logger,
        error: Exception,
    ) -> None:
        monkeypatch.setattr(pele_renderer, "find_node", lambda: "/x/node")

        def broken_bundle(_logger: logging.Logger) -> Path:
            raise error

        monkeypatch.setattr(pele_renderer, "ensure_pele_bundle", broken_bundle)
        with pytest.raises(PeleUnavailableError, match="bundle"):
            render_diagrams(["graph TD\n A-->B"], logger)


# =============================================================================
# Real helper protocol (Node required, stub bundle, no network)
# =============================================================================


class TestHelperWithNode:
    def test_round_trip_with_stub_bundle(
        self,
        real_node: str,
        tmp_path: Path,
        monkeypatch: pytest.MonkeyPatch,
        logger: logging.Logger,
    ) -> None:
        (tmp_path / "pele.mjs").write_text(STUB_BUNDLE, encoding="utf-8")
        monkeypatch.setattr(
            pele_renderer, "ensure_pele_bundle", lambda _logger: tmp_path
        )

        results = render_diagrams(
            [
                "graph TD\n  A --> B",
                "graph TD\n  SYNTAX_ERROR",
                "sequenceDiagram\n  A->>B: hi",
                "graph TD\n  CRASH",
            ],
            logger,
        )

        assert [r.diagram_type for r in results] == [
            "flowchart",
            None,
            "sequence",
            None,
        ]
        assert results[0].svg is not None
        assert results[0].svg.startswith("<svg")
        syntax = results[1].error
        assert syntax is not None
        assert (syntax.code, syntax.line, syntax.column) == ("syntax", 2, 3)
        crash = results[3].error
        assert crash is not None
        assert crash.code == "internal"
        assert "boom" in crash.message

    def test_helper_rejects_missing_argument(self, real_node: str) -> None:
        proc = subprocess.run(
            [real_node, str(HELPER)],
            input="{}",
            capture_output=True,
            text=True,
            timeout=60,
            check=False,
        )
        assert proc.returncode == 2
        assert "pele.mjs" in proc.stderr

    def test_bundle_loads_as_esm_without_syntax_detection(
        self,
        real_node: str,
        tmp_path: Path,
        monkeypatch: pytest.MonkeyPatch,
        logger: logging.Logger,
    ) -> None:
        # Node.js 20.0-20.18 and 22.0-22.6 have no ES module syntax
        # detection: a bare .js bundle loads as CommonJS and fails on
        # `export`. Turn detection off to get that behaviour on newer Node.
        flag = "--no-experimental-detect-module"
        probe = subprocess.run(
            [real_node, flag, "-e", ""], capture_output=True, timeout=60, check=False
        )
        if probe.returncode != 0:
            pytest.skip(f"this Node.js does not accept {flag}")
        monkeypatch.setenv("NODE_OPTIONS", flag)
        bundle = tmp_path / pele_renderer.PELE_ESM_BUNDLE
        bundle.write_text(STUB_BUNDLE, encoding="utf-8")
        monkeypatch.setattr(
            pele_renderer, "ensure_pele_bundle", lambda _logger: tmp_path
        )

        results = render_diagrams(["graph TD\n  A --> B"], logger)

        assert bundle.suffix == ".mjs"
        assert results[0].error is None
        assert results[0].diagram_type == "flowchart"