Add standardized HTMX conventions, interaction patterns, and migration guide for ThrillWiki UX

backend/tests/ux/test_breadcrumbs.py

@@ -0,0 +1,193 @@
+"""
+Tests for breadcrumb utilities.
+
+These tests verify that the breadcrumb system generates
+correct navigation structures and Schema.org markup.
+"""
+
+import pytest
+from django.test import RequestFactory
+from django.urls import reverse
+
+from apps.core.utils.breadcrumbs import (
+    Breadcrumb,
+    BreadcrumbBuilder,
+    build_breadcrumb,
+)
+
+
+class TestBreadcrumb:
+    """Tests for Breadcrumb dataclass."""
+
+    def test_basic_breadcrumb(self):
+        """Should create breadcrumb with required fields."""
+        crumb = Breadcrumb(label="Home", url="/")
+        assert crumb.label == "Home"
+        assert crumb.url == "/"
+        assert crumb.icon is None
+        assert crumb.is_current is False
+
+    def test_breadcrumb_with_icon(self):
+        """Should accept icon parameter."""
+        crumb = Breadcrumb(label="Home", url="/", icon="fas fa-home")
+        assert crumb.icon == "fas fa-home"
+
+    def test_current_breadcrumb(self):
+        """Should mark breadcrumb as current."""
+        crumb = Breadcrumb(label="Current Page", is_current=True)
+        assert crumb.is_current is True
+        assert crumb.url is None
+
+    def test_schema_position(self):
+        """Should have default schema position."""
+        crumb = Breadcrumb(label="Test")
+        assert crumb.schema_position == 1
+
+
+class TestBuildBreadcrumb:
+    """Tests for build_breadcrumb helper function."""
+
+    def test_basic_breadcrumb(self):
+        """Should create breadcrumb dict with defaults."""
+        crumb = build_breadcrumb("Home", "/")
+        assert crumb["label"] == "Home"
+        assert crumb["url"] == "/"
+        assert crumb["is_current"] is False
+
+    def test_current_breadcrumb(self):
+        """Should mark as current when specified."""
+        crumb = build_breadcrumb("Current", is_current=True)
+        assert crumb["is_current"] is True
+
+    def test_breadcrumb_with_icon(self):
+        """Should include icon when specified."""
+        crumb = build_breadcrumb("Home", "/", icon="fas fa-home")
+        assert crumb["icon"] == "fas fa-home"
+
+
+class TestBreadcrumbBuilder:
+    """Tests for BreadcrumbBuilder class."""
+
+    def test_empty_builder(self):
+        """Should build empty list when no crumbs added."""
+        builder = BreadcrumbBuilder()
+        crumbs = builder.build()
+        assert crumbs == []
+
+    def test_add_home(self):
+        """Should add home breadcrumb with defaults."""
+        builder = BreadcrumbBuilder()
+        crumbs = builder.add_home().build()
+
+        assert len(crumbs) == 1
+        assert crumbs[0].label == "Home"
+        assert crumbs[0].url == "/"
+        assert crumbs[0].icon == "fas fa-home"
+
+    def test_add_home_custom(self):
+        """Should allow customizing home breadcrumb."""
+        builder = BreadcrumbBuilder()
+        crumbs = builder.add_home(
+            label="Dashboard",
+            url="/dashboard/",
+            icon="fas fa-tachometer-alt",
+        ).build()
+
+        assert crumbs[0].label == "Dashboard"
+        assert crumbs[0].url == "/dashboard/"
+        assert crumbs[0].icon == "fas fa-tachometer-alt"
+
+    def test_add_breadcrumb(self):
+        """Should add breadcrumb with label and URL."""
+        builder = BreadcrumbBuilder()
+        crumbs = builder.add("Parks", "/parks/").build()
+
+        assert len(crumbs) == 1
+        assert crumbs[0].label == "Parks"
+        assert crumbs[0].url == "/parks/"
+
+    def test_add_current(self):
+        """Should add current page breadcrumb."""
+        builder = BreadcrumbBuilder()
+        crumbs = builder.add_current("Current Page").build()
+
+        assert len(crumbs) == 1
+        assert crumbs[0].label == "Current Page"
+        assert crumbs[0].is_current is True
+        assert crumbs[0].url is None
+
+    def test_add_current_with_icon(self):
+        """Should add current page with icon."""
+        builder = BreadcrumbBuilder()
+        crumbs = builder.add_current("Settings", icon="fas fa-cog").build()
+
+        assert crumbs[0].icon == "fas fa-cog"
+
+    def test_chain_multiple_breadcrumbs(self):
+        """Should chain multiple breadcrumbs."""
+        builder = BreadcrumbBuilder()
+        crumbs = (
+            builder.add_home()
+            .add("Parks", "/parks/")
+            .add("California", "/parks/california/")
+            .add_current("Disneyland")
+            .build()
+        )
+
+        assert len(crumbs) == 4
+        assert crumbs[0].label == "Home"
+        assert crumbs[1].label == "Parks"
+        assert crumbs[2].label == "California"
+        assert crumbs[3].label == "Disneyland"
+        assert crumbs[3].is_current is True
+
+    def test_schema_positions_auto_assigned(self):
+        """Should auto-assign schema positions."""
+        builder = BreadcrumbBuilder()
+        crumbs = (
+            builder.add_home().add("Parks", "/parks/").add_current("Test").build()
+        )
+
+        assert crumbs[0].schema_position == 1
+        assert crumbs[1].schema_position == 2
+        assert crumbs[2].schema_position == 3
+
+    def test_builder_is_reusable(self):
+        """Builder should be reusable after build."""
+        builder = BreadcrumbBuilder()
+        builder.add_home()
+
+        crumbs1 = builder.build()
+        builder.add("New", "/new/")
+        crumbs2 = builder.build()
+
+        assert len(crumbs1) == 1
+        assert len(crumbs2) == 2
+
+
+class TestBreadcrumbContextProcessor:
+    """Tests for breadcrumb context processor."""
+
+    def test_empty_breadcrumbs_when_not_set(self):
+        """Should return empty list when not set on request."""
+        from apps.core.context_processors import breadcrumbs
+
+        factory = RequestFactory()
+        request = factory.get("/")
+
+        context = breadcrumbs(request)
+        assert context["breadcrumbs"] == []
+
+    def test_returns_breadcrumbs_from_request(self):
+        """Should return breadcrumbs when set on request."""
+        from apps.core.context_processors import breadcrumbs
+
+        factory = RequestFactory()
+        request = factory.get("/")
+        request.breadcrumbs = [
+            build_breadcrumb("Home", "/"),
+            build_breadcrumb("Test", is_current=True),
+        ]
+
+        context = breadcrumbs(request)
+        assert len(context["breadcrumbs"]) == 2