pytest-django-admin-kit 1.0.0__tar.gz → 1.1.0__tar.gz

{pytest_django_admin_kit-1.0.0 → pytest_django_admin_kit-1.1.0}/CHANGELOG.md

@@ -5,6 +5,62 @@ All notable changes to this project are listed in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [1.1.0] - 2026-11-05
+
+### Added
+
+- Open the login page with `admin_ui.login()`, fill it with `page.fill(username=..., password=...)`
+  and submit it with `page.submit()`. A refused form is the same page, so it can be filled
+  again. Opening the login page logs nobody out.
+- `admin_ui.login(user, password=...)` returns the result of the submission, so
+  `result.success` says whether the admin let the user in.
+- A submission that ends on the login page has the login page as its `result.page`.
+- Read what a login page says with `page.errors`, the notes above the form such as why a login
+  was refused, and `page.field_errors`, the errors under each input.
+- Read the help the admin shows with a field with `field.help_text`, `""` for a field without
+  any. A field the user may only read has it too.
+- Get the fields the user may only read and the ones with a control to fill with
+  `page.readonly_fields` and `page.editable_fields`. They follow what the page shows, so a user
+  who may only view gets every field as read-only.
+- List the fieldsets of a form with `page.fieldsets`. Each one has its `name` and its
+  `description`, `None` when it has none, and its `fields`, read and filled like `page.fields`.
+- Tell whether a fieldset can be collapsed and whether it is collapsed now with
+  `fieldset.collapsible` and `fieldset.collapsed`, and open or collapse it with
+  `fieldset.open()` and `fieldset.close()`.
+- Read and fill the admin's split date-time through the built-in `SplitDateTimeWidget`. It reads
+  as the date and the time as typed, such as `("2026-01-15", "09:30:00")`, and is filled from a
+  `datetime`, a `(date, time)` pair or `None`.
+- Read and fill radio buttons, as the admin draws a field named in `radio_fields`, through the
+  built-in `RadioWidget`. They're read, filled and listed as a select is, and read as `None`
+  while none is checked.
+- Read and fill a multiple select, as the admin draws a many-to-many field, through the built-in
+  `SelectMultipleWidget`. It reads as the list of choices made and is filled with a list of
+  values, each written as for a select. A lone value raises `TypeError`.
+- `page.populate(instance)` fills a many-to-many field with a saved instance's related objects,
+  and leaves it alone for an unsaved instance, which has none yet.
+
+### Changed
+
+- Asking `page.fields` for a field the form doesn't have now says
+  `No field named 'color' here.`, rather than `The form has no field named 'color'.`, so the
+  same message fits a fieldset's fields. It still lists the fields there are.
+
+### Fixed
+
+- A multiple select no longer reads as one option, and filling it no longer replaces the choice
+  with a single option. It reads and fills as a list.
+- `page.populate(instance)` no longer fails with `ValueError` on an unsaved model instance with
+  a many-to-many field.
+- A `filter_horizontal` or `filter_vertical` field raises `LookupError` at once when read or
+  filled, rather than waiting for the timeout. No built-in widget class takes the two lists the
+  admin's script draws for it, so a project can add its own.
+- `admin_ui.login(user, password="")` no longer waits 30 seconds and fails. The browser does not
+  send a form with an empty input, so the result is no success, at once.
+- Filling a field of a collapsed fieldset, with `field.fill()` or `page.populate()`, no longer
+  waits for the timeout and fails. The fieldset is opened first, as the user has to.
+
 ## [1.0.0] - 2026-10-13
 
 The first release. Tests open the Django admin in a real browser and check it with plain
@@ -80,4 +136,6 @@ The first release. Tests open the Django admin in a real browser and check it wi
 - Tests can run in parallel, and every test starts logged out.
 - Works with Python 3.8 to 3.14 and Django 3.2 to 6.1.
 
+[Unreleased]: https://github.com/JeyKip/pytest-django-admin-kit/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/JeyKip/pytest-django-admin-kit/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/JeyKip/pytest-django-admin-kit/releases/tag/v1.0.0

