Add HtmxClient and testing assertions (Fixes #583)

[alkapandey1031986-arch]

Hello,

This PR resolves #583. It introduces an HtmxClient and HtmxTestCaseAssertions inside a new django_htmx.testing module. This eliminates the need for developers to manually build header scaffoldings to mimic HTMX requests.

A dedicated internal Pytest suite has been added and passes entirely.

[adamchainz]

Thank you for engaging on this issue. However, the value proposition here is very minimal: a client that sets hx-request to true, plus two very niche assertion methods (maybe too niche to bother using - assert response.status_code == HTMX_STOP_POLLING is clear enough, since we expose that constant). I don't think that's enough draw to ask users to switch their testing client.

I was thinking of something with more tooling to set htmx headers, like a client where all methods accept an htmx argument that can configure multiple headers succinctly, for example:

# Sets hx-request only:
response = self.client.get("/hot-dogs/", htmx=True)

# Sets hx-request and hx-target:
response = self.client.get("/hot-dogs/", htmx={"target": "#dogs"})

This is as far as my thinking has gone, as I've honestly not written many tests for htmx views myself. Have you?

[alkapandey1031986-arch]

Thanks for the feedback, really appreciate it!

You're right — the assertion helpers were too thin. I've reworked the client based on your suggestion. It now accepts an htmx kwarg directly on request methods:

python

Sets HX-Request only

response = self.client.get("/hot-dogs/", htmx=True)

Sets HX-Request + HX-Target

response = self.client.get("/hot-dogs/", htmx={"target": "#dogs"})

Multiple headers at once

response = self.client.get("/hot-dogs/", htmx={"target": "#dogs", "trigger": "click"})

The dict keys mirror the property names on HtmxDetails (target, trigger, trigger_name, prompt, boosted, current_url, history_restore_request) so they feel natural to anyone already using this library. Passing an unknown key raises a clear ValueError. Removed the assertion helpers entirely.

As for writing htmx view tests myself — not extensively, but that's honestly what motivated this. Setting headers manually every time got old fast.

Happy to adjust anything!

[adamchainz]

As for writing htmx view tests myself — not extensively, but that's honestly what motivated this. Setting headers manually every time got old fast.

Yeah, fair enough!

[alkapandey1031986-arch]

I also added a new documentation page (docs/testing.rst) to cover the HtmxClient usage at the main index. I figured a new module like this isn't much use to people if it isn't in the official docs!

I've also run the full pre-commit suite (ruff, mypy, etc.) locally to make sure everything matches your project's formatting exactly.

Ready for another look whenever you have a moment.

[adamchainz]

Rather than set HTTP_ values, we should be adding to the headers arg:

https://docs.djangoproject.com/en/6.0/topics/testing/tools/#django.test.Client.get:~:text=Keyword%20arguments%20starting%20with%20a%20HTTP%5F%20prefix%20are%20set%20as%20headers%2C%20but%20the%20headers%20parameter%20should%20be%20preferred%20for%20readability

[adamchainz]

This kind of comment isn't needed

Suggested change

# Basic: htmx=True just sets HX-Request

[adamchainz]

can you move the views and urls into tests.views and tests.urls?

[adamchainz]

use response.json() throughout the tests

alternatively, we can actually use response.wsgi_request.headers - no need for the view to echo the headers back to us!

[adamchainz]

this comment dupes the test title

Suggested change

# No htmx kwarg at all means a normal non-HTMX request

[adamchainz]

Suggested change

# Works with POST too, not just GET

[adamchainz]

Use indexing for the headers, as you expect them to be there so it's fine to raise KeyError if they're not

Suggested change

	assert headers.get("Hx-Request") == "true"
	assert headers["Hx-Request"] == "true"