pytest-django-admin-kit 1.0.0__py3-none-any.whl

django_admin_kit/plugin.py

@@ -0,0 +1,169 @@
+"""The pytest plugin: the fixtures the package adds.
+
+Registered through a ``pytest11`` entry point, so a project that installs the package
+gets them without listing anything in its own configuration. Every fixture is lazy and
+none is autouse, so a project that installs the package and never uses ``admin_ui``
+behaves exactly as it did before.
+
+The browser comes from pytest-playwright, so its flags govern admin tests too:
+``--browser``, ``--headed``, ``--slowmo`` and the rest mean here what they mean
+everywhere else in the project. That also makes each admin test carry the browser it
+ran on in its id.
+
+The fixtures are layered so one can be overridden without rewriting the rest. Point
+``admin_ui_urls`` at another ``AdminSite``, ``admin_ui_normalizers`` at other rules,
+``admin_ui_widgets`` at other widget classes, or ``admin_ui_config`` at different settings,
+and ``admin_ui`` follows.
+"""
+
+from __future__ import annotations
+
+import os
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any, Iterator, TypedDict
+
+import pytest
+
+from .config import Config, from_django_settings
+
+# The real imports happen inside the fixtures. Doing them here would add roughly 400
+# modules and 150ms to pytest startup in every project that installs the package,
+# most of it django.contrib.admin. mypy reads this block; Python never runs it.
+if TYPE_CHECKING:
+    from pytest_django.live_server_helper import LiveServer
+    from pytest_playwright.pytest_playwright import CreateContextCallback
+
+    from .normalize import Normalizers
+    from .session import AdminSession
+    from .urls import AdminUrls
+    from .widgets import Widgets
+
+
+_ASYNC_UNSAFE = "DJANGO_ALLOW_ASYNC_UNSAFE"
+
+
+class _MachineIndependentContextArgs(TypedDict, total=False):
+    """The context arguments the package sets so results do not depend on the machine."""
+
+    timezone_id: str
+    locale: str
+
+
+@contextmanager
+def _orm_allowed_while_driving() -> Iterator[None]:
+    """Let the ORM run while a browser is live, and put the guard back afterwards.
+
+    The driver's synchronous API leaves an asyncio event loop on the test thread, and
+    Django then refuses every ORM call with ``SynchronousOnlyOperation``. Logging a
+    user in needs the ORM, so the guard has to come off.
+    """
+    previous = os.environ.get(_ASYNC_UNSAFE)
+    os.environ[_ASYNC_UNSAFE] = "true"
+    try:
+        yield
+    finally:
+        if previous is None:
+            os.environ.pop(_ASYNC_UNSAFE, None)
+        else:
+            os.environ[_ASYNC_UNSAFE] = previous
+
+
+@pytest.fixture(scope="session")
+def admin_ui_config() -> Config:
+    """Settings resolved once for the whole session."""
+    return from_django_settings()
+
+
+@pytest.fixture(scope="session")
+def admin_ui_urls(admin_ui_config: Config) -> AdminUrls:
+    """URLs for the configured admin site, resolved once."""
+    # Imported here, not at module scope: this module loads at pytest startup in
+    # every project that installs the package, and `urls` pulls in the whole of
+    # django.contrib.admin.
+    from .urls import AdminUrls, resolve_site
+
+    return AdminUrls(resolve_site(admin_ui_config.site))
+
+
+@pytest.fixture(scope="session")
+def admin_ui_normalizers(admin_ui_config: Config) -> Normalizers:
+    """The rules that read rendered values: the defaults, with the ones the settings
+    replace, built once."""
+    from .normalize import Normalizers
+
+    return Normalizers(admin_ui_config.normalizers)
+
+
+@pytest.fixture(scope="session")
+def admin_ui_widgets(admin_ui_config: Config) -> Widgets:
+    """The widget classes that read and fill controls: the project's, then the package's
+    own, built once."""
+    from .widgets import Widgets
+
+    return Widgets(admin_ui_config.widgets)
+
+
+@pytest.fixture(scope="session")
+def admin_ui_driving() -> Iterator[None]:
+    """Hold Django's async guard open around everything the admin session touches.
+
+    It depends on nothing, and in particular not on ``browser``. A guard that depends
+    on the browser is torn down when the browser is, while the driver behind it is
+    still running, and dropping the test database then fails with
+    ``SynchronousOnlyOperation``. That surfaces only when the browser is torn down
+    before the end of the session, which is what a second ``--browser`` does.
+
+    Depending on nothing also lets ``admin_ui`` request it first, so it is set up
+    before the database is built and torn down after the database is destroyed.
+
+    Being a fixture rather than a session hook is what keeps it honest. A project that
+    installs the package and never asks for ``admin_ui`` never runs this, and Django's
+    guard stays where it was.
+    """
+    with _orm_allowed_while_driving():
+        yield
+
+
+@pytest.fixture
+def admin_ui(
+    # The guard comes first so it outlives the database at both ends. `live_server`
+    # before `new_context` follows Django's own practice of closing the browser before
+    # joining the live-server thread, since a held-open connection can deadlock it.
+    # Inverting it here did not reproduce a hang, so treat that half as precaution
+    # rather than a demonstrated fix.
+    admin_ui_driving: None,
+    live_server: LiveServer,
+    new_context: CreateContextCallback,
+    admin_ui_config: Config,
+    admin_ui_urls: AdminUrls,
+    admin_ui_normalizers: Normalizers,
+    admin_ui_widgets: Widgets,
+    browser_context_args: dict[str, Any],
+) -> Iterator[AdminSession]:
+    """A fresh, unauthenticated admin session per test.
+
+    Each test gets its own browsing context, which is the isolation unit for cookies
+    and storage. Sharing one would let a test that never calls ``login`` inherit the
+    previous test's user, and whether it passed would depend on file order.
+
+    The context comes from pytest-playwright's factory, so admin tests record video
+    and traces on the same flags as every other browser test in the project.
+    """
+    from .session import AdminSession
+    from .tools import PageTools
+
+    # Only pass what the project has not set itself: the factory merges its own
+    # arguments with these, and a duplicate key raises TypeError. `base_url` is
+    # deliberately absent, since AdminSession navigates absolutely.
+    context_args: _MachineIndependentContextArgs = {}
+    if admin_ui_config.timezone is not None and "timezone_id" not in browser_context_args:
+        context_args["timezone_id"] = admin_ui_config.timezone
+    if admin_ui_config.locale is not None and "locale" not in browser_context_args:
+        context_args["locale"] = admin_ui_config.locale
+
+    context = new_context(**context_args)
+    context.set_default_timeout(admin_ui_config.timeout)
+
+    # No close here: the factory closes the contexts it made when the test ends.
+    tools = PageTools(admin_ui_urls, admin_ui_normalizers, admin_ui_widgets)
+    yield AdminSession(context, tools, live_server.url)

