feat: add unit tests for panel alignment and inset functionality

Author: CSSFrancis

anyplotlib/tests/test_layouts/test_gridspec.py

@@ -2,11 +2,10 @@
 tests/test_gridspec.py
 ======================
 
-Tests for GridSpec / SubplotSpec indexing AND the figure sizing pipeline
-(_compute_cell_sizes) that converts grid specs + figsize into per-panel
-canvas pixel dimensions.
+Tests for GridSpec / SubplotSpec indexing, the figure sizing pipeline
+(_compute_cell_sizes), and per-panel plot-area alignment.
 
-The sizing contract (all measured at the *canvas* level, before PAD margins):
+Sizing contract (all measured at the *canvas* level, before PAD margins):
   - All panels in the same grid column have the same canvas width  (pw).
   - All panels in the same grid row    have the same canvas height (ph).
   - Grid tracks are pure ratio math — no aspect-locking.
@@ -19,6 +18,13 @@
     sum(row tracks) <= fh.
   - Images are rendered "contain" (letterboxed) in JS — the Python layout
     engine never modifies tracks because of image content.
+
+Alignment contract (inner plot-area coordinates, shared PAD constants):
+  - PAD_L=58  PAD_R=12  PAD_T=12  PAD_B=42
+  - The inner plot/image area for any panel kind is:
+      x=PAD_L, y=PAD_T, w=pw-PAD_L-PAD_R, h=ph-PAD_T-PAD_B
+  - All panels in the same column share pw → same left/right edges.
+  - All panels in the same row share ph → same top/bottom edges.
 """
 
 from __future__ import annotations
@@ -31,6 +37,9 @@
 from anyplotlib.figure import Figure
 from anyplotlib.figure_plots import GridSpec, SubplotSpec, Axes  # noqa: F401
 
+# PAD constants must match figure_esm.js (used in panel-alignment tests)
+PAD_L, PAD_R, PAD_T, PAD_B = 58, 12, 12, 42
+
 
 # ─────────────────────────────────────────────────────────────────────────────
 # Helpers
@@ -705,6 +714,129 @@ def test_figsize_in_layout_json(self):
         assert layout["fig_height"] == 555
 
 
+# ─────────────────────────────────────────────────────────────────────────────
+# Part 8 – Panel alignment
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _plot_area(pw: int, ph: int) -> tuple[int, int, int, int]:
+    """Return (x, y, w, h) of the inner plot/image area for any panel kind.
+
+    Both 1-D and 2-D panels use the same PAD constants in figure_esm.js,
+    so as long as Python assigns the same (pw, ph) to sibling panels they
+    are guaranteed to be pixel-aligned inside the shared canvas grid cell.
+    """
+    return PAD_L, PAD_T, pw - PAD_L - PAD_R, ph - PAD_T - PAD_B
+
+
+class TestPanelAlignment:
+    """Same-row / same-column panels must share canvas dimensions and
+    therefore produce identical inner plot-area coordinates."""
+
+    # ── two-row, one-column ───────────────────────────────────────────────
+
+    def test_2row_1col_same_width(self):
+        fig, axs = vw.subplots(2, 1, figsize=(600, 600))
+        v2d = axs[0].imshow(np.random.rand(128, 128))
+        v1d = axs[1].plot(np.sin(np.linspace(0, 6, 256)))
+        s = _sizes(fig)
+        pw2d = s[v2d._id][0]
+        pw1d = s[v1d._id][0]
+        assert pw2d == pw1d, (
+            f"Panels in same column must have equal width: 2D={pw2d}, 1D={pw1d}"
+        )
+
+    def test_2row_1col_left_edge_aligned(self):
+        """Left edge of the 2D image area and 1D plot area must both be PAD_L."""
+        fig, axs = vw.subplots(2, 1, figsize=(600, 600))
+        v2d = axs[0].imshow(np.random.rand(128, 128))
+        v1d = axs[1].plot(np.sin(np.linspace(0, 6, 256)))
+        s = _sizes(fig)
+        x2d = _plot_area(*s[v2d._id])[0]
+        x1d = _plot_area(*s[v1d._id])[0]
+        assert x2d == x1d == PAD_L, (
+            f"Left edge must be PAD_L={PAD_L}: 2D={x2d}, 1D={x1d}"
+        )
+
+    def test_2row_1col_plot_area_widths_equal(self):
+        """Plot-area widths must match when panels share a column."""
+        fig, axs = vw.subplots(2, 1, figsize=(600, 600))
+        v2d = axs[0].imshow(np.random.rand(128, 128))
+        v1d = axs[1].plot(np.sin(np.linspace(0, 6, 256)))
+        s = _sizes(fig)
+        w2d = _plot_area(*s[v2d._id])[2]
+        w1d = _plot_area(*s[v1d._id])[2]
+        assert w2d == w1d, f"Plot area widths: 2D={w2d}, 1D={w1d}"
+
+    # ── one-row, two-column ───────────────────────────────────────────────
+
+    def test_1row_2col_same_height(self):
+        fig, axs = vw.subplots(1, 2, figsize=(800, 400))
+        v2d = axs[0].imshow(np.random.rand(64, 64))
+        v1d = axs[1].plot(np.cos(np.linspace(0, 6, 256)))
+        s = _sizes(fig)
+        ph2d = s[v2d._id][1]
+        ph1d = s[v1d._id][1]
+        assert ph2d == ph1d, (
+            f"Panels in same row must have equal height: 2D={ph2d}, 1D={ph1d}"
+        )
+
+    def test_1row_2col_top_bottom_aligned(self):
+        """Top and bottom y-coordinates of plot areas must match across the row."""
+        fig, axs = vw.subplots(1, 2, figsize=(800, 400))
+        v2d = axs[0].imshow(np.random.rand(64, 64))
+        v1d = axs[1].plot(np.cos(np.linspace(0, 6, 256)))
+        s = _sizes(fig)
+        y2d, h2d = _plot_area(*s[v2d._id])[1], _plot_area(*s[v2d._id])[3]
+        y1d, h1d = _plot_area(*s[v1d._id])[1], _plot_area(*s[v1d._id])[3]
+        assert y2d == y1d == PAD_T, f"Top y: 2D={y2d}, 1D={y1d}"
+        assert h2d == h1d, f"Plot area heights: 2D={h2d}, 1D={h1d}"
+
+    # ── 2D panel canvas equals its grid cell ─────────────────────────────
+
+    def test_square_image_gets_square_canvas(self):
+        """A 128×128 image in a 500×500 figsize → canvas is 500×500 (pw == ph).
+        Images are letterboxed in JS; the Python layout never changes the cell."""
+        fig, axs = vw.subplots(1, 1, figsize=(500, 500))
+        v2d = axs.imshow(np.random.rand(128, 128))
+        pw, ph = _sizes(fig)[v2d._id]
+        assert pw == ph, f"Square figsize must give pw==ph: pw={pw}, ph={ph}"
+
+    def test_wide_image_canvas_equals_cell(self):
+        """A 2:1 image in a square cell gets a square canvas — no aspect-lock."""
+        fig, axs = vw.subplots(1, 1, figsize=(512, 512))
+        v2d = axs.imshow(np.random.rand(128, 256))  # w=256, h=128
+        pw, ph = _sizes(fig)[v2d._id]
+        assert pw == 512 and ph == 512, (
+            f"Canvas should equal full figsize 512×512, got {pw}×{ph}"
+        )
+
+    # ── non-square 2D panel plus 1D panel — column width consistent ───────
+
+    def test_nonsquare_2d_and_1d_same_column(self):
+        """A tall non-square image in a 2-row, 1-col layout must not affect the
+        1D panel's canvas width — both must equal the column track width."""
+        fig, axs = vw.subplots(2, 1, figsize=(600, 800))
+        v2d = axs[0].imshow(np.random.rand(256, 128))  # tall image
+        v1d = axs[1].plot(np.random.rand(256))
+        s = _sizes(fig)
+        pw2d = s[v2d._id][0]
+        pw1d = s[v1d._id][0]
+        assert pw2d == pw1d, (
+            f"Same-column panels must have equal width: 2D={pw2d}, 1D={pw1d}"
+        )
+
+    # ── plot-area dimensions are positive ─────────────────────────────────
+
+    def test_plot_areas_positive(self):
+        fig, axs = vw.subplots(2, 1, figsize=(400, 400))
+        v2d = axs[0].imshow(np.random.rand(64, 64))
+        v1d = axs[1].plot(np.random.rand(128))
+        for pid, (pw, ph) in _sizes(fig).items():
+            x, y, w, h = _plot_area(pw, ph)
+            assert w > 0, f"Panel {pid}: plot area width must be positive, got {w}"
+            assert h > 0, f"Panel {pid}: plot area height must be positive, got {h}"
+
+
 
 
 

