Tutorial: Test a LiveView with LiveViewTestClient

Most LiveView bugs are state-transition bugs: the user clicked the button but the right state var didn't change, or it changed but the template branch didn't update. The fastest feedback loop for those bugs is a unit test that mounts the view, fires events, and asserts on state — no Selenium, no Playwright, no test browser.

djust ships LiveViewTestClient for exactly this. It instantiates the view, calls mount(), and invokes handlers directly. Same code path as the production WebSocket consumer minus the transport layer. Tests run in tens of milliseconds, are deterministic, and fail with clean tracebacks pointing at the line in your view.

By the end of this tutorial you'll have:

• A test for a counter view — mount, fire events, assert state.
• A test for a form view with validation — including the failure path (empty submission → error message).
• A test for page-level auth (anonymous user hits an auth-gated view → 302 to /login/).
• A test for a pushed event (server tells the client to show a flash toast).
• A pattern for testing a LiveComponent in isolation, mounted without its parent.

Prerequisites: Installation, pytest with pytest-django configured, and one of the earlier tutorials so you have a view worth testing. The examples below use the search-as-you-type view as the running case.

What this client gives you (and what it doesn't)

The LiveViewTestClient is a server-side test harness. It runs:

• mount(request, **params) — the view's own mount(). Page-level auth (login_required, get_object() / has_object_permission()) is not applied here; see Step 4.
• Each @event_handler you send_event for.
• Template rendering (when you call client.render()).
• All assertions are against self.* attrs after the handler runs.

It does NOT run:

• The WebSocket transport (no real frames; no LiveViewConsumer).
• The client-side JS runtime (no dj-debounce timer, no dj-loading.* class application — those are client-only).
• Real DOM mounting / patching (no JSDOM, no IntersectionObserver).

Use this client for logic tests — does the handler change the state correctly? Does the template render the right text for the right state? Use a real-browser tool (Playwright, Selenium) for transport tests — does the WebSocket actually reconnect after a flap? Does dj-debounce cancel the timer correctly? Most teams need 100 of the former for every 1 of the latter.

Step 1 — Test the search-as-you-type view's happy path

Recall the view from tutorial #1:

class SearchView(LiveView):
    template_name = "search.html"

    query = state("")
    results = state(default_factory=list)
    error = state("")

    @event_handler
    def search(self, value: str = "", **kwargs):
        self.query = value
        self.error = ""
        q = value.strip()
        if not q:
            self.results = []
            return
        # ... query DB ...
        self.results = [{"id": d.id, "title": d.title} for d in qs]

The simplest possible test:

# tests/test_search_view.py
import pytest
from djust.testing import LiveViewTestClient

from myapp.models import Document
from myapp.views import SearchView


@pytest.mark.django_db
def test_typing_a_query_populates_results():
    Document.objects.create(title="Indexing strategies for Postgres")
    Document.objects.create(title="Why we picked Rust")
    Document.objects.create(title="Postgres tuning notes")

    client = LiveViewTestClient(SearchView).mount()
    client.send_event("search", value="postgres")

    state = client.get_state()
    assert state["query"] == "postgres"
    assert len(state["results"]) == 2
    titles = [r["title"] for r in state["results"]]
    assert "Indexing strategies for Postgres" in titles
    assert "Postgres tuning notes" in titles


@pytest.mark.django_db
def test_empty_query_clears_results():
    Document.objects.create(title="Anything")

    client = LiveViewTestClient(SearchView).mount()
    client.send_event("search", value="anything")
    assert len(client.get_state()["results"]) == 1

    client.send_event("search", value="")
    state = client.get_state()
    assert state["results"] == []
    assert state["query"] == ""

Two patterns:

Note the @pytest.mark.django_db — needed because the view talks to the DB. Without the marker, the test runs against an empty in-memory DB and Document.objects.create would fail.

Step 2 — Test the failure path

The search view's handler swallows errors and writes them to self.error. Test the path:

@pytest.mark.django_db
def test_search_handles_db_error_gracefully(monkeypatch):
    def boom(*args, **kwargs):
        raise RuntimeError("connection lost")

    monkeypatch.setattr(
        "myapp.views.Document.objects.filter",
        boom,
    )

    client = LiveViewTestClient(SearchView).mount()
    client.send_event("search", value="anything")

    state = client.get_state()
    assert state["results"] == []
    assert state["error"]  # the user sees a message...
    assert "connection lost" not in state["error"]  # ...but not the raw error

The monkeypatch fixture is pytest's standard way to swap a callable inline; here we make Document.objects.filter raise unconditionally and confirm the handler catches the error, sets self.error, and keeps the exception text out of it (the view logs it instead).

Step 3 — Test a pushed event (flash toast)

If the view fires self.push_event("flash", {...}), the test client captures it:

class CommentView(LiveView):
    @event_handler
    def post(self, body: str = "", **kwargs):
        if not body.strip():
            self.push_event("flash", {"type": "error", "message": "Empty comment"})
            return
        # ... save ...
        self.push_event("flash", {"type": "success", "message": "Posted!"})


@pytest.mark.django_db
def test_empty_comment_pushes_error_flash():
    client = LiveViewTestClient(CommentView).mount()
    client.send_event("post", body="")

    client.assert_push_event("flash", {"type": "error", "message": "Empty comment"})

assert_push_event passes when any event queued since mount() has that name and a payload containing the given keys (a subset match, so later payload additions don't break the test). The queue is not cleared between send_event calls; to check exactly what one handler pushed, use a fresh client.

Step 4 — Test page-level auth

LiveViewTestClient.mount() calls your mount() directly, so it does not apply login_required or the get_object() / has_object_permission() check. Test those through the page load with Django's test client (pytest-django's client fixture). The auth-gated team admin from the authentication tutorial sends anonymous visitors to /login/ and answers 403 to a signed-in non-member:

import pytest

from myapp.models import Team


@pytest.mark.django_db
def test_anonymous_user_redirects_to_login(client):
    response = client.get("/teams/1/")
    assert response.status_code == 302
    assert response.url.startswith("/login/?next=")


@pytest.mark.django_db
def test_non_member_is_refused(client, django_user_model):
    user = django_user_model.objects.create_user(username="alice", password="pw")
    Team.objects.create(id=1, name="The Team")
    client.force_login(user)

    response = client.get("/teams/1/")
    assert response.status_code == 403  # not a member of team 1

Once the page-level matrix is covered, use LiveViewTestClient's user= kwarg for handler logic that depends on who is signed in: LiveViewTestClient(TeamAdminView, user=user).mount(team_id=1) sets request.user for the lifecycle (without it, the request has AnonymousUser). client.assert_redirect("/teams/") checks that a handler called self.live_redirect("/teams/").

Step 5 — Test the rendered HTML, not just state

Sometimes the bug is in the template, not the handler. State asserts pass; the user still sees the wrong thing. Use client.render() for HTML-level assertions:

@pytest.mark.django_db
def test_results_render_with_titles():
    Document.objects.create(title="Indexing strategies")
    Document.objects.create(title="Why we picked Rust")

    client = LiveViewTestClient(SearchView).mount()
    client.send_event("search", value="indexing")

    html = client.render()
    assert "Indexing strategies" in html
    assert "Why we picked Rust" not in html
    # Check the empty-state isn't shown when we have results
    assert "Type to search" not in html

Don't reach for client.render() for every test — it's slower than assert_state and couples the test to template markup. Use it when the bug class is "the conditional template branch picked the wrong arm" or "the format string lost a variable."

Step 6 — Test a LiveComponent in isolation

The StarRating component from the LiveComponent tutorial can be tested without its parent:

from djust.testing import LiveComponentTestClient

from myapp.components.star_rating import StarRating


def test_hover_changes_hover_state_only():
    client = LiveComponentTestClient(StarRating).mount(value=3, max=5)
    assert client.get_state()["hover"] == 0

    client.send_event("hover_star", n=4)
    state = client.get_state()
    assert state["hover"] == 4
    assert state["value"] == 3  # value untouched


def test_commit_rating_bubbles_to_parent():
    client = LiveComponentTestClient(StarRating).mount(value=3)
    sent = []
    client.component._set_parent_callback(sent.append)  # stand-in parent

    client.send_event("commit_rating", n=5)

    assert client.get_state()["value"] == 5
    assert sent[-1]["event"] == "rating_changed"
    assert sent[-1]["data"] == {"value": 5}

send_parent() calls whatever callback the parent registered; with no parent it does nothing. Registering a list's append as the callback captures the bubble-up, so you don't need a real parent view in the test. LiveComponentTestClient calls the component's methods directly and does not enforce @event_handler; for full integration (parent + component), mount the parent with LiveViewTestClient.

Beyond logic tests: when to reach for a real browser

The test client doesn't simulate the client runtime. Tests that depend on the runtime need a real browser (Playwright is standard):

The 100:1 ratio holds: most of your bug surface is in handler logic and template branches. Cover that with the test client. Reserve the slow real-browser tests for the few features whose correctness genuinely depends on the transport or runtime.

Where to go next

• Snapshot testing: mix in SnapshotTestMixin (Testing guide) to assert on rendered HTML diffs, not just substrings. Catches accidental template regressions the substring asserts would miss.
• Smoke test the whole site: LiveViewSmokeTest discovers every LiveView (or one app's, with app_label), mounts and renders each, and fuzzes their handlers. Catches "I changed an import and now half the views 500" before deploying.
• Time-travel debugging in tests: time-travel branches live in memory only; to keep one as a regression test, reproduce its event sequence with send_event. See the time-travel guide.
• CI integration: point pytest at tests/ in your CI config; the test client doesn't need any special setup beyond what pytest-django already provides.

The four-line shape of a test (mount → send_event → assert_state or assert_push_event) is the entire surface for ~95% of LiveView tests. Start there; reach for real-browser tests only when you've proven you need them.