django_admin_kit/rendered.py

@@ -0,0 +1,143 @@
+"""A value as the admin rendered it, wherever it stands: in a changelist cell or in a
+form field the user may only read.
+
+What such a value holds is read from the document's own text, so the admin's styling
+never changes it, and the links it renders are kept next to it.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable
+from urllib.parse import SplitResult, urlsplit
+
+from django.contrib.admin import ModelAdmin
+from django.contrib.admin.utils import NotRelationField, get_fields_from_path
+from django.core.exceptions import FieldDoesNotExist
+from django.db.models import Field
+from django.utils.html import strip_tags
+from playwright.sync_api import Locator
+
+if TYPE_CHECKING:
+    from .normalize import Normalizers
+
+
+class Link:
+    """One link in a rendered value: its text, and its ``href`` exactly as rendered, split.
+
+    ``href`` is a ``SplitResult``, so its parts are there by name: ``path`` to compare
+    against ``admin_ui.url``, ``query`` for what the admin added to keep a filter. A
+    link compares equal to another link and to a ``(text, href)`` pair, as a tuple or a
+    list, with ``href`` given either as a string or already split.
+    """
+
+    def __init__(self, text: str, href: str | SplitResult) -> None:
+        self._text = text
+        self._href = urlsplit(href) if isinstance(href, str) else href
+
+    @property
+    def text(self) -> str:
+        return self._text
+
+    @property
+    def href(self) -> SplitResult:
+        return self._href
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Link):
+            return (self._text, self._href) == (other._text, other._href)
+        if isinstance(other, (tuple, list)) and len(other) == 2:
+            text, href = other
+            if isinstance(text, str) and isinstance(href, (str, SplitResult)):
+                return self == Link(text, href)
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash((self._text, self._href))
+
+    def __repr__(self) -> str:
+        return f"Link({self._text!r}, {self._href.geturl()!r})"
+
+
+class RenderedValue:
+    """One value the admin rendered, read from the element that holds it.
+
+    ``check`` is run before every read, and fails when the browser no longer shows the
+    page the value is on. ``normalizers`` read its value, by what stands behind it: the
+    ``name`` the admin renders it under, on a page ``model_admin`` draws.
+    """
+
+    def __init__(
+        self,
+        element: Locator,
+        name: str,
+        *,
+        check: Callable[[], None],
+        normalizers: Normalizers,
+        model_admin: ModelAdmin,
+    ) -> None:
+        self._element = element
+        self._name = name
+        self._check = check
+        self._normalizers = normalizers
+        self._model_admin = model_admin
+
+    @property
+    def native(self) -> Locator:
+        """The element, unwrapped, for anything the package does not model."""
+        return self._element
+
+    @property
+    def field(self) -> Field | None:
+        """The model field the admin rendered the value from, or ``None``, as for a method."""
+        return _model_field(self._model_admin.model, self._name)
+
+    @property
+    def empty_display(self) -> str:
+        """The text the admin shows here for a value it has none of: the model admin's, which
+        falls back to the site's."""
+        return display_text(self._model_admin.get_empty_value_display())
+
+    @property
+    def text(self) -> str:
+        """What the document shows, with its whitespace collapsed."""
+        self._check()
+        return text_of(self._element)
+
+    @property
+    def value(self) -> Any:
+        """What is shown, read by the rule for its kind: by default the text, or a boolean
+        where the admin drew one as an icon."""
+        self._check()
+        return self._normalizers.read(self)
+
+    @property
+    def links(self) -> list[Link]:
+        """The links rendered, in order; ``[]`` when there is none."""
+        self._check()
+        return [
+            Link(text_of(a), a.get_attribute("href") or "")
+            for a in self._element.locator("a[href]").all()
+        ]
+
+
+def text_of(element: Locator) -> str:
+    """The document's text inside ``element``, with its whitespace collapsed."""
+    return " ".join((element.text_content() or "").split())
+
+
+def display_text(display: str) -> str:
+    """``display`` as the page shows it: without markup, its whitespace collapsed."""
+    return " ".join(strip_tags(str(display)).split())
+
+
+def _model_field(model: type[Any], name: str) -> Field | None:
+    """The model field the admin renders under ``name``, or ``None`` when it renders something
+    else there, such as a method.
+
+    The admin looks a name up as a field first, following a path such as ``category__name``,
+    and only then as a callable or a method, so a name that is a field is always that field.
+    """
+    try:
+        return get_fields_from_path(model, name)[-1]
+    except (FieldDoesNotExist, NotRelationField):
+        return None

