test(examples): exercise html-fragment path in jobs custom-form fixture (#679)

The examples/jobs JobAdmin already ships the custom-template Path B
(?run_custom=1 dual-listbox change_view + run_custom.html + the
run_with_custom_steps action). Update its docstrings/comments from the old
legacy-iframe contract to the server-rendered html-fragment contract
(rest-api 1.7.0+, #75), and add JobHtmlFragmentApiTests covering the SPA's
actual API path end-to-end against the example backend:

  - GET .../form-spec/?run_custom=1 -> renderer "html-fragment" (dual-listbox
    markup + inline <script> + csrf_token + submit_url preserved);
  - POST .../change/?run_custom=1 with no selection -> re-rendered
    html-fragment carrying the error message (PRG-to-self);
  - POST with a selection -> renderer "redirect", target mapped onto the SPA
    prefix, success message carried for toasting.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: martin-castro-laminr-ai

examples/jobs/admin.py

@@ -1,21 +1,27 @@
-"""``JobAdmin`` — the custom-form fixture that proves the legacy-iframe escape.
+"""``JobAdmin`` — the custom-form fixture that exercises the html-fragment path.
 
 This admin uses *only* documented Django ``ModelAdmin`` hooks — no
 django-admin-react / -rest-api / -mcp-specific API. The point: if this runs
-on the React admin at ``/admin-react/`` with at most a single-view iframe
-fallback, then any legacy ``/admin/`` ModelAdmin does too.
+inside the React admin shell at ``/admin2/`` with the server-rendered
+html-fragment renderer, then any legacy ``/admin/`` ModelAdmin does too.
 
 Two rendering paths:
 
-* **Path A** — ``/admin-react/jobs/job/<pk>/change/`` (no query). The stock
+* **Path A** — ``/admin2/jobs/job/<pk>/change/`` (no query). The stock
   change form, fully describable by the form-spec contract.
   ``formfield_for_dbfield`` swaps ``metadata`` to a large textarea, which
   the SPA renders natively from ``widget.kind == "textarea"``.
 * **Path B** — ``?run_custom=1``. ``change_view`` returns a hand-rolled
   dual-listbox template (not a ModelForm, not fieldsets). The form-spec
-  resolver detects the custom render and returns
-  ``{renderer: "legacy-iframe", legacy_url: …}``; the SPA embeds the legacy
-  page in an iframe inside its own chrome.
+  resolver (rest-api 1.7.0+, #75) detects the custom render, renders it
+  SERVER-SIDE, strips the admin chrome, and returns
+  ``{renderer: "html-fragment", html, csrf_token, submit_url, method,
+  messages}``. The SPA injects that HTML inside its own shell — breadcrumb /
+  sidebar / title / toolbar stay React-rendered, no iframe (#679). The
+  injected ``<form>`` POSTs back through the round-trip route, which
+  re-renders on a validation error (``messages.error`` + redirect-to-self) or
+  returns ``{renderer: "redirect", to}`` on success — surfaced as a SPA
+  ``navigate()`` plus toasts.
 """
 
 from __future__ import annotations

examples/jobs/templates/admin/jobs/job/run_custom.html

@@ -4,8 +4,12 @@
 
 This is a *pure custom template* with a custom POST contract: no ModelForm,
 no fieldsets, no model fields. The form-spec resolver detects this (the
-overridden change_view renders a non-standard template) and tells the React
-SPA to embed THIS legacy page in an iframe. The contract that must hold:
+overridden change_view renders a non-standard template), renders it
+server-side, strips the admin chrome, and hands the SPA the content-block
+HTML — including the inline <script>/<style> below — to inject INSIDE its own
+shell (no iframe, #679). The inline JS must survive into the SPA and run after
+injection (the SPA re-executes injected <script> elements). The contract that
+must hold:
 
   request.POST.getlist("selected_steps")  ← ordered, in DOM order of the
                                              right-hand column.

examples/jobs/tests/test_admin.py

@@ -1,8 +1,8 @@
 """Backend tests for the Job custom-form fixture.
 
 Exercises the legacy ``/admin/`` side of the contract — the side the React
-SPA embeds in an iframe for Path B. Pure Django ``TestCase`` + test client;
-no browser / e2e.
+SPA renders server-side as an html-fragment for Path B (#679). Pure Django
+``TestCase`` + test client; no browser / e2e.
 """
 
 from django.contrib import admin
@@ -66,3 +66,77 @@ def test_path_b_post_empty_is_rejected(self) -> None:
         # Redirects back to the same custom view with an error message.
         self.assertEqual(resp.status_code, 302)
         self.assertIn("run_custom=1", resp["Location"])
+
+
+class JobHtmlFragmentApiTests(TestCase):
+    """End-to-end exercise of the SPA's html-fragment path (#679) against the
+    example backend's REST API — the side the React SPA actually consumes.
+
+    The SPA fetches ``GET …/form-spec/?run_custom=1`` (→ ``html-fragment``)
+    and POSTs the injected form back to ``POST …/<pk>/change/?run_custom=1``
+    (→ another ``html-fragment`` on a validation error, or a ``redirect`` on
+    success, with Django ``messages`` surfaced for SPA toasts). Pure Django
+    ``TestCase`` + test client; no browser / e2e.
+    """
+
+    @classmethod
+    def setUpTestData(cls) -> None:
+        cls.user = get_user_model().objects.create_superuser(
+            username="root",
+            email="root@example.com",
+            password="x",  # noqa: S106
+        )
+        cls.job = Job.objects.create(name="nightly", status="idle")
+
+    def setUp(self) -> None:
+        self.client.force_login(self.user)
+
+    def _form_spec_url(self) -> str:
+        return f"/admin-react/api/v1/jobs/job/{self.job.pk}/form-spec/?run_custom=1"
+
+    def _change_post_url(self) -> str:
+        return f"/admin-react/api/v1/jobs/job/{self.job.pk}/change/?run_custom=1"
+
+    def test_form_spec_returns_html_fragment(self) -> None:
+        """The custom-template view resolves to a server-rendered html-fragment
+        (not the JSON form-spec, never an iframe)."""
+        resp = self.client.get(self._form_spec_url())
+        self.assertEqual(resp.status_code, 200)
+        payload = resp.json()
+        self.assertEqual(payload["renderer"], "html-fragment")
+        # The dual-listbox markup + the inline JS survive into the fragment.
+        self.assertIn('data-step="fetch"', payload["html"])
+        self.assertIn("<script>", payload["html"])
+        # The form wiring the SPA needs is present.
+        self.assertTrue(payload["csrf_token"])
+        self.assertEqual(payload["method"], "POST")
+        self.assertIn("run_custom=1", payload["submit_url"])
+
+    def test_post_empty_re_renders_fragment_with_error(self) -> None:
+        """An empty selection re-renders the fragment (the PRG-to-self idiom)
+        and carries the error message for the SPA to toast."""
+        resp = self.client.post(self._change_post_url(), data={})
+        self.assertEqual(resp.status_code, 200)
+        payload = resp.json()
+        self.assertEqual(payload["renderer"], "html-fragment")
+        self.assertTrue(
+            any(m["level"] == "error" for m in payload["messages"]),
+            payload["messages"],
+        )
+
+    def test_post_selection_redirects_to_spa(self) -> None:
+        """A valid selection redirects; the target is mapped onto the SPA prefix
+        and the success message is carried for the SPA to toast."""
+        resp = self.client.post(
+            self._change_post_url(),
+            data={"selected_steps": ["validate", "fetch"]},
+        )
+        self.assertEqual(resp.status_code, 200)
+        payload = resp.json()
+        self.assertEqual(payload["renderer"], "redirect")
+        # Mapped onto the SPA prefix (not the legacy /admin/ mount).
+        self.assertNotIn("/admin/", payload["to"])
+        self.assertTrue(
+            any("validate → fetch" in m["text"] for m in payload["messages"]),
+            payload["messages"],
+        )