Testing Utilities¶

This section covers test assertions for verifying navigation parity and HTML fragment composition across HTMX and full-page request pathways.

Testing Reference (`htmx_nav.testing`)¶

Testing utilities for django-htmx-nav.

Provides assertion helpers for Django and HTMX test suites to verify navigation parity and HTML fragment composition.

htmx_nav.testing.assert_html_equal(a, b, *, label_a='a', label_b='b')[source]¶

Assert that two HTML documents or fragments are structurally equal.

Normalizes whitespace and attribute ordering using Django’s parse_html and strips debug marker scripts before comparing.

Parameters:

a (bytes | str) – First HTML document or fragment.
b (bytes | str) – Second HTML document or fragment.
label_a (str) – Label for a in unified diff output. Defaults to “a”.
label_b (str) – Label for b in unified diff output. Defaults to “b”.

Raises:

AssertionError – If the two documents differ structurally, including a unified diff.

Example

assert_html_equal(response.content, "<div id='main'>Hello</div>")

htmx_nav.testing.assert_shell_composition(client, url, *, page_shell_kwargs, tab_shell_kwargs, full_reload_kwargs=None, page_container_id='page-content', tab_container_id='tab-content', self_wrapped=False)[source]¶

Assert that full-page reloads and HTMX swap responses compose identical HTML.

Performs requests across three interaction tiers (full page reload, page-level shell swap, and tab/component swap) and verifies that HTML fragments nest and match structurally without state drift.

Parameters:

client (Client) – The Django test client instance.
url (str) – The target endpoint URL.
page_shell_kwargs (dict[str, Any]) – Kwargs for client.get representing a page-level swap.
tab_shell_kwargs (dict[str, Any]) – Kwargs for client.get representing a tab-level swap.
full_reload_kwargs (dict[str, Any] | None) – Optional kwargs for a standard browser GET. Defaults to {}.
page_container_id (str) – DOM element ID targeted by page-level swaps. Defaults to “page-content”.
tab_container_id (str) – DOM element ID targeted by tab-level swaps. Defaults to “tab-content”.
self_wrapped (bool) – Set to True if swap responses re-emit their outer container tag (hx-swap="outerHTML"). Defaults to False.

Return type:

dict[str, Any]

Returns:

Mapping containing "full_reload", "page_shell", and "tab_shell" response objects.

Raises:

AssertionError – If any response status is not 200, a container ID is missing, or fragment markup diverges.
ImportError – If beautifulsoup4 is not installed.

Example

responses = assert_shell_composition(
    client,
    "/projects/1/",
    page_shell_kwargs={"HTTP_HX_REQUEST": "true", "HTTP_HX_TARGET": "page-content"},
    tab_shell_kwargs={"HTTP_HX_REQUEST": "true", "HTTP_HX_TARGET": "tab-content"},
    page_container_id="page-content",
    tab_container_id="tab-content",
)

htmx_nav.testing.assert_shell_parity(client, url, *, requests, checks)[source]¶

Assert that template context remains consistent across request modes.

Issues GET requests for each scenario in requests and executes extraction callbacks against response contexts to verify shell state parity (e.g. active links, breadcrumbs, sidebar items).

Parameters:

client (Client) – The Django test client instance.
url (str) – The target URL to request.
requests (dict[str, dict[str, Any]]) – Mapping of scenario labels to kwargs passed to client.get.
checks (dict[str, Callable[[Any], Any]]) – Mapping of check labels to extraction functions receiving response.context.

Return type:

dict[str, Any]

Returns:

Mapping of scenario labels to their Django response objects.

Raises:

AssertionError – If any check produces a value that differs from the baseline established by the first request.

Example

requests = {
    "full_reload": {},
    "page_shell": {"HTTP_HX_REQUEST": "true", "HTTP_HX_TARGET": "page-content"},
}
checks = {
    "active_tab": lambda ctx: ctx["active_tab"],
    "breadcrumbs": lambda ctx: [c["label"] for c in ctx["nav"]["breadcrumbs"]],
}
responses = assert_shell_parity(
    client, "/dashboard/", requests=requests, checks=checks
)

Testing Utilities¶

Testing Reference (htmx_nav.testing)¶

Testing Reference (`htmx_nav.testing`)¶