django_admin_kit/results.py

@@ -0,0 +1,62 @@
+"""The outcome of submitting an admin form.
+
+A result says whether the admin accepted the submission and where it sent the browser.
+Anything shown on the page, such as fields, errors and messages, is read from
+``result.page``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .pages import AdminPage
+    from .urls import AdminUrls
+
+
+class SubmissionResult:
+    """The outcome of one form submission."""
+
+    def __init__(self, page: AdminPage, redirected: bool, urls: AdminUrls) -> None:
+        self._page = page
+        self._redirected = redirected
+        self._urls = urls
+
+    @property
+    def page(self) -> AdminPage:
+        """The page the browser shows after the submission.
+
+        It is the submitted page object itself if the browser stayed on that page, and a
+        new page object otherwise.
+        """
+        return self._page
+
+    @property
+    def success(self) -> bool:
+        """Whether the admin accepted the submission.
+
+        Django redirects after a successful save and shows the form again when it rejects
+        one, so this is whether a redirect happened.
+        """
+        return self._redirected
+
+    def redirected_to(self, url: str) -> bool:
+        """Whether the admin redirected the browser to ``url``, a path such as
+        ``admin_ui.url.list(Product)``.
+
+        A rejected form is shown again at its own URL without a redirect, so it is never
+        redirected to that URL.
+        """
+        return self._redirected and self._page.destination == url
+
+    def redirected_to_index(self) -> bool:
+        return self.redirected_to(self._urls.index())
+
+    def redirected_to_list(self, model: type[Any]) -> bool:
+        return self.redirected_to(self._urls.list(model))
+
+    def redirected_to_create(self, model: type[Any]) -> bool:
+        return self.redirected_to(self._urls.create(model))
+
+    def redirected_to_edit(self, instance: Any) -> bool:
+        return self.redirected_to(self._urls.edit(instance))

django_admin_kit/rows.py

@@ -0,0 +1,165 @@
+"""The rows of a changelist and the cells in them.
+
+A cell is addressed by the name its column is configured with, never by the label
+shown over it, and a row by its position. A cell is a rendered value, as the
+``rendered`` module reads one, that also knows its column.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Iterator
+
+from django.contrib.admin import ModelAdmin
+from django.contrib.admin.utils import unquote
+from django.db.models import Model
+from django.urls import Resolver404, resolve
+from playwright.sync_api import Locator
+
+from .normalize import Normalizers
+from .rendered import RenderedValue, display_text
+from .urls import AdminUrls, model_admin
+
+
+class Cell(RenderedValue):
+    """One cell of a changelist row."""
+
+    def __init__(
+        self,
+        element: Locator,
+        column: str,
+        *,
+        check: Callable[[], None],
+        normalizers: Normalizers,
+        model_admin: ModelAdmin,
+    ) -> None:
+        super().__init__(
+            element, column, check=check, normalizers=normalizers, model_admin=model_admin
+        )
+        self._column = column
+
+    @property
+    def column(self) -> str:
+        """The configured name of the column the cell is in."""
+        return self._column
+
+    @property
+    def empty_display(self) -> str:
+        """The text the admin shows here for a value it has none of: the column's own, when
+        it is a method or a callable that sets one, else the model admin's or the site's."""
+        function = None if self.field is not None else self._display_function()
+        if function is not None and hasattr(function, "empty_value_display"):
+            return display_text(function.empty_value_display)
+        return super().empty_display
+
+    def _display_function(self) -> Any:
+        """What the admin calls to render the column, looked up as the admin looks it up: a
+        callable in ``list_display``, then the model admin's attribute, then the model's."""
+        for entry in self._model_admin.list_display:
+            if callable(entry) and getattr(entry, "__name__", None) == self._column:
+                return entry
+        if hasattr(self._model_admin, self._column):
+            return getattr(self._model_admin, self._column)
+        return getattr(self._model_admin.model, self._column, None)
+
+
+class Row:
+    """One row of a changelist, indexable by column name or position.
+
+    The columns are the ones the changelist had when the row was read. A project whose
+    ``list_display`` changes with the query string reads its rows again after filtering.
+    """
+
+    def __init__(
+        self,
+        element: Locator,
+        index: int,
+        *,
+        columns: list[str],
+        model: type[Model],
+        urls: AdminUrls,
+        check: Callable[[], None],
+        normalizers: Normalizers,
+    ) -> None:
+        self._element = element
+        self._index = index
+        self._columns = columns
+        self._model = model
+        self._urls = urls
+        self._check = check
+        self._normalizers = normalizers
+
+    @property
+    def index(self) -> int:
+        """The row's 0-based position in the changelist.
+
+        The row is that position, not a record: every read goes to whichever row the page
+        shows there now, so once the changelist is filtered or sorted it may be another one.
+        """
+        return self._index
+
+    @property
+    def native(self) -> Locator:
+        """The row element, unwrapped, for anything the package does not model."""
+        return self._element
+
+    @property
+    def object(self) -> Any:
+        """The instance behind the row, where the changelist links to its change page.
+
+        ``None`` for a row without such a link, as under ``list_display_links = None``.
+        The database is asked each time, so the instance is as it is stored now.
+        """
+        opts = self._model._meta
+        for cell in self._cells:
+            for link in cell.links:
+                try:
+                    match = resolve(link.href.path)
+                except Resolver404:
+                    continue
+                if (
+                    match.namespace == self._urls.site.name
+                    and match.url_name == f"{opts.app_label}_{opts.model_name}_change"
+                ):
+                    return self._model._default_manager.get(pk=unquote(match.kwargs["object_id"]))
+        return None
+
+    def __len__(self) -> int:
+        return len(self._cells)
+
+    def __iter__(self) -> Iterator[Cell]:
+        return iter(self._cells)
+
+    def __getitem__(self, key: int | str) -> Cell:
+        if isinstance(key, int):
+            return self._cells[key]
+        try:
+            return self._cells[self._columns.index(key)]
+        except ValueError:
+            raise KeyError(
+                f"The row has no column named {key!r}. Columns: "
+                f"{', '.join(repr(name) for name in self._columns)}."
+            ) from None
+
+    @property
+    def _cells(self) -> list[Cell]:
+        self._check()
+        # The row's own cells line up with the columns by position once the
+        # checkbox Django adds for actions is skipped, as the headers skip its
+        # header cell.
+        cells = self._element.locator(":scope > th, :scope > td").all()
+        cells = [cell for cell in cells if "action-checkbox" not in _classes(cell)]
+        admin = model_admin(self._urls.site, self._model)
+        return [
+            Cell(
+                cell,
+                column,
+                check=self._check,
+                normalizers=self._normalizers,
+                model_admin=admin,
+            )
+            for cell, column in zip(cells, self._columns)
+        ]
+
+
+def _classes(element: Locator) -> list[str]:
+    return (element.get_attribute("class") or "").split()

