loremfile 0.2.0__tar.gz → 0.3.0__tar.gz

{loremfile-0.2.0 → loremfile-0.3.0}/PKG-INFO

@@ -1,18 +1,19 @@
 Metadata-Version: 2.4
 Name: loremfile
-Version: 0.2.0
+Version: 0.3.0
 Summary: Download CC0 sample files from loremfile.dev and verify every byte
 Author: the loremfile.dev contributors
 License-Expression: MIT
 Project-URL: Homepage, https://loremfile.dev
 Project-URL: Source, https://github.com/kumarprabhashanand/loremfile
 Project-URL: Issues, https://github.com/kumarprabhashanand/loremfile/issues
-Keywords: fixtures,test-data,sample-files,cc0,download,mcp
+Keywords: fixtures,test-data,sample-files,cc0,download,mcp,pytest
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Testing
+Classifier: Framework :: Pytest
 Classifier: Environment :: Console
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -50,6 +51,28 @@ refuse to run if loremfile.dev has moved on. `get` also takes `--force` (overwri
 Exit codes: `0` fine, `1` a file failed verification or is missing, `2` the request was
 wrong, `3` loremfile.dev could not be read.
 
+## In a pytest suite
+
+For files too big to commit: multi-megabyte video, audio and archives that would otherwise
+bloat a repository. Installing the client gives pytest a `loremfile` fixture:
+
+```python
+def test_reads_a_real_mp4(loremfile):
+    video = loremfile("mp4/10mb.mp4")  # a pathlib.Path
+    ...
+```
+
+The first call downloads the file into `.pytest_cache` and checks its SHA-256 against the
+manifest; a file that does not match is never returned. Published files never change at
+their path, so after that the file and its manifest entry are reused and the suite needs no
+network for them. In CI, cache `.pytest_cache/d/loremfile` between runs to keep it that way;
+`pytest --cache-clear` starts over.
+
+It is not for every suite. If your tests may not touch the network, or the file you need is
+a 4 KB PDF, commit the file: that is simpler and needs nothing from us. The fixture takes a
+path only (`loremfile list` finds one), needs pytest 8.0 or newer, and does nothing until a
+test asks for it.
+
 ## MCP server
 
 <!-- mcp-name: io.github.kumarprabhashanand/loremfile -->
@@ -94,7 +117,7 @@ oldest CPython still receiving security fixes when a release is cut; a new one i
 supported within six weeks of its release, and an end-of-life one is dropped in the next
 minor release.
 
-Zero dependencies — standard library only.
+Zero dependencies: standard library only.
 
 ## In GitHub Actions, prefer the action
 
@@ -105,15 +128,15 @@ Zero dependencies — standard library only.
 ```
 
 It is shell only and needs no install step. This client is for everywhere else: a laptop,
-a Makefile, a CI system that is not Actions, or Windows — which the action does not
+a Makefile, a CI system that is not Actions, or Windows, which the action does not
 support because it needs `sha256sum`.
 
 ## One name, two tools
 
 The console script installed here is `loremfile`, which is also the name of the
 repository's own development CLI (the one that generates and publishes the fixtures).
-They are never installed together — that tool lives only inside the project's toolchain
-image — but a contributor who installs both into one environment gets whichever was
+They are never installed together (that tool lives only inside the project's toolchain
+image), but a contributor who installs both into one environment gets whichever was
 installed last. The published package contains the client only: no generators, no
 validators, no uploader, no infrastructure code.
 

{loremfile-0.2.0 → loremfile-0.3.0}/README.md

@@ -31,6 +31,28 @@ refuse to run if loremfile.dev has moved on. `get` also takes `--force` (overwri
 Exit codes: `0` fine, `1` a file failed verification or is missing, `2` the request was
 wrong, `3` loremfile.dev could not be read.
 
+## In a pytest suite
+
+For files too big to commit: multi-megabyte video, audio and archives that would otherwise
+bloat a repository. Installing the client gives pytest a `loremfile` fixture:
+
+```python
+def test_reads_a_real_mp4(loremfile):
+    video = loremfile("mp4/10mb.mp4")  # a pathlib.Path
+    ...
+```
+
+The first call downloads the file into `.pytest_cache` and checks its SHA-256 against the
+manifest; a file that does not match is never returned. Published files never change at
+their path, so after that the file and its manifest entry are reused and the suite needs no
+network for them. In CI, cache `.pytest_cache/d/loremfile` between runs to keep it that way;
+`pytest --cache-clear` starts over.
+
+It is not for every suite. If your tests may not touch the network, or the file you need is
+a 4 KB PDF, commit the file: that is simpler and needs nothing from us. The fixture takes a
+path only (`loremfile list` finds one), needs pytest 8.0 or newer, and does nothing until a
+test asks for it.
+
 ## MCP server
 
 <!-- mcp-name: io.github.kumarprabhashanand/loremfile -->
@@ -75,7 +97,7 @@ oldest CPython still receiving security fixes when a release is cut; a new one i
 supported within six weeks of its release, and an end-of-life one is dropped in the next
 minor release.
 
-Zero dependencies — standard library only.
+Zero dependencies: standard library only.
 
 ## In GitHub Actions, prefer the action
 
@@ -86,15 +108,15 @@ Zero dependencies — standard library only.
 ```
 
 It is shell only and needs no install step. This client is for everywhere else: a laptop,
-a Makefile, a CI system that is not Actions, or Windows — which the action does not
+a Makefile, a CI system that is not Actions, or Windows, which the action does not
 support because it needs `sha256sum`.
 
 ## One name, two tools
 
 The console script installed here is `loremfile`, which is also the name of the
 repository's own development CLI (the one that generates and publishes the fixtures).
-They are never installed together — that tool lives only inside the project's toolchain
-image — but a contributor who installs both into one environment gets whichever was
+They are never installed together (that tool lives only inside the project's toolchain
+image), but a contributor who installs both into one environment gets whichever was
 installed last. The published package contains the client only: no generators, no
 validators, no uploader, no infrastructure code.
 

{loremfile-0.2.0 → loremfile-0.3.0}/pyproject.toml

@@ -11,7 +11,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "loremfile"
-version = "0.2.0"
+version = "0.3.0"
 description = "Download CC0 sample files from loremfile.dev and verify every byte"
 readme = "README.md"
 # A range, and a policy: the floor is the oldest CPython still receiving security fixes
@@ -21,13 +21,14 @@ readme = "README.md"
 requires-python = ">=3.11"
 license = "MIT"
 authors = [{ name = "the loremfile.dev contributors" }]
-keywords = ["fixtures", "test-data", "sample-files", "cc0", "download", "mcp"]
+keywords = ["fixtures", "test-data", "sample-files", "cc0", "download", "mcp", "pytest"]
 classifiers = [
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
   "Topic :: Software Development :: Testing",
+  "Framework :: Pytest",
   "Environment :: Console",
 ]
 # Deliberately empty, and a decision rather than an omission: the client is standard
@@ -37,6 +38,11 @@ dependencies = []
 [project.scripts]
 loremfile = "loremfile_client.cli:main"
 
+# The `loremfile` fixture. pytest loads this in every run where the client is installed,
+# so the module does nothing until a test asks for the fixture (tests/test_pytest_plugin.py).
+[project.entry-points.pytest11]
+loremfile = "loremfile_client.pytest_plugin"
+
 [project.urls]
 Homepage = "https://loremfile.dev"
 Source = "https://github.com/kumarprabhashanand/loremfile"

{loremfile-0.2.0 → loremfile-0.3.0}/src/loremfile.egg-info/PKG-INFO

@@ -1,18 +1,19 @@
 Metadata-Version: 2.4
 Name: loremfile
-Version: 0.2.0
+Version: 0.3.0
 Summary: Download CC0 sample files from loremfile.dev and verify every byte
 Author: the loremfile.dev contributors
 License-Expression: MIT
 Project-URL: Homepage, https://loremfile.dev
 Project-URL: Source, https://github.com/kumarprabhashanand/loremfile
 Project-URL: Issues, https://github.com/kumarprabhashanand/loremfile/issues
-Keywords: fixtures,test-data,sample-files,cc0,download,mcp
+Keywords: fixtures,test-data,sample-files,cc0,download,mcp,pytest
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Testing
+Classifier: Framework :: Pytest
 Classifier: Environment :: Console
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -50,6 +51,28 @@ refuse to run if loremfile.dev has moved on. `get` also takes `--force` (overwri
 Exit codes: `0` fine, `1` a file failed verification or is missing, `2` the request was
 wrong, `3` loremfile.dev could not be read.
 
+## In a pytest suite
+
+For files too big to commit: multi-megabyte video, audio and archives that would otherwise
+bloat a repository. Installing the client gives pytest a `loremfile` fixture:
+
+```python
+def test_reads_a_real_mp4(loremfile):
+    video = loremfile("mp4/10mb.mp4")  # a pathlib.Path
+    ...
+```
+
+The first call downloads the file into `.pytest_cache` and checks its SHA-256 against the
+manifest; a file that does not match is never returned. Published files never change at
+their path, so after that the file and its manifest entry are reused and the suite needs no
+network for them. In CI, cache `.pytest_cache/d/loremfile` between runs to keep it that way;
+`pytest --cache-clear` starts over.
+
+It is not for every suite. If your tests may not touch the network, or the file you need is
+a 4 KB PDF, commit the file: that is simpler and needs nothing from us. The fixture takes a
+path only (`loremfile list` finds one), needs pytest 8.0 or newer, and does nothing until a
+test asks for it.
+
 ## MCP server
 
 <!-- mcp-name: io.github.kumarprabhashanand/loremfile -->
@@ -94,7 +117,7 @@ oldest CPython still receiving security fixes when a release is cut; a new one i
 supported within six weeks of its release, and an end-of-life one is dropped in the next
 minor release.
 
-Zero dependencies — standard library only.
+Zero dependencies: standard library only.
 
 ## In GitHub Actions, prefer the action
 
@@ -105,15 +128,15 @@ Zero dependencies — standard library only.
 ```
 
 It is shell only and needs no install step. This client is for everywhere else: a laptop,
-a Makefile, a CI system that is not Actions, or Windows — which the action does not
+a Makefile, a CI system that is not Actions, or Windows, which the action does not
 support because it needs `sha256sum`.
 
 ## One name, two tools
 
 The console script installed here is `loremfile`, which is also the name of the
 repository's own development CLI (the one that generates and publishes the fixtures).
-They are never installed together — that tool lives only inside the project's toolchain
-image — but a contributor who installs both into one environment gets whichever was
+They are never installed together (that tool lives only inside the project's toolchain
+image), but a contributor who installs both into one environment gets whichever was
 installed last. The published package contains the client only: no generators, no
 validators, no uploader, no infrastructure code.
 

{loremfile-0.2.0 → loremfile-0.3.0}/src/loremfile.egg-info/SOURCES.txt

@@ -10,8 +10,10 @@ src/loremfile_client/__main__.py
 src/loremfile_client/api.py
 src/loremfile_client/cli.py
 src/loremfile_client/mcp.py
+src/loremfile_client/pytest_plugin.py
 src/loremfile_client/tools.json
 tests/test_commands.py
 tests/test_mcp.py
 tests/test_only_loremfile_dev.py
-tests/test_packaging.py
+tests/test_packaging.py
+tests/test_pytest_plugin.py

{loremfile-0.2.0 → loremfile-0.3.0}/src/loremfile.egg-info/entry_points.txt

@@ -1,2 +1,5 @@
 [console_scripts]
 loremfile = loremfile_client.cli:main
+
+[pytest11]
+loremfile = loremfile_client.pytest_plugin

{loremfile-0.2.0 → loremfile-0.3.0}/src/loremfile_client/__init__.py

@@ -1,3 +1,3 @@
 """A small client for loremfile.dev: download CC0 sample files and verify every byte."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

loremfile-0.3.0/src/loremfile_client/pytest_plugin.py

@@ -0,0 +1,110 @@
+"""The `loremfile` pytest fixture: a published file, verified, as a local path.
+
+pytest imports this module through the `pytest11` entry point in every run where the
+client is installed, whether or not a test asks for the fixture. So importing it does
+nothing: no network, no files, no hooks, no options. All the work happens the first time
+a test calls the fixture, and `tests/test_pytest_plugin.py` holds that as a test.
+
+Published files never change at their path, so a cached file and its cached manifest entry
+are final. The manifest is fetched again only for a path the cached copy does not list,
+and once that cache is filled a suite runs without the network.
+"""
+
+from __future__ import annotations
+
+import json
+import tempfile
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from loremfile_client import api
+
+
+class Files:
+    """One session's fetcher over a cache directory. Called with a path, returns a file."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = root
+        self.files = root / "files"
+        self.cached_manifest = root / "manifest.json"
+        self.entries: dict[str, dict[str, Any]] | None = None
+        self.refreshed = False
+        self.downloads = 0
+        self.ready: dict[str, Path] = {}
+
+    def __call__(self, path: str) -> Path:
+        if path in self.ready:
+            return self.ready[path]
+        entry = self.entry(path)
+        if not api.verify(entry, self.files).ok:
+            self.download(entry)
+        local = api.target(self.files, path)
+        self.ready[path] = local
+        return local
+
+    def entry(self, path: str) -> dict[str, Any]:
+        if self.entries is None:
+            self.entries = self.read_cached()
+        if path not in self.entries and not self.refreshed:
+            self.entries = self.refresh()
+        # `select` is the CLI's own refusal, so an unknown or removed path reads the same.
+        return api.select(list(self.entries.values()), paths=[path])[0]
+
+    def read_cached(self) -> dict[str, dict[str, Any]]:
+        try:
+            document = json.loads(self.cached_manifest.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return {}
+        return {e["path"]: e for e in api.active(document)}
+
+    def refresh(self) -> dict[str, dict[str, Any]]:
+        document = api.manifest()
+        self.refreshed = True
+        try:  # noqa: SIM105 - contextlib would be a new import for one line
+            self.write_cached(document)
+        except OSError:
+            pass  # only the next session pays: this one has the document in memory
+        return {e["path"]: e for e in api.active(document)}
+
+    def write_cached(self, document: dict[str, Any]) -> None:
+        """Written beside its final name and renamed, so a parallel worker never reads half."""
+        self.root.mkdir(parents=True, exist_ok=True)
+        handle = tempfile.NamedTemporaryFile(  # noqa: SIM115 - closed by the `with` below
+            "w", dir=self.root, suffix=".part", delete=False, encoding="utf-8"
+        )
+        partial = Path(handle.name)
+        try:
+            with handle:
+                json.dump(document, handle)
+            partial.replace(self.cached_manifest)
+        finally:
+            partial.unlink(missing_ok=True)
+
+    def download(self, entry: dict[str, Any]) -> None:
+        if self.downloads:
+            api.pace()
+        self.downloads += 1
+        try:
+            api.download(entry, self.files, force=True)
+        except OSError:
+            # On Windows the final rename fails while another xdist worker has the file
+            # open. If that worker already put the verified bytes there, they are ours too.
+            if not api.verify(entry, self.files).ok:
+                raise
+
+
+@pytest.fixture(scope="session")
+def loremfile(
+    pytestconfig: pytest.Config, tmp_path_factory: pytest.TempPathFactory
+) -> Callable[[str], Path]:
+    """loremfile(path) -> Path: a loremfile.dev file, checked against its published SHA-256.
+
+    Cached in .pytest_cache, so each file is downloaded once; `--cache-clear` starts over.
+    """
+    # `-p no:cacheprovider` removes the attribute itself; a file then lasts one session.
+    cache = getattr(pytestconfig, "cache", None)
+    root = cache.mkdir("loremfile") if cache is not None else tmp_path_factory.mktemp("loremfile")
+    return Files(root)

{loremfile-0.2.0 → loremfile-0.3.0}/tests/test_only_loremfile_dev.py

@@ -110,10 +110,16 @@ def test_the_client_imports_nothing_but_the_standard_library() -> None:
     }
     imported: set[str] = set()
     for source in PACKAGE.glob("*.py"):
+        found: set[str] = set()
         for node in ast.walk(ast.parse(source.read_text(encoding="utf-8"))):
             if isinstance(node, ast.Import):
-                imported |= {alias.name.split(".")[0] for alias in node.names}
+                found |= {alias.name.split(".")[0] for alias in node.names}
             elif isinstance(node, ast.ImportFrom) and node.module and node.level == 0:
-                imported.add(node.module.split(".")[0])
+                found.add(node.module.split(".")[0])
+        # The one exemption, by name: only pytest imports the plugin, so pytest is present.
+        if source.name == "pytest_plugin.py":
+            assert "pytest" in found, "the exemption names a module that no longer needs it"
+            found.discard("pytest")
+        imported |= found
     assert imported, "empty-set control: the scan found the imports"
     assert imported <= allowed, imported - allowed

{loremfile-0.2.0 → loremfile-0.3.0}/tests/test_packaging.py

@@ -46,6 +46,13 @@ def test_the_console_script_is_the_client_entry_point() -> None:
     assert "loremfile = loremfile_client.cli:main" in text
 
 
+def test_the_wheel_registers_the_pytest_plugin() -> None:
+    with zipfile.ZipFile(wheel()) as archive:
+        entry_points = next(n for n in archive.namelist() if n.endswith("entry_points.txt"))
+        text = archive.read(entry_points).decode()
+    assert "[pytest11]\nloremfile = loremfile_client.pytest_plugin" in text
+
+
 def test_the_wheel_carries_the_mcp_tool_surface() -> None:
     """mcp.py reads tools.json at import; a wheel without it is a server that cannot start."""
     source = CLIENT / "src" / "loremfile_client" / "tools.json"

loremfile-0.3.0/tests/test_pytest_plugin.py

@@ -0,0 +1,234 @@
+"""The `loremfile` fixture: what it returns, when it needs the network, and that it is inert.
+
+pytest loads the plugin in every run where the client is installed, so the property that
+matters most is the one nobody would notice breaking: a suite that never asks for the
+fixture must not pay for it. The subprocess tests below run a real pytest with the socket
+module refused, and each has a control that watches the same guard catch the plugin.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+from importlib import metadata
+from pathlib import Path
+from typing import Any
+
+import pytest
+from loremfile_client import api, pytest_plugin
+from loremfile_client.pytest_plugin import Files
+
+from conftest import BODIES, Handler
+
+SMALL = BODIES["pdf/small.pdf"]
+
+
+class NetworkUsed(Exception):
+    pass
+
+
+def no_network(path: str) -> Any:
+    raise NetworkUsed(path)
+
+
+def test_a_file_arrives_verified_at_a_path(server: str, tmp_path: Path) -> None:
+    local = Files(tmp_path / "cache")("pdf/small.pdf")
+    assert local == (tmp_path / "cache" / "files" / "pdf" / "small.pdf").resolve()
+    assert local.read_bytes() == SMALL
+
+
+def test_a_filled_cache_needs_no_network(
+    server: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    Files(tmp_path / "cache")("pdf/small.pdf")
+    monkeypatch.setattr(api, "_open", no_network)
+    assert Files(tmp_path / "cache")("pdf/small.pdf").read_bytes() == SMALL
+
+
+def test_control_an_empty_cache_does_need_it(
+    server: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(api, "_open", no_network)
+    with pytest.raises(NetworkUsed):
+        Files(tmp_path / "cache")("pdf/small.pdf")
+
+
+def test_a_path_the_cached_copy_lacks_refreshes_it_once(
+    server: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    root = tmp_path / "cache"
+    Files(root)("pdf/small.pdf")
+    # A cached copy from before svg/square.svg was published.
+    document = json.loads((root / "manifest.json").read_text(encoding="utf-8"))
+    document["fixtures"] = [e for e in document["fixtures"] if e["path"] != "svg/square.svg"]
+    (root / "manifest.json").write_text(json.dumps(document), encoding="utf-8")
+    fetched: list[int] = []
+    real = api.manifest
+    monkeypatch.setattr(api, "manifest", lambda **kw: fetched.append(1) or real(**kw))
+
+    get = Files(root)
+    assert get("svg/square.svg").read_bytes() == BODIES["svg/square.svg"]
+    with pytest.raises(api.Refused, match=re.escape("not published: pdf/not-real.pdf")):
+        get("pdf/not-real.pdf")
+    assert fetched == [1]
+
+
+@pytest.mark.parametrize("path", ["pdf/not-real.pdf", "pdf/withdrawn.pdf"])
+def test_an_unpublished_or_removed_path_is_refused(server: str, tmp_path: Path, path: str) -> None:
+    with pytest.raises(api.Refused, match=re.escape(f"not published: {path}")):
+        Files(tmp_path / "cache")(path)
+
+
+def test_bytes_that_do_not_match_are_never_returned(server: str, tmp_path: Path) -> None:
+    Handler.corrupt = {"pdf/small.pdf"}
+    with pytest.raises(api.Mismatch):
+        Files(tmp_path / "cache")("pdf/small.pdf")
+    assert not (tmp_path / "cache" / "files" / "pdf" / "small.pdf").exists()
+
+
+def test_a_cached_file_that_changed_is_fetched_again(server: str, tmp_path: Path) -> None:
+    root = tmp_path / "cache"
+    Files(root)("pdf/small.pdf").write_bytes(b"edited by someone")
+    assert Files(root)("pdf/small.pdf").read_bytes() == SMALL
+
+
+def test_a_rename_another_worker_won_is_accepted(
+    server: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    real = api.download
+
+    def raced(entry: dict[str, Any], dest: Path, *, force: bool = False) -> api.Result:
+        real(entry, dest, force=force)
+        raise PermissionError("the file is open in another process")
+
+    monkeypatch.setattr(api, "download", raced)
+    assert Files(tmp_path / "cache")("pdf/small.pdf").read_bytes() == SMALL
+
+
+def test_control_a_failed_rename_with_nothing_verified_is_raised(
+    server: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    def failed(entry: dict[str, Any], dest: Path, *, force: bool = False) -> api.Result:
+        raise PermissionError("the file is open in another process")
+
+    monkeypatch.setattr(api, "download", failed)
+    with pytest.raises(PermissionError):
+        Files(tmp_path / "cache")("pdf/small.pdf")
+
+
+def test_the_plugin_adds_no_hooks() -> None:
+    assert [name for name in vars(pytest_plugin) if name.startswith("pytest_")] == []
+    assert callable(pytest_plugin.loremfile), "control: the module read is the plugin"
+
+
+def test_the_client_imports_without_pytest() -> None:
+    """The CLI and the MCP server must not drag pytest in; the control proves the probe sees it."""
+    probe = (
+        "import sys, {}; print(sorted(m for m in sys.modules"
+        " if m.split('.')[0] == 'pytest' or m.endswith('pytest_plugin')))"
+    )
+    client = subprocess.run(  # noqa: S603 - fixed argv, no shell
+        [sys.executable, "-c", probe.format("loremfile_client.cli, loremfile_client.mcp")],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    assert client.stdout.strip() == "[]"
+    control = subprocess.run(  # noqa: S603 - fixed argv, no shell
+        [sys.executable, "-c", probe.format("loremfile_client.pytest_plugin")],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    assert "'pytest'" in control.stdout
+
+
+# --- a real pytest, in a subprocess, with the network refused --------------------------
+
+#: Installed before pytest starts, so it is in place when the plugin is imported.
+GUARD = """
+import json, os, socket, sys
+attempts = []
+def refuse(*args, **kwargs):
+    attempts.append(repr(args[:2]))
+    raise OSError("network refused by the test")
+socket.socket.connect = refuse
+socket.create_connection = refuse
+socket.getaddrinfo = refuse
+import pytest
+code = pytest.main(sys.argv[1:])
+with open(os.environ["GUARD_LOG"], "w") as log:
+    json.dump(attempts, log)
+sys.exit(code)
+"""
+
+USES_IT = """
+def test_it(loremfile):
+    assert loremfile("pdf/small.pdf").read_bytes() == b"%PDF-1.4 pretend\\n"
+"""
+
+IGNORES_IT = """
+def test_it(request):
+    assert request.config.pluginmanager.get_plugin("loremfile") is not None
+"""
+
+
+def entry_point_installed() -> None:
+    """Fails rather than skips: an inertness test that quietly does not run proves nothing."""
+    found = [ep.value for ep in metadata.entry_points(group="pytest11") if ep.name == "loremfile"]
+    assert found == ["loremfile_client.pytest_plugin"], (
+        f"pytest11 entry points named loremfile: {found}; install the client's wheel first"
+    )
+
+
+def pytest_run(
+    where: Path, source: str, *args: str, guarded: bool = False
+) -> tuple[int, list[str]]:
+    entry_point_installed()
+    (where / "pytest.ini").write_text("[pytest]\n", encoding="utf-8")
+    (where / "test_it.py").write_text(source, encoding="utf-8")
+    log = where / "attempts.json"
+    env = {**os.environ, "GUARD_LOG": str(log)}
+    env.pop("PYTEST_DISABLE_PLUGIN_AUTOLOAD", None)
+    env.pop("PYTEST_ADDOPTS", None)
+    if guarded:
+        command = [sys.executable, "-c", GUARD, "-q", *args]
+    else:
+        command = [sys.executable, "-m", "pytest", "-q", *args]
+    done = subprocess.run(  # noqa: S603 - fixed argv, no shell
+        command, cwd=where, env=env, capture_output=True, text=True, timeout=120, check=False
+    )
+    attempts = json.loads(log.read_text(encoding="utf-8")) if guarded else []
+    assert done.returncode in (0, 1), done.stdout + done.stderr
+    return done.returncode, attempts
+
+
+def test_a_suite_that_never_asks_for_it_pays_nothing(tmp_path: Path) -> None:
+    code, attempts = pytest_run(tmp_path, IGNORES_IT, guarded=True)
+    assert (code, attempts) == (0, [])
+    assert not (tmp_path / ".pytest_cache" / "d" / "loremfile").exists()
+
+
+def test_control_the_guard_sees_the_plugin_reach_out(server: str, tmp_path: Path) -> None:
+    code, attempts = pytest_run(tmp_path, USES_IT, guarded=True)
+    assert code == 1
+    assert attempts, "the guard recorded nothing, so the test above could not have failed"
+
+
+def test_once_the_cache_is_filled_the_suite_runs_offline(server: str, tmp_path: Path) -> None:
+    assert pytest_run(tmp_path, USES_IT) == (0, [])
+    # Where the README tells CI to cache, and the path the inertness test finds absent.
+    cached = tmp_path / ".pytest_cache" / "d" / "loremfile" / "files" / "pdf" / "small.pdf"
+    assert cached.read_bytes() == SMALL
+    assert pytest_run(tmp_path, USES_IT, guarded=True) == (0, [])
+    # Control: the same offline run with the cache cleared has to reach out, and fails.
+    code, attempts = pytest_run(tmp_path, USES_IT, "--cache-clear", guarded=True)
+    assert code == 1
+    assert attempts
+
+
+def test_without_the_cache_provider_it_still_works(server: str, tmp_path: Path) -> None:
+    assert pytest_run(tmp_path, USES_IT, "-p", "no:cacheprovider") == (0, [])