Chore: State the test directory layout in one place (#14171)

The temp directory layout used by the tests was written out four separate
times: once in the documents conftest, once in the paperless checks tests,
once in a fixture local to the NFC upload tests, and once in the helper
behind the old paperless_environment context manager. Each copy covered a
different subset of the settings, so which directories a test actually got
depended on which copy it happened to reach.

The layout now lives in paperless_testing.dirs. build_paperless_dirs owns
where things go and creates them, dirs_settings maps them onto Django
setting names and is pure, and a paperless_dirs fixture in the root conftest
applies that mapping through pytest-django's settings fixture so every app
can reach it. Tests that need a second environment part way through a test
body use the paperless_environment context manager from the same module,
which expresses the identical layout through override_settings. The three
redundant implementations and the old media settings fixture are gone, and
their consumers now take paperless_dirs.

src/documents/tests/conftest.py

@@ -1,6 +1,5 @@
 import shutil
 from collections.abc import Generator
-from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING
 
@@ -16,16 +15,7 @@ UserModelT = get_user_model()
 
 if TYPE_CHECKING:
     from documents.models import Document
-
-
-@dataclass(frozen=True, slots=True)
-class PaperlessDirs:
-    """Standard Paperless-ngx directory layout for tests."""
-
-    media: Path
-    originals: Path
-    archive: Path
-    thumbnails: Path
+    from paperless_testing.dirs import PaperlessDirs
 
 
 @pytest.fixture(scope="session")
@@ -34,52 +24,24 @@ def samples_dir() -> Path:
     return Path(__file__).parent / "samples" / "documents"
 
 
-@pytest.fixture()
-def paperless_dirs(tmp_path: Path) -> PaperlessDirs:
-    """Create and return the directory structure for testing."""
-    media = tmp_path / "media"
-    dirs = PaperlessDirs(
-        media=media,
-        originals=media / "documents" / "originals",
-        archive=media / "documents" / "archive",
-        thumbnails=media / "documents" / "thumbnails",
-    )
-    for d in (dirs.originals, dirs.archive, dirs.thumbnails):
-        d.mkdir(parents=True)
-    return dirs
-
-
-@pytest.fixture()
-def _media_settings(paperless_dirs: PaperlessDirs, settings) -> None:
-    """Configure Django settings to point at temp directories."""
-    settings.MEDIA_ROOT = paperless_dirs.media
-    settings.ORIGINALS_DIR = paperless_dirs.originals
-    settings.ARCHIVE_DIR = paperless_dirs.archive
-    settings.THUMBNAIL_DIR = paperless_dirs.thumbnails
-    settings.MEDIA_LOCK = paperless_dirs.media / "media.lock"
-    settings.IGNORABLE_FILES = {".DS_Store", "Thumbs.db", "desktop.ini"}
-    settings.APP_LOGO = ""
-
-
 @pytest.fixture()
 def sample_doc(
-    paperless_dirs: PaperlessDirs,
-    _media_settings: None,
+    paperless_dirs: "PaperlessDirs",
     samples_dir: Path,
 ) -> "Document":
     """Create a document with valid files and matching checksums."""
-    with filelock.FileLock(paperless_dirs.media / "media.lock"):
+    with filelock.FileLock(paperless_dirs.media_lock):
         shutil.copy(
             samples_dir / "originals" / "0000001.pdf",
-            paperless_dirs.originals / "0000001.pdf",
+            paperless_dirs.originals_dir / "0000001.pdf",
         )
         shutil.copy(
             samples_dir / "archive" / "0000001.pdf",
-            paperless_dirs.archive / "0000001.pdf",
+            paperless_dirs.archive_dir / "0000001.pdf",
         )
         shutil.copy(
             samples_dir / "thumbnails" / "0000001.webp",
-            paperless_dirs.thumbnails / "0000001.webp",
+            paperless_dirs.thumbnail_dir / "0000001.webp",
         )
 
     return DocumentFactory(

src/documents/tests/management/test_management_sanity_checker.py

@@ -19,7 +19,7 @@ from paperless_testing.factories import DocumentFactory
 
 if TYPE_CHECKING:
     from documents.models import Document
-    from documents.tests.conftest import PaperlessDirs
+    from paperless_testing.dirs import PaperlessDirs
 
 
 def _render_to_string(messages: SanityCheckMessages) -> str:
@@ -71,7 +71,7 @@ class TestRenderResultsWithIssues:
         assert "INFO" in output
         assert "No OCR data" in output
 
-    @pytest.mark.usefixtures("_media_settings")
+    @pytest.mark.usefixtures("paperless_dirs")
     def test_global_message(self) -> None:
         msgs = SanityCheckMessages()
         msgs.warning(None, "Orphaned file: /tmp/stray.pdf")
@@ -87,7 +87,7 @@ class TestRenderResultsWithIssues:
         assert "Thumbnail missing" in output
         assert "Checksum mismatch" in output
 
-    @pytest.mark.usefixtures("_media_settings")
+    @pytest.mark.usefixtures("paperless_dirs")
     def test_unknown_doc_pk(self) -> None:
         msgs = SanityCheckMessages()
         msgs.error(99999, "Ghost document")
@@ -184,7 +184,6 @@ class TestDocumentSanityCheckerCommand:
         assert "ERROR" in output
         assert "Original of document does not exist" in output
 
-    @pytest.mark.usefixtures("_media_settings")
     def test_checksum_mismatch(self, paperless_dirs: PaperlessDirs) -> None:
         """Lightweight document with zero-byte files triggers checksum mismatch."""
         doc = DocumentFactory(

src/documents/tests/test_api_post_document_nfc.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import unicodedata
 from typing import TYPE_CHECKING
 from unittest import mock
@@ -7,8 +9,11 @@ import pytest
 from django.core.files.uploadedfile import SimpleUploadedFile
 
 if TYPE_CHECKING:
+    from rest_framework.test import APIClient
+
     from documents.data_models import ConsumableDocument
     from documents.data_models import DocumentMetadataOverrides
+    from paperless_testing.dirs import PaperlessDirs
 
 
 @pytest.fixture()
@@ -18,22 +23,14 @@ def consume_file_mock():
         yield m
 
 
-@pytest.fixture()
-def directories(tmp_path, settings, _media_settings):
-    scratch = tmp_path / "scratch"
-    scratch.mkdir()
-    settings.SCRATCH_DIR = scratch
-    return scratch
-
-
 @pytest.mark.django_db
 class TestPostDocumentNFCNormalization:
     def test_nfd_filename_normalized_to_nfc(
         self,
-        admin_client,
+        admin_client: APIClient,
         consume_file_mock: mock.MagicMock,
-        directories,
-    ):
+        paperless_dirs: PaperlessDirs,
+    ) -> None:
         """Uploaded file with NFD filename must have its name stored as NFC."""
         nfd = unicodedata.normalize("NFD", "Rechnung März.pdf")
         nfc = unicodedata.normalize("NFC", "Rechnung März.pdf")
@@ -69,10 +66,10 @@ class TestPostDocumentNFCNormalization:
 
     def test_already_nfc_filename_unchanged(
         self,
-        admin_client,
+        admin_client: APIClient,
         consume_file_mock: mock.MagicMock,
-        directories,
-    ):
+        paperless_dirs: PaperlessDirs,
+    ) -> None:
         """Uploaded file with already-NFC filename must pass through unchanged."""
         nfc = unicodedata.normalize("NFC", "Invoice_2024.pdf")
 

src/documents/tests/test_management_exporter.py

@@ -49,8 +49,8 @@ from documents.settings import EXPORTER_SHARE_LINK_BUNDLE_NAME
 from documents.tests.utils import DirectoriesMixin
 from documents.tests.utils import FileSystemAssertsMixin
 from documents.tests.utils import SampleDirMixin
-from documents.tests.utils import paperless_environment
 from paperless_mail.models import MailAccount
+from paperless_testing.dirs import paperless_environment
 
 
 @pytest.mark.management

src/documents/tests/test_permission_filtering_security.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from http import HTTPStatus
+from typing import TYPE_CHECKING
 from unittest.mock import patch
 
 import pytest
@@ -30,6 +31,9 @@ from paperless_testing.factories import DocumentTypeFactory
 from paperless_testing.factories import StoragePathFactory
 from paperless_testing.factories import TagFactory
 
+if TYPE_CHECKING:
+    from paperless_testing.dirs import PaperlessDirs
+
 
 def assert_visible_document_ids(actual_ids, *, expected_visible, expected_hidden):
     actual_ids = set(actual_ids)
@@ -369,10 +373,9 @@ class TestBulkEditChangePermissionBoundary:
 class TestBulkDownloadPermissionChecksRootDocument:
     def test_download_requires_global_view_permission(
         self,
-        rest_api_client,
-        paperless_dirs,
-        _media_settings,
-    ):
+        rest_api_client: APIClient,
+        paperless_dirs: PaperlessDirs,
+    ) -> None:
         owner = User.objects.create_user(username="owner")
         requester = User.objects.create_user(username="requester")
         root = DocumentFactory(owner=owner)
