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

django_admin_kit/__init__.py

@@ -0,0 +1,16 @@
+"""A pytest toolkit for writing conscious tests against the Django admin.
+
+Public names are imported from the module that defines them, such as
+``django_admin_kit.pages.AdminPage``. Nothing is re-exported here: this module runs
+at pytest startup in every project that installs the package, and importing the
+session, page or URL modules would load the admin and the browser for all of them.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("pytest-django-admin-kit")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["__version__"]

django_admin_kit/config.py

@@ -0,0 +1,205 @@
+"""Settings for the package, and the rules that reject a bad one loudly.
+
+Values come from the ``DJANGO_ADMIN_KIT`` dict in Django settings, or a default. A
+typo raises rather than being ignored, because a silently dropped key disables a
+setting invisibly and the resulting test failure points nowhere near the cause.
+
+Which browser to use, whether to show it, and how far to slow it down are not settings
+here. They belong to the pytest plugin the package drives the browser through, and
+duplicating its flags would give a project two places to say the same thing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Mapping
+
+from django.conf import settings as django_settings
+from django.core.exceptions import ImproperlyConfigured
+from django.utils.module_loading import import_string
+
+from .normalize import DEFAULTS, Rule
+
+SETTINGS_NAME = "DJANGO_ADMIN_KIT"
+
+DEFAULT_TIMEOUT = 30_000
+
+# Settings this package owns. Anything the browser plugin already governs is absent
+# on purpose; see the module docstring.
+_KNOWN_KEYS = frozenset({"locale", "normalizers", "site", "timeout", "timezone", "widgets"})
+
+
+@dataclass(frozen=True)
+class Config:
+    # A dotted path, resolved later by `urls.resolve_site`. It cannot be an
+    # AdminSite instance: settings are imported before the app registry is ready, so
+    # a project that wrote one here would fail with AppRegistryNotReady before this
+    # package saw the value.
+    site: str | None
+    timeout: int
+    timezone: str | None
+    locale: str | None
+    # The rules the project replaces, by kind, already imported. The kinds it leaves out
+    # keep their defaults.
+    normalizers: Mapping[str, Rule] = field(default_factory=dict)
+    # The project's widget classes, one instance of each, in the order they are tried.
+    widgets: tuple[Any, ...] = ()
+
+
+def _quote(values: Iterable[str]) -> str:
+    return ", ".join(repr(value) for value in values)
+
+
+def _positive_int(value: Any, key: str, minimum: int) -> int:
+    # bool is a subclass of int, so without the first check `"timeout": True` would
+    # pass as a 1ms timeout and every browser operation would fail for no visible
+    # reason.
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ImproperlyConfigured(
+            f"{SETTINGS_NAME}['{key}'] must be an integer, not {type(value).__name__}."
+        )
+    if value < minimum:
+        raise ImproperlyConfigured(f"{SETTINGS_NAME}['{key}'] must be at least {minimum}.")
+    return value
+
+
+def _rules(value: Any) -> dict[str, Rule]:
+    """The project's rules by kind, each imported from its dotted path.
+
+    A rule is named by its path, as the site is, so the settings module never imports
+    project code before the app registry is ready.
+    """
+    key = f"{SETTINGS_NAME}['normalizers']"
+    if not isinstance(value, Mapping):
+        raise ImproperlyConfigured(
+            f"{key} must be a dict of rule names to dotted paths, not {type(value).__name__}."
+        )
+    unknown = set(value) - set(DEFAULTS)
+    if unknown:
+        raise ImproperlyConfigured(
+            f"Unknown {key} rule(s): {_quote(sorted(unknown))}. "
+            f"Valid rules are: {_quote(DEFAULTS)}."
+        )
+    rules = {}
+    for name, path in value.items():
+        if not isinstance(path, str):
+            raise ImproperlyConfigured(
+                f"{key}[{name!r}] must be a dotted path to a callable, not {type(path).__name__}."
+            )
+        try:
+            rule = import_string(path)
+        except ImportError as error:
+            raise ImproperlyConfigured(
+                f"{key}[{name!r}] names {path!r}, which cannot be imported: {error}"
+            ) from error
+        if not callable(rule):
+            raise ImproperlyConfigured(f"{key}[{name!r}] names {path!r}, which is not callable.")
+        rules[name] = rule
+    return rules
+
+
+def _widgets(value: Any) -> tuple[Any, ...]:
+    """The project's widget classes, each imported from its dotted path and made once.
+
+    A class is named by its path, as a rule is, and made with no arguments, as Django
+    makes an authentication backend.
+    """
+    key = f"{SETTINGS_NAME}['widgets']"
+    if not isinstance(value, (list, tuple)):
+        raise ImproperlyConfigured(
+            f"{key} must be a list of dotted paths to widget classes, not {type(value).__name__}."
+        )
+    widgets = []
+    for index, path in enumerate(value):
+        if not isinstance(path, str):
+            raise ImproperlyConfigured(
+                f"{key}[{index}] must be a dotted path to a widget class, "
+                f"not {type(path).__name__}."
+            )
+        try:
+            widget_class = import_string(path)
+        except ImportError as error:
+            raise ImproperlyConfigured(
+                f"{key}[{index}] names {path!r}, which cannot be imported: {error}"
+            ) from error
+        if not isinstance(widget_class, type):
+            raise ImproperlyConfigured(f"{key}[{index}] names {path!r}, which is not a class.")
+        widget = widget_class()
+        for method in ("marker", "read", "fill"):
+            if not callable(getattr(widget, method, None)):
+                raise ImproperlyConfigured(
+                    f"{key}[{index}] names {path!r}, which has no {method} method."
+                )
+        # A widget class offers choices only if its widget has a fixed set of them.
+        if hasattr(widget, "choices") and not callable(widget.choices):
+            raise ImproperlyConfigured(
+                f"{key}[{index}] names {path!r}, whose choices is not a method."
+            )
+        widgets.append(widget)
+    return tuple(widgets)
+
+
+def build_config(
+    settings: Mapping[str, Any] | None = None,
+    default_timezone: str | None = None,
+    default_locale: str | None = None,
+) -> Config:
+    """Resolve the settings dict into one frozen Config."""
+    given = dict(settings or {})
+
+    unknown = set(given) - _KNOWN_KEYS
+    if unknown:
+        raise ImproperlyConfigured(
+            f"Unknown {SETTINGS_NAME} setting(s): {_quote(sorted(unknown))}. "
+            f"Valid settings are: {_quote(sorted(_KNOWN_KEYS))}."
+        )
+
+    timeout = _positive_int(given.get("timeout", DEFAULT_TIMEOUT), "timeout", minimum=1)
+
+    timezone = given.get("timezone", default_timezone)
+    if timezone is not None and not isinstance(timezone, str):
+        raise ImproperlyConfigured(
+            f"{SETTINGS_NAME}['timezone'] must be an IANA zone name or None, "
+            f"not {type(timezone).__name__}."
+        )
+
+    locale = given.get("locale", default_locale)
+    if locale is not None and not isinstance(locale, str):
+        raise ImproperlyConfigured(
+            f"{SETTINGS_NAME}['locale'] must be a language tag such as 'en-us' or None, "
+            f"not {type(locale).__name__}."
+        )
+
+    site = given.get("site")
+    if site is not None and not isinstance(site, str):
+        raise ImproperlyConfigured(
+            f"{SETTINGS_NAME}['site'] must be a dotted path to an AdminSite, "
+            f"not {type(site).__name__}."
+        )
+
+    normalizers = _rules(given.get("normalizers", {}))
+    widgets = _widgets(given.get("widgets", []))
+
+    return Config(
+        site=site,
+        timeout=timeout,
+        timezone=timezone,
+        locale=locale,
+        normalizers=normalizers,
+        widgets=widgets,
+    )
+
+
+def from_django_settings() -> Config:
+    """Build the configuration from the project's own Django settings.
+
+    The time zone defaults to the project's ``TIME_ZONE`` so that a rendered date
+    reads the same in the browser as it does in a Django template. The locale
+    defaults to ``LANGUAGE_CODE``, so a project whose admin follows the browser's
+    ``Accept-Language`` renders the same language and formats on every machine.
+    """
+    return build_config(
+        getattr(django_settings, SETTINGS_NAME, None),
+        default_timezone=getattr(django_settings, "TIME_ZONE", None),
+        default_locale=getattr(django_settings, "LANGUAGE_CODE", None),
+    )