…yplotlib/tests/test_plot3d/test_inset.py …plotlib/tests/test_layouts/test_inset.pyanyplotlib/tests/test_plot3d/test_inset.py renamed to anyplotlib/tests/test_layouts/test_inset.py anyplotlib/tests/test_plot3d/test_inset.py renamed to anyplotlib/tests/test_layouts/test_inset.py

@@ -1,6 +1,8 @@
 """
 Tests for InsetAxes — floating overlay inset panels.
 
+Unit tests
+----------
 Covers:
   - Creation via fig.add_inset()
   - layout_json inset_specs content
@@ -13,15 +15,33 @@
   - Invalid corner raises ValueError
   - Figure resize keeps inset fracs correct
   - plot._id registered in _plots_map
+
+Visual regression tests
+-----------------------
+Pixel-accurate rendering checks for inset panels in a headless Chromium
+browser.  Each test renders a deterministic Figure and compares it against
+a golden PNG in ``tests/baselines/``.
+
+Generate / refresh baselines::
+
+    uv run pytest tests/test_layouts/test_inset.py --update-baselines -v
+
+Normal CI run (fails on regression)::
+
+    uv run pytest tests/test_layouts/test_inset.py -v
 """
+from __future__ import annotations
+
 import json
+import pathlib
+
 import numpy as np
 import pytest
 import anyplotlib as apl
 from anyplotlib.figure_plots import InsetAxes
 
 