@@ -390,10 +393,9 @@ class TestBulkDownloadPermissionChecksRootDocument:
 
     def test_permission_checked_on_root_not_on_version(
         self,
-        rest_api_client,
-        paperless_dirs,
-        _media_settings,
-    ):
+        rest_api_client: APIClient,
+        paperless_dirs: PaperlessDirs,
+    ) -> None:
         owner = User.objects.create_user(username="owner")
         requester = User.objects.create_user(username="requester")
         requester.user_permissions.add(

src/documents/tests/test_sanity_check.py

@@ -19,7 +19,7 @@ if TYPE_CHECKING:
     from collections.abc import Iterable
 
     from documents.models import Document
-    from documents.tests.conftest import PaperlessDirs
+    from paperless_testing.dirs import PaperlessDirs
 
 
 class TestSanityCheckMessages:
@@ -46,14 +46,14 @@ class TestSanityCheckMessages:
 class TestCheckSanityNoDocuments:
     """Sanity checks against an empty archive."""
 
-    @pytest.mark.usefixtures("_media_settings")
+    @pytest.mark.usefixtures("paperless_dirs")
     def test_no_documents(self) -> None:
         messages = check_sanity()
         assert not messages.has_error
         assert not messages.has_warning
         assert messages.total_issue_count == 0
 
-    @pytest.mark.usefixtures("_media_settings")
+    @pytest.mark.usefixtures("paperless_dirs")
     def test_no_issues_logs_clean(self, caplog: pytest.LogCaptureFixture) -> None:
         messages = check_sanity()
         with caplog.at_level(logging.INFO, logger="paperless.sanity_checker"):
@@ -214,18 +214,17 @@ class TestCheckSanityOrphans:
         sample_doc: Document,
         paperless_dirs: PaperlessDirs,
     ) -> None:
-        (paperless_dirs.originals / "orphan.pdf").touch()
+        (paperless_dirs.originals_dir / "orphan.pdf").touch()
         messages = check_sanity()
         assert messages.has_warning
         assert any("Orphaned file" in m["message"] for m in messages[None])
 
-    @pytest.mark.usefixtures("_media_settings")
     def test_ignorable_files_not_flagged(
         self,
         paperless_dirs: PaperlessDirs,
     ) -> None:
-        (paperless_dirs.media / ".DS_Store").touch()
-        (paperless_dirs.media / "desktop.ini").touch()
+        (paperless_dirs.media_dir / ".DS_Store").touch()
+        (paperless_dirs.media_dir / "desktop.ini").touch()
         messages = check_sanity()
         assert not messages.has_warning
 
@@ -269,13 +268,13 @@ class TestCheckSanityLogMessages:
         paperless_dirs: PaperlessDirs,
         caplog: pytest.LogCaptureFixture,
     ) -> None:
-        (paperless_dirs.originals / "orphan.pdf").touch()
+        (paperless_dirs.originals_dir / "orphan.pdf").touch()
         messages = check_sanity()
         with caplog.at_level(logging.WARNING, logger="paperless.sanity_checker"):
             messages.log_messages()
         assert "Orphaned file" in caplog.text
 
-    @pytest.mark.usefixtures("_media_settings")
+    @pytest.mark.usefixtures("paperless_dirs")
     def test_logs_unknown_doc_pk(self, caplog: pytest.LogCaptureFixture) -> None:
         """A doc PK not in the DB logs 'Unknown' as the title."""
         messages = check_sanity()

src/documents/tests/utils.py

@@ -79,17 +79,6 @@ def remove_dirs(dirs) -> None:
     dirs.settings_override.disable()
 
 
-@contextmanager
-def paperless_environment():
-    dirs = None
-    try:
-        dirs = setup_directories()
-        yield dirs
-    finally:
-        if dirs:
-            remove_dirs(dirs)
-
-
 def util_call_with_backoff(
     method_or_callable: Callable,
     args: list | tuple,