django_admin_kit/errors.py

@@ -0,0 +1,64 @@
+"""The validation errors a create or edit form shows after the admin rejected it.
+
+The admin shows them at three levels, and each is read on its own: the summary
+notice above the form, the errors of the form as a whole, and the errors of each field.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Callable
+
+from playwright.sync_api import Locator
+
+from .rendered import text_of
+
+if TYPE_CHECKING:
+    from .fields import Fields
+
+
+class ValidationErrors:
+    """The errors a form shows, read from the page each time they are asked for.
+
+    ``form`` gives the form element and ``fields`` the form's fields; both fail when the
+    browser no longer shows the page the form is on.
+    """
+
+    def __init__(self, form: Callable[[], Locator], fields: Callable[[], Fields]) -> None:
+        self._form = form
+        self._fields = fields
+
+    @property
+    def banner(self) -> str:
+        """The notice the admin shows above a rejected form, or ``""`` when it shows none.
+
+        Its wording depends on how many errors there are, so a test that only cares that
+        the form was rejected asserts that it is there.
+        """
+        notice = self._form().locator("p.errornote")
+        return text_of(notice) if notice.count() else ""
+
+    @property
+    def non_field(self) -> list[str]:
+        """The errors of the form as a whole rather than of one field, in order.
+
+        The notice is not one of them, though the admin shows them right under it.
+        """
+        # The form's own list is a direct child of the form's one div, which leaves out
+        # the lists of the inline formsets next to it.
+        items = self._form().locator(":scope > div > ul.errorlist.nonfield > li")
+        return [text_of(item) for item in items.all()]
+
+    @property
+    def fields(self) -> dict[str, list[str]]:
+        """The errors of each field that has any, by field name, in the order the admin
+        presents the fields. One field's errors are read from it: ``field.errors``."""
+        return {name: errors for name, field in self._fields().items() if (errors := field.errors)}
+
+    def __bool__(self) -> bool:
+        return bool(self.banner or self.non_field or self.fields)
+
+    def __repr__(self) -> str:
+        return (
+            f"ValidationErrors(banner={self.banner!r}, non_field={self.non_field!r}, "
+            f"fields={self.fields!r})"
+        )

