From 9e17c55a9a66a24c7c20c595f3a194b0e93da9e1 Mon Sep 17 00:00:00 2001
From: Trenton H <797416+stumpylog@users.noreply.github.com>
Date: Thu, 30 Apr 2026 09:45:11 -0700
Subject: [PATCH] test(mail): add mail_api_user, mail_api_client, bogus_mailbox
 fixtures

---
 src/paperless_mail/tests/conftest.py | 55 ++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/src/paperless_mail/tests/conftest.py b/src/paperless_mail/tests/conftest.py
index ae4d78c9c..4dacbc963 100644
--- a/src/paperless_mail/tests/conftest.py
+++ b/src/paperless_mail/tests/conftest.py
@@ -1,12 +1,19 @@
 from collections.abc import Generator
+from typing import TYPE_CHECKING
 
 import pytest
+import pytest_mock
+from django.contrib.auth.models import User
 from django.test import Client
+from rest_framework.test import APIClient
 
 from paperless_mail.mail import MailAccountHandler
 from paperless_mail.models import MailAccount
 from paperless_mail.tests.factories import MailAccountFactory
 
+if TYPE_CHECKING:
+    from paperless_mail.tests.test_mail import BogusMailBox
+
 
 @pytest.fixture()
 def greenmail_mail_account(db: None) -> Generator[MailAccount, None, None]:
@@ -80,3 +87,51 @@ def mail_mocker(db: None):
         yield mocker
     finally:
         mocker.doCleanups()
+
+
+@pytest.fixture()
+def mail_api_user(
+    db: None,
+    django_user_model: type[User],
+) -> User:
+    """
+    Fully-permissioned (regular) user used by the mail API tests.
+
+    Has every model-level permission but is NOT a Django superuser/staff:
+    the owner-aware filtering and bulk_delete permission tests rely on
+    django-guardian's object-level checks, and `is_superuser` short-circuits
+    those checks. The name avoids `admin` to make this distinction explicit.
+    """
+    from django.contrib.auth.models import Permission
+
+    user = django_user_model.objects.create_user(username="mail_api_user")
+    user.user_permissions.add(*Permission.objects.all())
+    user.save()
+    return user
+
+
+@pytest.fixture()
+def mail_api_client(mail_api_user: User) -> APIClient:
+    """
+    DRF APIClient force-authenticated as `mail_api_user` and pinned to API v10
+    via the Accept header (matches `documents/tests/conftest.py:admin_client`).
+    """
+    client = APIClient()
+    client.force_authenticate(user=mail_api_user)
+    client.credentials(HTTP_ACCEPT="application/json; version=10")
+    return client
+
+
+@pytest.fixture()
+def bogus_mailbox(mocker: pytest_mock.MockerFixture) -> "BogusMailBox":
+    """
+    Patch `paperless_mail.mail.MailBox` with a `BogusMailBox` instance so the
+    `/api/mail_accounts/test/` endpoint can run without a real IMAP server.
+    Returns the bogus mailbox so tests can introspect/manipulate it.
+    """
+    from paperless_mail.tests.test_mail import BogusMailBox
+
+    mailbox = BogusMailBox()
+    mock_mailbox_cls = mocker.patch("paperless_mail.mail.MailBox")
+    mock_mailbox_cls.return_value = mailbox
+    return mailbox