-# ── helpers ──────────────────────────────────────────────────────────────────
+# ── helpers (unit tests) ──────────────────────────────────────────────────────
 
 def _make_fig():
     fig, ax = apl.subplots(1, 1, figsize=(640, 480))
@@ -247,3 +267,120 @@ def test_repr():
     assert "top-right" in r
     assert "normal" in r
 
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Visual regression tests
+# ─────────────────────────────────────────────────────────────────────────────
+
+BASELINES = pathlib.Path(__file__).parent / "baselines"
+
+
+def _check(name: str, arr: np.ndarray, update: bool) -> None:
+    from anyplotlib.tests._png_utils import decode_png, encode_png, compare_arrays
+
+    path = BASELINES / f"{name}.png"
+
+    if update:
+        BASELINES.mkdir(exist_ok=True)
+        path.write_bytes(encode_png(arr))
+        pytest.skip(f"Baseline updated: {path.name}")
+
+    if not path.exists():
+        pytest.skip(
+            f"No baseline for {name!r} — run with --update-baselines to create it"
+        )
+
+    expected = decode_png(path.read_bytes())
+    ok, msg = compare_arrays(arr, expected)
+    assert ok, f"Visual regression [{name}]: {msg}"
+
+
+def _main_fig():
+    """640×480 figure with a grayscale 64×64 imshow — the inset host."""
+    rng = np.random.default_rng(0)
+    fig, ax = apl.subplots(1, 1, figsize=(640, 480))
+    ax.imshow(rng.uniform(0.0, 1.0, (64, 64)).astype(np.float32))
+    return fig
+
+
+class TestInsetVisual:
+    """Pixel-level visual regression tests for the floating inset panel system."""
+
+    # ── single inset, normal state ─────────────────────────────────────────
+
+    def test_inset_normal_2d(self, take_screenshot, update_baselines):
+        """2-D inset in top-right corner, normal state."""
+        rng = np.random.default_rng(1)
+        fig = _main_fig()
+        inset = fig.add_inset(0.30, 0.30, corner="top-right", title="Zoom")
+        inset.imshow(rng.uniform(0.0, 1.0, (32, 32)).astype(np.float32),
+                     cmap="viridis")
+        arr = take_screenshot(fig)
+        _check("inset_normal_2d", arr, update_baselines)
+
+    def test_inset_minimized(self, take_screenshot, update_baselines):
+        """Inset collapsed to title bar only after minimize()."""
+        rng = np.random.default_rng(2)
+        fig = _main_fig()
+        inset = fig.add_inset(0.30, 0.30, corner="top-right", title="Phase")
+        inset.imshow(rng.uniform(0.0, 1.0, (32, 32)).astype(np.float32))
+        inset.minimize()
+        arr = take_screenshot(fig)
+        _check("inset_minimized", arr, update_baselines)
+
+    def test_inset_maximized(self, take_screenshot, update_baselines):
+        """Inset expanded to ~72 % of figure after maximize()."""
+        rng = np.random.default_rng(3)
+        fig = _main_fig()
+        inset = fig.add_inset(0.30, 0.30, corner="top-right", title="Detail")
+        inset.imshow(rng.uniform(0.0, 1.0, (32, 32)).astype(np.float32),
+                     cmap="inferno")
+        inset.maximize()
+        arr = take_screenshot(fig)
+        _check("inset_maximized", arr, update_baselines)
+
+    # ── two insets stacked in the same corner ──────────────────────────────
+
+    def test_inset_stacked(self, take_screenshot, update_baselines):
+        """Two insets sharing top-right corner stack with constant gap."""
+        rng = np.random.default_rng(4)
+        fig = _main_fig()
+        i1 = fig.add_inset(0.28, 0.25, corner="top-right", title="A")
+        i1.imshow(rng.uniform(0.0, 1.0, (32, 32)).astype(np.float32))
+        i2 = fig.add_inset(0.28, 0.25, corner="top-right", title="B")
+        i2.imshow(rng.uniform(0.0, 1.0, (32, 32)).astype(np.float32),
+                  cmap="hot")
+        arr = take_screenshot(fig)
+        _check("inset_stacked", arr, update_baselines)
+
+    # ── 1-D line inset ─────────────────────────────────────────────────────
+
+    def test_inset_1d(self, take_screenshot, update_baselines):
+        """1-D line plot inset in bottom-right corner."""
+        rng = np.random.default_rng(5)
+        fig = _main_fig()
+        inset = fig.add_inset(0.32, 0.22, corner="bottom-right",
+                               title="Profile")
+        t = np.linspace(0.0, 2 * np.pi, 128)
+        inset.plot(np.sin(t) + rng.normal(0, 0.05, 128),
+                   color="#4fc3f7", linewidth=1.5)
+        arr = take_screenshot(fig)
+        _check("inset_1d", arr, update_baselines)
+
+    # ── stacked with one minimized (restack test) ──────────────────────────
+
+    def test_inset_stacked_one_minimized(self, take_screenshot, update_baselines):
+        """Two insets in same corner; first minimized — second shifts up."""
+        rng = np.random.default_rng(6)
+        fig = _main_fig()
+        i1 = fig.add_inset(0.28, 0.25, corner="bottom-left", title="Min")
+        i1.imshow(rng.uniform(0.0, 1.0, (32, 32)).astype(np.float32))
+        i2 = fig.add_inset(0.28, 0.25, corner="bottom-left", title="Normal")
+        i2.imshow(rng.uniform(0.0, 1.0, (32, 32)).astype(np.float32),
+                  cmap="viridis")
+        i1.minimize()
+        arr = take_screenshot(fig)
+        _check("inset_stacked_one_minimized", arr, update_baselines)
+
+
+