docs(tests): fourth whole-repo pass over tests (#1103)

tests/_dependency_gates.py

@@ -45,9 +45,9 @@
 
 One thing this deliberately does not model, recorded here rather than left to
 be discovered: **environment markers.** ``PyPCAPFile = [ "pypcapfile;
-python_version < '3.12'" ]`` resolves to nothing on four of the five supported
-legs (3.12-3.15), so an install line carrying that extra would satisfy this module
-while only 3.11 and the KTLO legs ran the tests. :func:`requirement_key`
+python_version < '3.12'" ]`` resolves to nothing on every leg from 3.12 up,
+so an install line carrying that extra would satisfy this module while only the
+legs below 3.12 ran the tests. :func:`requirement_key`
 strips the marker and :func:`provided_by` ignores it; the marker text is kept
 on :class:`Requirement` so a diagnostic can say so.
 
@@ -195,7 +195,7 @@
     # generated constants on a schedule rather than as a check -- so excluding
     # this flag would have left `make isort`'s verdict unverified everywhere,
     # which is the #766 complaint. Cost does not argue the other way either:
-    # isort is a pure-Python wheel and all four Makefile lines together measure
+    # isort is a pure-Python wheel and the Makefile's isort lines together measure
     # about 1.5s, against the ~238 MB and licence questions that keep ``NGAP``
     # out of ``all``.
     'isort': ('isort',),
@@ -1153,7 +1153,7 @@ def module_flag_requirements(path: 'pathlib.Path') -> 'dict[str, frozenset[str]]
 
     Public for the same reason :func:`module_gates` is: the shapes it has to
     understand are best pinned against source written to exercise them one at a
-    time, rather than against whichever of them the suite happens to use today.
+    time, rather than against whichever of them the suite happens to use.
 
     """
     try:
@@ -1535,7 +1535,7 @@ def pytest_jobs(workflow: 'Optional[pathlib.Path]' = None) -> 'tuple[Job, ...]':
         # `integration` job's names `fixture_tier_paths()`, so classifying on
         # the whole job section reads `gate` as an ignore-selection job and
         # credits it with reaching only the unit tier. Matching on the step name
-        # would work today and break the day a step is renamed.
+        # would work only until a step is renamed.
         steps = re.findall(r'(?ms)^      - name: [^\n]*\n(.*?)(?=^      - name:|\Z)', section)
         running = [step for step in steps if 'python -m pytest' in step]
         if len(running) != 1:

tests/_support.py

@@ -794,8 +794,8 @@ def restore_modules_after(test: 'unittest.TestCase',
     Registered **once per test** however many times this is called, and the
     snapshot kept is the first one -- the only one taken before any of the loads
     wrote anything. That is what lets :func:`bootstrap_core_modules` announce
-    itself and then make seven :func:`load_module` calls without registering
-    eight cleanups to eight successively more polluted snapshots.
+    itself and then make a run of :func:`load_module` calls without registering
+    a cleanup per call, each to a successively more polluted snapshot.
 
     Registered with :meth:`~unittest.TestCase.addCleanup` rather than done in a
     ``tearDown``, for the reasons :func:`isolate_modules` gives: it runs even
@@ -1008,7 +1008,7 @@ def purge_modules(prefixes: Iterable[str]) -> None:
     test. Take the two together rather than reading the paragraph above as a promise
     that a purge leaves no trace -- under a runner that loads no ``conftest``, it
     does. Measured on ``b337cdbc2``: ``python -m unittest discover -s tests/corekit``
-    fails 5 of that class's identity subtests, because ``test_module`` sorts first
+    fails that class's identity subtests, because ``test_module`` sorts first
     and purges, while the same file alone passes and :program:`pytest` -- the
     supported runner, and what :file:`.github/workflows/unit-tests.yml` invokes --
     passes either way.

tests/_tiers.py

@@ -74,9 +74,9 @@
 
 What neither catches, deliberately: a unit-tier module that opens a capture
 without going through :func:`~tests._support.sample_path` at all, e.g. by joining
-:file:`examples/captures/` and a name itself. No *unit-tier* module does this
-today -- :file:`tests/protocols/misc/test_pcapng_unit.py` was the last one and
-now reads ``sample_path('dhcp_big_endian.pcapng')`` inside the ``try``/``except
+:file:`examples/captures/` and a name itself. No *unit-tier* module does this:
+:file:`tests/protocols/misc/test_pcapng_unit.py` was the last one, and
+reads ``sample_path('dhcp_big_endian.pcapng')`` inside the ``try``/``except
 FileNotFoundError`` idiom :func:`explain` recommends. Only the *unit* tier is
 claimed there, deliberately: fixture-tier modules join the directory freely and
 are entitled to, e.g. :file:`tests/protocols/test_option_coverage_runtime.py`,
@@ -734,7 +734,7 @@ def skip_idiom_modules() -> 'tuple[pathlib.Path, ...]':
     :func:`audit_module` carries and for the same reason: a name computed at
     call time, e.g. ``sample_path(sample)`` in a parametrised loop, is
     invisible to a static pass. No module in the suite does this inside a
-    handled call today -- see ``test_every_handled_call_names_a_literal_capture``
+    handled call -- see ``test_every_handled_call_names_a_literal_capture``
     in :file:`tests/test_tier_guard.py`, which exists to catch the day one does,
     since such a call would silently drop out of this function's result and
     its fixture-backed coverage would quietly stop running anywhere.
@@ -771,12 +771,12 @@ def _enclosing_scope(tree: 'ast.Module', lineno: 'int') -> 'Optional[tuple[Optio
     carry that context as it goes. "Most tightly" is decided by span, so a
     helper function defined inside a test method and containing the line in
     question would win over the test method itself; nothing in this suite's
-    skip idiom does that today, but the rule is stated so a future one is
+    skip idiom does that, but the rule is stated so a future one is
     handled the same way :func:`sample_path_calls` already treats nesting.
 
     Returns:
         :data:`None` if no function definition contains ``lineno`` at all --
-        a module-level call, which does not happen in this suite today.
+        a module-level call, which does not happen in this suite.
 
     """
     best = None  # type: Optional[tuple[Optional[str], str, int]]
@@ -822,8 +822,8 @@ def skip_idiom_test_ids() -> 'tuple[str, ...]':
 
     Falls back to the *module* path when a handled call cannot be resolved to
     one enclosing function -- :func:`_enclosing_scope` returns :data:`None` for
-    a module-level call, which is not a shape this suite's skip idiom uses
-    today, but a fallback that still runs the file is safer than one that
+    a module-level call, which is not a shape this suite's skip idiom uses,
+    but a fallback that still runs the file is safer than one that
     drops the call's coverage entirely.
 
     Returns:

tests/conftest.py

@@ -1,7 +1,11 @@
 # -*- coding: utf-8 -*-
 """Suite-wide :program:`pytest` configuration.
 
-Holds three things. The first is :func:`restore_module_table`, the guard that
+Besides session hooks documented where they are defined -- the warm import
+and coverage flush in :func:`pytest_sessionstart` and
+:func:`pytest_sessionfinish`, and the timer release in
+:func:`pytest_timeout_cancel_timer` -- it holds the following. The first is
+:func:`restore_module_table`, the guard that
 puts the :mod:`pcapkit` region of :data:`sys.modules` back after every test; see
 its own docstring for why it is here rather than left to each test file.
 

tests/const/test_const_apptype_split_unit.py

@@ -669,7 +669,7 @@ def test_every_transport_named_span_is_claimed_by_one_registry(self) -> None:
         :mod:`pcapkit.vendor.reg.apptype.apptype` stops emitting the test -- and
         it returns silently, because a shadowed branch is unreachable rather than
         wrong. This asserts the invariant over every branch instead of over the two
-        spans that happen to collide today: a branch minting a member for a named
+        spans that happen to collide: a branch minting a member for a named
         transport protocol is claimed by that registry, and one minting for
         ``undefined`` claims nothing, since IANA's unassigned and reserved markers
         belong to whichever registry was asked.

tests/const/test_const_enum_builtin_parity.py

@@ -432,11 +432,17 @@ def test_the_exception_is_not_an_in_library_one(self) -> None:
         """Explicitly *not* ``EnumError``, and explicitly not loud.
 
         :class:`~pcapkit.utilities.exceptions.BaseError` logs at CRITICAL from
-        its constructor, so it fires even for an exception that is caught and
-        discarded -- which the ``except ValueError`` fallback in every generated
-        ``get()`` does on purpose. A guard raising a
+        its constructor unless it is quiet, so it fires even for an exception
+        that is caught and discarded. The base
+        :meth:`~pcapkit.corekit.enum.EnumLookup.get` constructs its lookup inside
+        a ``_CaughtByCaller(ValueError)`` block (#1845), which quiets a
+        :exc:`ValueError` subclass there, but a direct ``cls(value)`` caught by
+        its caller has no such block: a guard raising a
         :class:`~pcapkit.utilities.exceptions.BaseError` subclass would log once
-        per discarded default.
+        per value discarded that way. And
+        :class:`~pcapkit.utilities.exceptions.EnumError`, not being a
+        :exc:`ValueError`, would escape its ``except ValueError`` fallback
+        altogether.
         """
         from pcapkit.utilities.exceptions import BaseError, EnumError