django_admin_kit/fields.py

@@ -0,0 +1,246 @@
+"""The fields of an admin form, as the page shows them.
+
+A field is addressed by its name, never by the label shown next to it. Its element is
+the box the admin draws around label, control and help text, which is the one thing
+every field has whether the user may fill it or only read it.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable, Dict
+
+from django.contrib.admin import ModelAdmin
+from django.utils import translation
+from playwright.sync_api import Locator
+
+from .normalize import Normalizers
+from .rendered import Link, RenderedValue, text_of
+
+if TYPE_CHECKING:
+    from .widgets import Widget, Widgets
+
+
+class FieldChoice:
+    """One option a field offers: its ``value``, what the form posts, and its ``label``,
+    what the user reads.
+
+    A choice compares equal to another choice and to a ``(value, label)`` pair, as a
+    tuple or a list, and to nothing else. A bare string is neither part, so a test
+    says which one it means: ``field.value.label == "Tools"``.
+    """
+
+    def __init__(self, value: str, label: str) -> None:
+        self._value = value
+        self._label = label
+
+    @property
+    def value(self) -> str:
+        return self._value
+
+    @property
+    def label(self) -> str:
+        return self._label
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, FieldChoice):
+            return (self._value, self._label) == (other._value, other._label)
+        if isinstance(other, (tuple, list)) and len(other) == 2:
+            return (self._value, self._label) == tuple(other)
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash((self._value, self._label))
+
+    def __repr__(self) -> str:
+        return f"FieldChoice({self._value!r}, {self._label!r})"
+
+
+class FormField:
+    """One field of an admin form.
+
+    ``language`` is the one the page was rendered in, which decides what the admin put
+    after the label. ``check`` is run before every read, and fails when the browser no
+    longer shows the page the field is on. ``normalizers`` read the value of a field the
+    user may only read, by what stands behind it on the page ``model_admin`` draws, and
+    ``widgets`` read and fill the field's control.
+    """
+
+    def __init__(
+        self,
+        element: Locator,
+        name: str,
+        *,
+        language: str,
+        check: Callable[[], None],
+        normalizers: Normalizers,
+        model_admin: ModelAdmin,
+        widgets: Widgets,
+    ) -> None:
+        self._element = element
+        self._name = name
+        self._language = language
+        self._check = check
+        self._normalizers = normalizers
+        self._model_admin = model_admin
+        self._widgets = widgets
+
+    @property
+    def name(self) -> str:
+        """The name the form knows the field by."""
+        return self._name
+
+    @property
+    def native(self) -> Locator:
+        """The field's box, unwrapped, for anything the package does not model."""
+        return self._element
+
+    @property
+    def required(self) -> bool:
+        """Whether the form requires a value, as the admin tells the user.
+
+        The admin marks a required field on its label, from the form field as the form
+        finally has it, so a ``ModelForm`` that changes what the model says is read the
+        way the user sees it. A field the user may only read is never required.
+        """
+        self._check()
+        return "required" in (self._label.get_attribute("class") or "").split()
+
+    @property
+    def label(self) -> str:
+        """The label the admin shows next to the field, as data and never as an address.
+
+        The suffix the form puts after every label, ``:`` in English and whatever the
+        page's language makes of it, is not part of the label and is taken off.
+        """
+        self._check()
+        label = text_of(self._label)
+        # The suffix is Django's own translated ":", so the catalog says what the page
+        # ends each label with: "Name:" in English, "Name\xa0:" in French, a full-width
+        # colon in Traditional Chinese. It is looked up in the page's language, not the
+        # test's: a project that picks the language per request renders the page in
+        # one while the test thread is in another. Collapsing the suffix as the label
+        # was collapsed turns the French "\xa0:" into ":", so "Name :" ends with it
+        # and the space left over is dropped too.
+        with translation.override(self._language):
+            suffix = " ".join(translation.gettext(":").split())
+        return label[: -len(suffix)].rstrip() if label.endswith(suffix) else label
+
+    @property
+    def editable(self) -> bool:
+        """Whether the field has a control to fill, rather than a value to read."""
+        self._check()
+        return self._element.locator("div.readonly").count() == 0
+
+    @property
+    def value(self) -> Any:
+        """What the field holds right now, as the user reads it.
+
+        A control is read by its widget class: a checkbox reads as ``True`` or
+        ``False``, a select as the ``FieldChoice`` chosen, anything else as the text
+        typed into it. A field the user may only read is read as a changelist cell is:
+        its text, or the boolean the admin drew as an icon. A control no widget class
+        recognizes raises ``LookupError``.
+        """
+        self._check()
+        if not self.editable:
+            return self._rendered.value
+        return self._widget("read").read(self)
+
+    @property
+    def links(self) -> list[Link]:
+        """The links in a rendered-only field's value, in order, like ``Cell.links``.
+
+        ``[]`` for an editable field: its value is what the control holds, and the
+        icons the admin may draw next to a select are not part of it.
+        """
+        self._check()
+        return [] if self.editable else self._rendered.links
+
+    @property
+    def errors(self) -> list[str]:
+        """The errors the admin shows for the field, in order; ``[]`` when it shows none.
+
+        A field can fail several rules at once, so this is always a list.
+        """
+        self._check()
+        items = self._element.locator("ul.errorlist > li").all()
+        # A field that shares its line with others has a box of its own. Django 4.2 to 6.0
+        # put its errors next to that box, in a wrapper around the two; the others put
+        # them inside it. The wrapper holds one field, so its list is this field's.
+        if "fieldBox" in (self._element.get_attribute("class") or "").split():
+            wrapper = self._element.locator("xpath=..")
+            items = wrapper.locator(":scope > ul.errorlist > li").all() + items
+        return [text_of(item) for item in items]
+
+    def fill(self, value: Any) -> None:
+        """Put ``value`` into the field, the way a user would.
+
+        The field's widget class fills it: a checkbox is checked or cleared by the
+        value's truth, a select is given the option that stands for the value, and every
+        other control is filled with the value's text, ``None`` emptying it. A field the
+        user may only read has nothing to fill, and a control no widget class recognizes
+        cannot be filled: both raise ``LookupError``.
+        """
+        self._check()
+        if not self.editable:
+            raise LookupError(
+                f"The field {self._name!r} is rendered only, so there is nothing to fill."
+            )
+        self._widget("fill").fill(self, value)
+
+    @property
+    def choices(self) -> list[FieldChoice]:
+        """The options a select offers, in order, the blank one included.
+
+        ``[]`` for any other field: a text input has no fixed set of options, and a
+        field the user may only read offers none.
+        """
+        self._check()
+        if not self.editable:
+            return []
+        choices = getattr(self._widgets.widget_for(self), "choices", None)
+        return [] if choices is None else choices(self)
+
+    def _widget(self, verb: str) -> Widget:
+        """The widget class that reads and fills the field. A field none of them
+        recognizes is reported at once, where waiting for a control would time out."""
+        widget = self._widgets.widget_for(self)
+        if widget is None:
+            raise LookupError(
+                f"No widget class can {verb} the field {self._name!r}. Add one for it to "
+                "DJANGO_ADMIN_KIT['widgets']."
+            )
+        return widget
+
+    @property
+    def _label(self) -> Locator:
+        # Django labels most fields with `label` and, from 6.0, a widget that groups
+        # several inputs with `legend`.
+        return self._element.locator("label, legend").first
+
+    @property
+    def _rendered(self) -> RenderedValue:
+        return RenderedValue(
+            self._element.locator("div.readonly"),
+            self._name,
+            check=self._check,
+            normalizers=self._normalizers,
+            model_admin=self._model_admin,
+        )
+
+    def __repr__(self) -> str:
+        return f"FormField({self._name!r})"
+
+
+class Fields(Dict[str, FormField]):
+    """The fields of a form by name, in the order the admin presents them.
+
+    A plain dict, so membership, ``set()`` and ``list()`` are what they always are;
+    only a miss says more than a bare ``KeyError`` would.
+    """
+
+    def __missing__(self, key: str) -> FormField:
+        raise KeyError(
+            f"The form has no field named {key!r}. Fields: "
+            f"{', '.join(repr(name) for name in self)}."
+        )