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

django_admin_kit/matching.py

@@ -0,0 +1,178 @@
+"""Matching changelist rows against patterns, and saying what did not match.
+
+A failed match raises ``AssertionError`` carrying the expected pattern and the rows
+actually shown, so that a test reads the whole picture under the line that failed, the
+way any assertion helper reports.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Sequence
+from urllib.parse import SplitResult
+
+from .rendered import Link
+from .rows import Cell, Row
+
+
+class _Named:
+    """A value that prints as its name: a sentinel, or a callable shown in a failure."""
+
+    def __init__(self, name: str) -> None:
+        self._name = name
+
+    def __repr__(self) -> str:
+        return self._name
+
+
+ANY = _Named("ANY")
+"""A cell pattern any cell matches: the cell must exist, its contents do not matter."""
+
+ANY_ROW = _Named("ANY_ROW")
+"""A row pattern any row matches."""
+
+
+def matches(pattern: Any, row: Row) -> bool:
+    """Whether one row pattern describes ``row``: ``ANY_ROW``, a cell pattern per
+    column, or cell patterns by column name, the columns left out unconstrained."""
+    if pattern is ANY_ROW:
+        return True
+    if isinstance(pattern, dict):
+        # An unknown name raises from the row, naming its columns: a misspelt
+        # column is a mistake to see, not a row that happens not to match.
+        return all(_cell_matches(expected, row, row[name]) for name, expected in pattern.items())
+    return len(pattern) == len(row) and all(
+        _cell_matches(expected, row, cell) for expected, cell in zip(pattern, row)
+    )
+
+
+def _cell_matches(expected: Any, row: Row, cell: Cell) -> bool:
+    if expected is ANY:
+        return True
+    if callable(expected):
+        # The test's own code: whatever it raises is its own bug to see.
+        return bool(expected(row, cell))
+    # A pattern describes the cell's links or its value, whichever it equals: one link
+    # as the cell's only link, a list or tuple of links as all of them. Nothing is read
+    # into a pattern's shape, so a project whose own rule puts links into the value
+    # matches them the same way.
+    if cell.links == [expected]:
+        return True
+    if isinstance(expected, (tuple, list)) and cell.links == list(expected):
+        return True
+    # `==` may return something other than a bool for an arbitrary value; only its
+    # truth decides the match.
+    return bool(expected == cell.value)
+
+
+def contains(pattern: Any, rows: Sequence[Row]) -> bool:
+    """``True`` when some row matches ``pattern``; otherwise the failure, raised."""
+    __tracebackhide__ = True
+    if any(matches(pattern, row) for row in rows):
+        return True
+    raise AssertionError(_no_match(pattern, rows))
+
+
+def match(patterns: Any, rows: Sequence[Row]) -> bool:
+    """``True`` when the rows are exactly ``patterns``, one row per pattern in order;
+    otherwise the failure, raised."""
+    __tracebackhide__ = True
+    if not isinstance(patterns, (tuple, list)):
+        raise TypeError(
+            "match() takes a list or tuple of row patterns, one per row of the changelist; "
+            f"got {patterns!r}. A single row is written as [row]."
+        )
+    if len(patterns) != len(rows):
+        raise AssertionError(_wrong_count(patterns, rows))
+    wrong = [
+        index
+        for index, (pattern, row) in enumerate(zip(patterns, rows))
+        if not matches(pattern, row)
+    ]
+    if wrong:
+        raise AssertionError(_wrong_rows(patterns, wrong, rows))
+    return True
+
+
+def _no_match(pattern: Any, rows: Sequence[Row]) -> str:
+    expected = f"    {_described(pattern)!r}"
+    lines = ["Expected row:", expected, "", "No matching row found.", "", "Actual rows:"]
+    return "\n".join(lines + _shown_rows(rows, pattern))
+
+
+def _wrong_count(patterns: Sequence[Any], rows: Sequence[Row]) -> str:
+    lines = ["Expected rows:", *_described_rows(patterns), ""]
+    lines.append(f"Expected {_count(len(patterns))}, found {len(rows)}.")
+    return "\n".join([*lines, "", "Actual rows:", *_shown_rows(rows, None)])
+
+
+def _wrong_rows(patterns: Sequence[Any], wrong: list[int], rows: Sequence[Row]) -> str:
+    lines = ["Expected rows:", *_described_rows(patterns)]
+    for index in wrong:
+        lines += ["", f"Row {index} did not match:"]
+        lines.append(f"    expected {_described(patterns[index])!r}")
+        lines.append(f"    actual   {_shown(rows[index], patterns[index])!r}")
+    return "\n".join([*lines, "", "Actual rows:", *_shown_rows(rows, None)])
+
+
+def _count(number: int) -> str:
+    return f"{number} row" if number == 1 else f"{number} rows"
+
+
+def _described_rows(patterns: Sequence[Any]) -> list[str]:
+    return [f"    {_described(pattern)!r}" for pattern in patterns] or ["    (none)"]
+
+
+def _shown_rows(rows: Sequence[Row], pattern: Any) -> list[str]:
+    return [f"    {_shown(row, pattern)!r}" for row in rows] or ["    (none)"]
+
+
+def _described(pattern: Any) -> Any:
+    # A callable prints as its name, since its repr says nothing a reader can use.
+    if isinstance(pattern, dict):
+        return {name: _described_cell(item) for name, item in pattern.items()}
+    if isinstance(pattern, (tuple, list)):
+        return type(pattern)(_described_cell(item) for item in pattern)
+    return pattern
+
+
+def _described_cell(expected: Any) -> Any:
+    if callable(expected):
+        return _Named(getattr(expected, "__name__", repr(expected)))
+    return expected
+
+
+def _shown(row: Row, pattern: Any) -> Any:
+    # A row is shown the way the pattern addressed it: as its values in order, or by
+    # the columns the pattern named; where the pattern asked about links, the cell's
+    # links are shown instead, so the two line up.
+    if isinstance(pattern, dict):
+        return {name: _shown_cell(row[name], expected) for name, expected in pattern.items()}
+    cells = pattern if isinstance(pattern, Sequence) else ()
+    return tuple(
+        _shown_cell(cell, cells[index] if index < len(cells) else None)
+        for index, cell in enumerate(row)
+    )
+
+
+def _shown_cell(cell: Cell, expected: Any) -> Any:
+    if _asks_for_links(expected):
+        return cell.links
+    return cell.value
+
+
+def _asks_for_links(expected: Any) -> bool:
+    # For display only: a pattern that is a link, a pair, or a list or tuple of them.
+    if _is_link(expected):
+        return True
+    return isinstance(expected, (tuple, list)) and all(_is_link(item) for item in expected)
+
+
+def _is_link(expected: Any) -> bool:
+    if isinstance(expected, Link):
+        return True
+    return (
+        isinstance(expected, (tuple, list))
+        and len(expected) == 2
+        and isinstance(expected[0], str)
+        and isinstance(expected[1], (str, SplitResult))
+    )

django_admin_kit/messages.py

@@ -0,0 +1,121 @@
+"""The messages the admin shows after an operation, with their level.
+
+A level is the tag a message is drawn with, not a fixed name: Django's own tags merged
+with the project's ``MESSAGE_TAGS``, so a project that tags errors ``danger`` reads them
+as ``danger``.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Iterator, Sequence, overload
+
+from django.contrib.messages.utils import get_level_tags
+from playwright.sync_api import Locator
+
+from .rendered import text_of
+
+
+class Message:
+    """One message: its ``level``, the tag it is drawn with, and its ``text``.
+
+    A message compares equal to another message and to a ``(level, text)`` pair, as a
+    tuple or a list, and to nothing else.
+    """
+
+    def __init__(self, level: str, text: str) -> None:
+        self._level = level
+        self._text = text
+
+    @property
+    def level(self) -> str:
+        """The level's tag, or ``""`` when the message's level has none."""
+        return self._level
+
+    @property
+    def text(self) -> str:
+        return self._text
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Message):
+            return (self._level, self._text) == (other._level, other._text)
+        if isinstance(other, (tuple, list)) and len(other) == 2:
+            return (self._level, self._text) == tuple(other)
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash((self._level, self._text))
+
+    def __repr__(self) -> str:
+        return f"Message({self._level!r}, {self._text!r})"
+
+
+class Messages(Sequence[Message]):
+    """The messages a page shows, in order, read from the page each time they are used.
+
+    ``items`` gives the elements of the messages, and fails when the browser no longer
+    shows the page they are on.
+    """
+
+    def __init__(self, items: Callable[[], Locator]) -> None:
+        self._items = items
+
+    @overload
+    def __getitem__(self, index: int) -> Message: ...
+
+    @overload
+    def __getitem__(self, index: slice) -> list[Message]: ...
+
+    def __getitem__(self, index: int | slice) -> Message | list[Message]:
+        return self._read()[index]
+
+    def __len__(self) -> int:
+        return len(self._read())
+
+    # The page is read once for the whole loop or lookup, rather than once per message as
+    # the sequence's own versions would.
+    def __iter__(self) -> Iterator[Message]:
+        return iter(self._read())
+
+    def __contains__(self, message: object) -> bool:
+        return message in self._read()
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, (Messages, list, tuple)):
+            return self._read() == list(other)
+        return NotImplemented
+
+    __hash__ = None  # type: ignore[assignment]
+
+    def of_level(self, level: str) -> list[str]:
+        """The texts of the messages of ``level``, in order; ``[]`` when there are none.
+
+        ``level`` is a tag the project knows, or ``""`` for messages whose level has no
+        tag. Any other name raises ``KeyError`` listing the levels there are, because a
+        level the project renamed would otherwise read as no messages and let a test pass.
+        """
+        # Django lists its own levels first, in their order, then the ones the project adds.
+        levels = list(dict.fromkeys(get_level_tags().values()))
+        if level and level not in levels:
+            raise KeyError(
+                f"The project has no message level {level!r}. Levels: "
+                f"{', '.join(repr(name) for name in levels)}."
+            )
+        return [message.text for message in self._read() if message.level == level]
+
+    def __repr__(self) -> str:
+        return f"Messages({self._read()!r})"
+
+    def _read(self) -> list[Message]:
+        # Every message is read with the same levels, so they are looked up once.
+        levels = set(get_level_tags().values())
+        return [Message(_level(item, levels), text_of(item)) for item in self._items().all()]
+
+
+def _level(item: Locator, levels: set[str]) -> str:
+    """The level tag among the classes of ``item``, or ``""`` when it has none.
+
+    Django draws a message with its extra tags and then its level tag, so the last class
+    that is a level tag is the level, even when an extra tag spells one too.
+    """
+    classes = (item.get_attribute("class") or "").split()
+    return next((tag for tag in reversed(classes) if tag in levels), "")