django_admin_kit/session.py

@@ -0,0 +1,132 @@
+"""The object the ``admin_ui`` fixture yields.
+
+Login builds the session in Django and hands the browser the resulting cookie. It
+never types a password, because passwords are stored irreversibly and a test handed an
+arbitrary user has no way to know one. A user created with ``set_unusable_password()``
+has no password at all and must still be able to log in.
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar
+from urllib.parse import urljoin
+
+from django.conf import settings
+from django.test import Client
+from playwright.sync_api import BrowserContext
+
+from .pages import AdminPage, ChangelistPage, CreatePage, DeletePage, EditPage, IndexPage
+from .tools import PageTools
+from .urls import AdminUrls
+
+_P = TypeVar("_P", bound=AdminPage)
+
+
+class AdminSession:
+    """One test's view of the admin: who is logged in, and where things live."""
+
+    def __init__(
+        self,
+        context: BrowserContext,
+        tools: PageTools,
+        base_url: str,
+    ) -> None:
+        self._context = context
+        self._tools = tools
+        self._base_url = base_url
+
+    @property
+    def native(self) -> BrowserContext:
+        """The browsing context, unwrapped, for anything the package does not model."""
+        return self._context
+
+    @property
+    def url(self) -> AdminUrls:
+        """Admin URLs resolved through the site under test, as paths."""
+        return self._tools.urls
+
+    def absolute(self, path: str) -> str:
+        """Turn an admin path into a full URL on the live server.
+
+        The package navigates absolutely rather than setting the context's
+        ``base_url``, which belongs to the project: a test suite already using
+        ``--base-url`` for its own pages keeps it, and neither of us can break the
+        other.
+        """
+        return urljoin(self._base_url, path)
+
+    def login(self, user: Any, password: str | None = None) -> None:
+        """Log in as ``user`` without knowing or needing a password.
+
+        Calling it again replaces the session rather than adding a second one, so
+        switching users mid-test works.
+
+        With ``password``, the rendered login form is driven instead: the browser
+        opens the login page, types what the user model identifies users by and the
+        password, and submits. That is for tests whose subject is the login page. A
+        wrong password leaves the browser on the form, with its error shown, and the
+        session anonymous.
+        """
+        self.logout()
+
+        if password is None:
+            self._login_with_cookie(user)
+        else:
+            self._login_with_form(user, password)
+
+    def _login_with_cookie(self, user: Any) -> None:
+        client = Client()
+        client.force_login(user)
+
+        name = settings.SESSION_COOKIE_NAME
+        self._context.add_cookies(
+            [{"name": name, "value": client.cookies[name].value, "url": self._base_url}]
+        )
+
+    def _login_with_form(self, user: Any, password: str) -> None:
+        page = self._context.new_page()
+        page.goto(self.absolute(self._tools.urls.login()))
+
+        # The admin's form names the identity input `username` whatever the user
+        # model calls the field; only the value it expects follows the model.
+        page.locator('input[name="username"]').fill(user.get_username())
+        page.locator('input[name="password"]').fill(password)
+        with page.expect_response(lambda response: response.request.method == "POST"):
+            page.locator('input[type="submit"]').click()
+        page.wait_for_load_state()
+
+    def logout(self) -> None:
+        """Return the browser to anonymous by dropping its cookies."""
+        self._context.clear_cookies()
+
+    def open(self, path: str) -> AdminPage:
+        """Open any admin path in a new page, including views the package does not
+        model, and report how it went."""
+        return self._open(path, AdminPage)
+
+    def index(self) -> IndexPage:
+        """Open the admin index."""
+        return self._open(self._tools.urls.index(), IndexPage)
+
+    def list(self, model: type[Any]) -> ChangelistPage:
+        """Open a model's changelist."""
+        return self._open(self._tools.urls.list(model), ChangelistPage, model)
+
+    def create(self, model: type[Any]) -> CreatePage:
+        """Open the page that adds a new instance of ``model``."""
+        return self._open(self._tools.urls.create(model), CreatePage, model)
+
+    def edit(self, instance: Any) -> EditPage:
+        """Open the change page of ``instance``."""
+        return self._open(self._tools.urls.edit(instance), EditPage, type(instance))
+
+    def delete(self, instance: Any) -> DeletePage:
+        """Open the page that asks whether to delete ``instance``."""
+        return self._open(self._tools.urls.delete(instance), DeletePage, type(instance))
+
+    def _open(self, path: str, page_class: type[_P], *args: Any) -> _P:
+        page = self._context.new_page()
+        response = page.goto(self.absolute(path))
+        # `goto` returns None only for same-document navigations, never for a URL.
+        assert response is not None
+        return page_class(page, response.status, path, self._tools, *args)