{pytest_django_admin_kit-1.0.0 → pytest_django_admin_kit-1.1.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: pytest-django-admin-kit
-Version: 1.0.0
-Summary: A pytest toolkit for writing conscious tests against the Django admin.
+Version: 1.1.0
+Summary: Pytest plugin for testing the Django admin in a real browser, with plain asserts.
 Project-URL: Homepage, https://github.com/JeyKip/pytest-django-admin-kit
 Project-URL: Source, https://github.com/JeyKip/pytest-django-admin-kit
 Project-URL: Changelog, https://github.com/JeyKip/pytest-django-admin-kit/blob/main/CHANGELOG.md
@@ -63,7 +63,7 @@ Description-Content-Type: text/markdown
 
 # pytest-django-admin-kit
 
-A pytest toolkit for writing conscious tests against the Django admin.
+Pytest plugin for testing the Django admin in a real browser, with plain asserts.
 
 Tests describe admin pages, their fields, rows, permissions and errors, using ordinary `assert`
 statements, and stay unchanged across supported Django versions.
@@ -78,10 +78,19 @@ def test_product_admin(admin_ui, admin_user, product):
 
 Install it as `pytest-django-admin-kit`; import it as `django_admin_kit`.
 
+AI agents can start from [llms.txt](https://github.com/JeyKip/pytest-django-admin-kit/blob/main/llms.txt).
+To point yours there, add this line to your project's `AGENTS.md` or `CLAUDE.md`:
+
+```markdown
+Before writing admin tests, read https://raw.githubusercontent.com/JeyKip/pytest-django-admin-kit/main/llms.txt
+```
+
 ## Status
 
-Version 1.0.0 implements the API written up in [specification.md](specification.md), and its
-public API is stable. What changed in each release is in [CHANGELOG.md](CHANGELOG.md), and what
+Version 1.1.0 implements the API written up in
+[specification.md](https://github.com/JeyKip/pytest-django-admin-kit/blob/main/specification.md),
+and its public API is stable. What changed in each release is in
+[CHANGELOG.md](https://github.com/JeyKip/pytest-django-admin-kit/blob/main/CHANGELOG.md), and what
 comes next is the roadmap in section 33 of the specification.
 
 ## What it solves today
@@ -119,10 +128,36 @@ project that mounts its admin elsewhere changes nothing.
 admin_ui.url.edit(product)
 ```
 
-**Testing the login page itself.** Typing into the form is an opt-in, never the default.
+**Testing the login page itself.** Typing into the form is an opt-in, never the default. The
+result says whether the admin let the user in.
+
+```python
+result = admin_ui.login(user, password="secret")
+assert result.success
+```
+
+To fill the form the way the test needs, open it, fill it and submit it in separate steps. A
+refused form stays the same page, so it can be filled again.
 
 ```python
-admin_ui.login(user, password="secret")
+page = admin_ui.login()
+page.fill(username="alice", password="wrong")
+result = page.submit()
+assert not result.success
+
+result.page.fill(password="secret")
+assert result.page.submit().success
+```
+
+A refused page reads what the admin says: the notes above the form, and the errors under each
+input.
+
+```python
+assert result.page.errors == [
+    "Please enter the correct username and password for a staff account. "
+    "Note that both fields may be case-sensitive."
+]
+assert result.page.field_errors == {}
 ```
 
 **Opening a changelist and reading its count and columns.** The count is what the page says,
@@ -196,8 +231,15 @@ assert page.fields["name"].required
 assert not page.fields["price_with_tax"].editable
 assert page.required_fields == {"name", "sku", "price", "quantity", "released_on"}
 assert page.optional_fields == {"is_active", "featured", "category"}
+assert page.readonly_fields == {"price_with_tax"}
+assert "name" in page.editable_fields
+# The admin sets no `fieldsets`, so Django draws every field in one fieldset without a name.
+assert page.fieldsets[0].name is None
+assert list(page.fieldsets[0].fields) == list(page.fields)
+assert not page.fieldsets[0].collapsible    # no `collapse` class, so no toggle to open it
 
 assert page.fields["name"].label == "Name"
+assert page.fields["sku"].help_text == "The code printed on the label."
 assert page.fields["name"].value == "Widget"
 assert page.fields["is_active"].value is True
 assert page.fields["category"].value == (str(tools.pk), "Tools")
@@ -233,7 +275,15 @@ assert page.fields["featured"].value == ("true", "Yes")
 
 A select takes back a choice it offered, `page.fields["category"].fill(choice)`, and `None`
 puts it on its blank option. A value no option has raises `ValueError` naming the options
-there are, and a field the user may only read raises `LookupError`.
+there are, and a field the user may only read raises `LookupError`. Radio buttons, as the admin
+draws a field named in `radio_fields`, are read and filled the same way, and read as `None` while
+none is checked. A multiple select reads as the list of choices made, and is filled with a list
+of values, each written as for a select: `fill([tools, toys])`, and `fill([])` clears it.
+
+A date-time, which the admin draws as a date input and a time input, reads as the two texts,
+`("2026-01-15", "09:30:00")`. It's filled from a `datetime`, typed in the current time zone, from
+a `(date, time)` pair whose halves may also be text or `None`, or from `None`, which empties
+both.
 
 **Filling a whole form in one call.** A dictionary carries the shared data and keywords carry
 the values this one test is about. Fields that are named nowhere keep the values the admin
@@ -350,8 +400,8 @@ such as `text=`, belongs in `read` and `fill`. To combine conditions, use `:has(
 `':scope:has(input[name="image_cache_key"]) input[type="file"]'`.
 
 Your classes are tried first, in the order you list them, then the package's own:
-`CheckboxWidget`, `SelectWidget` and `TextWidget`, from `django_admin_kit.widgets`. Two rules
-follow from that:
+`CheckboxWidget`, `RadioWidget`, `SelectMultipleWidget`, `SelectWidget`, `SplitDateTimeWidget` and
+`TextWidget`, from `django_admin_kit.widgets`. Two rules follow from that:
 
 - A marker matches what is particular to its widget. A class marked by `input[type="file"]`
   would take every file field in the project.
@@ -912,7 +962,7 @@ So editing `tox.toml` changes CI, and the two cannot disagree.
 
 The build job refuses to run if the tag doesn't match the `version` in `pyproject.toml`, so bump
 the version in the same commit you tag. The steps of a release are in
-[RELEASING.md](RELEASING.md).
+[RELEASING.md](https://github.com/JeyKip/pytest-django-admin-kit/blob/main/RELEASING.md).
 
 ## Building
 
@@ -948,4 +998,4 @@ specification.md         the public API this is built against
 
 ## License
 
-MIT. See [LICENSE](LICENSE).
+MIT. See [LICENSE](https://github.com/JeyKip/pytest-django-admin-kit/blob/main/LICENSE).

{pytest_django_admin_kit-1.0.0 → pytest_django_admin_kit-1.1.0}/README.md

@@ -1,6 +1,6 @@
 # pytest-django-admin-kit
 
-A pytest toolkit for writing conscious tests against the Django admin.
+Pytest plugin for testing the Django admin in a real browser, with plain asserts.
 
 Tests describe admin pages, their fields, rows, permissions and errors, using ordinary `assert`
 statements, and stay unchanged across supported Django versions.
@@ -15,10 +15,19 @@ def test_product_admin(admin_ui, admin_user, product):
 
 Install it as `pytest-django-admin-kit`; import it as `django_admin_kit`.
 
+AI agents can start from [llms.txt](https://github.com/JeyKip/pytest-django-admin-kit/blob/main/llms.txt).
+To point yours there, add this line to your project's `AGENTS.md` or `CLAUDE.md`:
+
+```markdown
+Before writing admin tests, read https://raw.githubusercontent.com/JeyKip/pytest-django-admin-kit/main/llms.txt
+```
+
 ## Status
 
-Version 1.0.0 implements the API written up in [specification.md](specification.md), and its
-public API is stable. What changed in each release is in [CHANGELOG.md](CHANGELOG.md), and what
+Version 1.1.0 implements the API written up in
+[specification.md](https://github.com/JeyKip/pytest-django-admin-kit/blob/main/specification.md),
+and its public API is stable. What changed in each release is in
+[CHANGELOG.md](https://github.com/JeyKip/pytest-django-admin-kit/blob/main/CHANGELOG.md), and what
 comes next is the roadmap in section 33 of the specification.
 
 ## What it solves today
@@ -56,10 +65,36 @@ project that mounts its admin elsewhere changes nothing.
 admin_ui.url.edit(product)
 ```
 
-**Testing the login page itself.** Typing into the form is an opt-in, never the default.
+**Testing the login page itself.** Typing into the form is an opt-in, never the default. The
+result says whether the admin let the user in.
+
+```python
+result = admin_ui.login(user, password="secret")
+assert result.success
+```
+
+To fill the form the way the test needs, open it, fill it and submit it in separate steps. A
+refused form stays the same page, so it can be filled again.
 
 ```python
-admin_ui.login(user, password="secret")
+page = admin_ui.login()
+page.fill(username="alice", password="wrong")
+result = page.submit()
+assert not result.success
+
+result.page.fill(password="secret")
+assert result.page.submit().success
+```
+
+A refused page reads what the admin says: the notes above the form, and the errors under each
+input.
+
+```python
+assert result.page.errors == [
+    "Please enter the correct username and password for a staff account. "
+    "Note that both fields may be case-sensitive."
+]
+assert result.page.field_errors == {}
 ```
 
 **Opening a changelist and reading its count and columns.** The count is what the page says,
@@ -133,8 +168,15 @@ assert page.fields["name"].required
 assert not page.fields["price_with_tax"].editable
 assert page.required_fields == {"name", "sku", "price", "quantity", "released_on"}
 assert page.optional_fields == {"is_active", "featured", "category"}
+assert page.readonly_fields == {"price_with_tax"}
+assert "name" in page.editable_fields
+# The admin sets no `fieldsets`, so Django draws every field in one fieldset without a name.
+assert page.fieldsets[0].name is None
+assert list(page.fieldsets[0].fields) == list(page.fields)
+assert not page.fieldsets[0].collapsible    # no `collapse` class, so no toggle to open it
 
 assert page.fields["name"].label == "Name"
+assert page.fields["sku"].help_text == "The code printed on the label."
 assert page.fields["name"].value == "Widget"
 assert page.fields["is_active"].value is True
 assert page.fields["category"].value == (str(tools.pk), "Tools")
@@ -170,7 +212,15 @@ assert page.fields["featured"].value == ("true", "Yes")
 
 A select takes back a choice it offered, `page.fields["category"].fill(choice)`, and `None`
 puts it on its blank option. A value no option has raises `ValueError` naming the options
-there are, and a field the user may only read raises `LookupError`.
+there are, and a field the user may only read raises `LookupError`. Radio buttons, as the admin
+draws a field named in `radio_fields`, are read and filled the same way, and read as `None` while
+none is checked. A multiple select reads as the list of choices made, and is filled with a list
+of values, each written as for a select: `fill([tools, toys])`, and `fill([])` clears it.
+
+A date-time, which the admin draws as a date input and a time input, reads as the two texts,
+`("2026-01-15", "09:30:00")`. It's filled from a `datetime`, typed in the current time zone, from
+a `(date, time)` pair whose halves may also be text or `None`, or from `None`, which empties
+both.
 
 **Filling a whole form in one call.** A dictionary carries the shared data and keywords carry
 the values this one test is about. Fields that are named nowhere keep the values the admin
@@ -287,8 +337,8 @@ such as `text=`, belongs in `read` and `fill`. To combine conditions, use `:has(
 `':scope:has(input[name="image_cache_key"]) input[type="file"]'`.
 
 Your classes are tried first, in the order you list them, then the package's own:
-`CheckboxWidget`, `SelectWidget` and `TextWidget`, from `django_admin_kit.widgets`. Two rules
-follow from that:
+`CheckboxWidget`, `RadioWidget`, `SelectMultipleWidget`, `SelectWidget`, `SplitDateTimeWidget` and
+`TextWidget`, from `django_admin_kit.widgets`. Two rules follow from that:
 
 - A marker matches what is particular to its widget. A class marked by `input[type="file"]`
   would take every file field in the project.
@@ -849,7 +899,7 @@ So editing `tox.toml` changes CI, and the two cannot disagree.
 
 The build job refuses to run if the tag doesn't match the `version` in `pyproject.toml`, so bump
 the version in the same commit you tag. The steps of a release are in
-[RELEASING.md](RELEASING.md).
+[RELEASING.md](https://github.com/JeyKip/pytest-django-admin-kit/blob/main/RELEASING.md).
 
 ## Building
 
@@ -885,4 +935,4 @@ specification.md         the public API this is built against
 
 ## License
 
-MIT. See [LICENSE](LICENSE).
+MIT. See [LICENSE](https://github.com/JeyKip/pytest-django-admin-kit/blob/main/LICENSE).

pytest_django_admin_kit-1.1.0/llms.txt

@@ -0,0 +1,41 @@
+# pytest-django-admin-kit
+
+> Pytest plugin for testing the Django admin in a real browser, with plain asserts. Install it as `pytest-django-admin-kit` and import it as `django_admin_kit`. It needs Python 3.8+ and Django 3.2+.
+
+Installing the package registers the plugin and the `admin_ui` fixture. The project also needs pytest-django configured and a browser, from `playwright install chromium`.
+
+```python
+def test_product_admin(admin_ui, admin_user, product):
+    admin_ui.login(admin_user)
+
+    assert admin_ui.list(Product).count == 1
+
+    page = admin_ui.edit(product)
+    page.populate(name="Renamed")
+    result = page.save()
+
+    assert result.success
+    assert result.page.messages.of_level("success")
+```
+
+Before writing tests:
+
+- Open pages with `admin_ui.index()`, `list(Model)`, `create(Model)`, `edit(obj)`, `delete(obj)` and `open(path)`. Get URLs from `admin_ui.url` rather than hardcoding `/admin/`.
+- `admin_ui.login(user)` needs no password. Passing `password=` types into the login form, so use it only to test that form.
+- Reads are live. After a submission, read `result.page`, because reading a page the browser has left raises `LookupError`.
+- Configure everything under the `DJANGO_ADMIN_KIT` setting. An unknown key is an error.
+- A field no widget class recognizes raises `LookupError`. Add a class to `DJANGO_ADMIN_KIT["widgets"]`, or override the `admin_ui_widgets` fixture for some tests. `filter_horizontal` and `filter_vertical` fields need this today.
+- For what the package doesn't model yet, use `.native`, the Playwright object behind a page, field, row or cell. That currently includes inlines and changelist search, filters, sorting, pagination and actions.
+- pytest-playwright deletes `test-results/` at the start of every session, so keep other output elsewhere or pass `--output`.
+- Don't set a fixed live server address, such as `--liveserver=localhost:8081`. It breaks parallel runs under `pytest-xdist`.
+
+The links below follow `main`, which can be ahead of the latest release. Check a feature's version in the changelog against the version installed.
+
+## Docs
+
+- [README](https://raw.githubusercontent.com/JeyKip/pytest-django-admin-kit/main/README.md): "What it solves today" and "Settings" cover usage, with examples. The sections after them are for contributors.
+- [Changelog](https://raw.githubusercontent.com/JeyKip/pytest-django-admin-kit/main/CHANGELOG.md): what each release added, and what is still unreleased.
+
+## Optional
+
+- [Specification](https://raw.githubusercontent.com/JeyKip/pytest-django-admin-kit/main/specification.md): the full design, over 3,000 lines. Section 27 covers fixtures, section 28 configuration and extension, and section 33 the roadmap. Parts not marked "(done)" may not exist yet.

{pytest_django_admin_kit-1.0.0 → pytest_django_admin_kit-1.1.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pytest-django-admin-kit"
-version = "1.0.0"
-description = "A pytest toolkit for writing conscious tests against the Django admin."
+version = "1.1.0"
+description = "Pytest plugin for testing the Django admin in a real browser, with plain asserts."
 readme = "README.md"
 requires-python = ">=3.8"
 license = { file = "LICENSE" }