django_admin_kit/normalize.py

@@ -0,0 +1,153 @@
+"""How the text of a rendered value becomes its value.
+
+Each kind of value has a rule, a callable that takes the rendered value and returns what a
+test reads. The package picks the rule for a value, so a rule reads one kind and never has to
+tell the kinds apart. Every rule has a default here, and a project replaces any of them in its
+settings.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Any, Callable, Mapping
+
+if TYPE_CHECKING:
+    from django.db.models import Field
+    from playwright.sync_api import Locator
+
+    from .rendered import RenderedValue
+
+Rule = Callable[["RenderedValue"], Any]
+
+_ICONS = {"True": True, "False": False, "None": None}
+
+
+def boolean(rendered: RenderedValue) -> Any:
+    """A boolean the admin draws as an icon, read from the icon's ``alt``: ``True``,
+    ``False``, or ``None`` for a nullable boolean that has no value."""
+    return _ICONS[_icon(rendered).get_attribute("alt") or ""]
+
+
+def empty(rendered: RenderedValue) -> Any:
+    """A value the admin has none of, as the text it shows in its place."""
+    return rendered.text
+
+
+def link(rendered: RenderedValue) -> Any:
+    """A value the admin renders as links, as their text; the links are in ``links``."""
+    return rendered.text
+
+
+def date(rendered: RenderedValue) -> Any:
+    """A date, as the text the project's formats render."""
+    return rendered.text
+
+
+def datetime(rendered: RenderedValue) -> Any:
+    """A date and time, as the text the project's formats render."""
+    return rendered.text
+
+
+def time(rendered: RenderedValue) -> Any:
+    """A time of day, as the text the project's formats render."""
+    return rendered.text
+
+
+def number(rendered: RenderedValue) -> Any:
+    """A number, as the text the project's formats render."""
+    return rendered.text
+
+
+def choice(rendered: RenderedValue) -> Any:
+    """A value from a fixed set of choices, as the label the admin shows for it."""
+    return rendered.text
+
+
+def text(rendered: RenderedValue) -> Any:
+    """Anything else, as its text."""
+    return rendered.text
+
+
+DEFAULTS: dict[str, Rule] = {
+    "boolean": boolean,
+    "empty": empty,
+    "link": link,
+    "date": date,
+    "datetime": datetime,
+    "time": time,
+    "number": number,
+    "choice": choice,
+    "text": text,
+}
+"""The default rule for each kind, by the name a project replaces it under."""
+
+
+class Normalizers:
+    """The rule for each kind of value: the defaults, with the project's replacements."""
+
+    def __init__(self, replaced: Mapping[str, Rule] | None = None) -> None:
+        self._rules = {**DEFAULTS, **(replaced or {})}
+
+    def read(self, rendered: RenderedValue) -> Any:
+        """The value of ``rendered``, read by the rule for its kind."""
+        return self._rules[_kind(rendered)](rendered)
+
+
+def _kind(rendered: RenderedValue) -> str:
+    """The kind of ``rendered``: by the model field behind it where it has one, then by what
+    the admin drew."""
+    # The admin marks a value it has none of only by the text it shows instead.
+    if rendered.text == rendered.empty_display:
+        return "empty"
+    field = rendered.field
+    if field is not None:
+        # The admin shows a field with choices as their labels, whatever the field's class.
+        if field.choices:
+            return "choice"
+        kind = _field_kind(field)
+        if kind is not None:
+            return kind
+    if _draws_a_boolean(rendered):
+        return "boolean"
+    if rendered.links:
+        return "link"
+    return "text"
+
+
+def _field_kind(field: Field) -> str | None:
+    """The kind of the most specific class ``field`` is that has one, so a date-time field,
+    which is also a date field, is a date-time."""
+    # Imported here: this module loads at pytest startup, with the settings.
+    from django.db import models
+
+    kinds = {
+        models.BooleanField: "boolean",
+        models.DateTimeField: "datetime",
+        models.DateField: "date",
+        models.TimeField: "time",
+        models.IntegerField: "number",
+        models.DecimalField: "number",
+        models.FloatField: "number",
+    }
+    return next((kinds[cls] for cls in type(field).__mro__ if cls in kinds), None)
+
+
+def _icon(rendered: RenderedValue) -> Locator:
+    return rendered.native.locator("img[alt]")
+
+
+def _draws_a_boolean(rendered: RenderedValue) -> bool:
+    """Whether the admin drew nothing but one of its boolean icons."""
+    icon = _icon(rendered)
+    if rendered.text or icon.count() != 1:
+        return False
+    return (icon.get_attribute("alt") or "") in _ICONS
+
+
+def integer(rendered: str) -> int:
+    """A whole number as the admin renders one, grouped or not.
+
+    Grouping is the only thing a locale adds to an integer, so dropping everything that
+    is not a digit reads it back under any separator.
+    """
+    return int(re.sub(r"\D", "", rendered))