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

tests/_dependency_gates.py

@@ -120,8 +120,8 @@
 #: (#1732), and :file:`cron-vendor.yml` runs ``tests/const`` and ``tests/vendor``
 #: over a freshly crawled tree, where a failure discards modules rather than
 #: failing the job (#1853); neither is read here. Other workflows install
-#: ``.[all]`` somewhere -- a docs build, a conda recipe, the lint pass, and the
-#: release packaging workflow -- and none of them invokes the suite;
+#: ``.[all]`` somewhere -- a docs build, a conda recipe, and the lint pass --
+#: and none of them invokes the suite;
 #: :file:`python-compatibility.yml` installs a bare ``.`` and only compiles and
 #: imports, and :file:`codeql-analysis.yml` installs nothing explicitly at all
 #: (CodeQL's own autobuild step). That is exactly why this module keys on *jobs that
@@ -621,7 +621,7 @@ class AmbiguousProvider(NamedTuple):
 def requirement_key(text: 'str') -> 'Requirement':
     """Split one requirement string into a :class:`Requirement`.
 
-    Deliberately not a PEP 508 parser: it handles the four things the extras in
+    Deliberately not a PEP 508 parser: it handles what the extras in
     :file:`pyproject.toml` actually use -- a name, optional bracketed extras, an
     optional version specifier, and an optional ``;`` marker -- and normalises
     the name per PEP 503 so ``pcap-ct``, ``pcap_ct`` and ``PCAP.CT`` compare
@@ -1040,11 +1040,11 @@ def _flag_imports(path: 'pathlib.Path') -> 'dict[str, str]':
 def flag_requirements() -> 'dict[tuple[str, str], frozenset[str]]':
     """``(module, flag)`` -> the modules that flag needs importable.
 
-    Resolved per file rather than per flag name, which matters for exactly one
-    flag and matters a lot: ``HAS_RUNTIME`` names the core dependencies in
-    every module but one, and in
+    Resolved per file rather than per flag name, because one flag name can
+    probe different modules in different files: ``HAS_RUNTIME`` names the core
+    dependencies in most modules, and in
     :file:`tests/foundation/engines/test_runtime_engines.py` it names those
-    plus ``dpkt``, ``scapy`` and ``pyshark``. Keyed on the name alone, that one
+    plus ``dpkt``, ``scapy`` and ``pyshark``. Keyed on the name alone, one
     module's requirements would be demanded of every other module that gates on
     it, or they would excuse it.
 
@@ -1420,7 +1420,7 @@ def job_reaches(job: 'Job', gate: 'Gate') -> 'bool':
     that gate skip, so one selected test is enough for the install line to
     matter. A node ID naming one method of a class therefore does reach a
     class-level gate on that class, even though the class's other methods run
-    elsewhere; :data:`Gap` counts gate decorators rather than methods, so nothing
+    elsewhere; :class:`Gap` counts gate decorators rather than methods, so nothing
     is double-counted by that. The strict reading -- "every test the gate guards"
     -- would be the unsafe one, because it would let a job that runs one gated
     test out of three off the hook entirely.

tests/_tiers.py

@@ -14,9 +14,9 @@
                                     :file:`*_runtime.py`, :file:`*_regression.py`
 =================================== ==========================================
 
-The unit tier has to pass on a fresh clone with nothing installed but
-``pip install -e '.[test]'``, which is exactly how the ``test`` job of
-:file:`.github/workflows/unit-tests.yml` runs it -- see
+The unit tier has to pass on a fresh clone with no capture generated, which is
+exactly how the ``test`` job of :file:`.github/workflows/unit-tests.yml` runs
+it -- see
 :data:`UNIT_TIER_SELECTION` for the selection it uses. The fixture-dependent
 tier runs only after :file:`examples/generators/make_samples.py` has rebuilt
 :file:`examples/captures/`, so it may read any capture it likes.
@@ -278,9 +278,11 @@
 #: :func:`is_project_pin`.
 PROJECT_PINS_DIR = 'project'
 #: The project pins' selector, verbatim from the workflows: the ``project-tests``
-#: job runs what it prints, and every ``test`` and ``experimental`` leg passes each
-#: path as an ``--ignore``. Asked at run time, as :data:`FIXTURE_TIER_SELECTOR` is,
-#: so neither workflow can drift from :func:`is_project_pin`.
+#: job runs what it prints, and the ``latest`` leg of ``test`` passes each path as
+#: an ``--ignore``. Every other ``test`` leg and every ``experimental`` leg leaves
+#: the pins out through :data:`LATEST_TIER_SELECTOR`, since every pin is
+#: ``LATEST``. Asked at run time, as :data:`FIXTURE_TIER_SELECTOR` is, so no
+#: workflow can drift from :func:`is_project_pin`.
 PROJECT_PINS_SELECTOR = (
     'python -c "from tests._tiers import project_pin_paths; '
     'print(\' \'.join(project_pin_paths()))"'

tests/cli/test_main.py

@@ -386,9 +386,9 @@ def test_help_strings_have_no_known_slips(self) -> None:
     def test_layer_and_protocol_reach_the_extractor(self) -> None:
         """``-L``/``-P`` are forwarded under the names ``Extractor`` reads.
 
-        The CLI half of GH-356. The forwarding was always correct -- it is the
-        core that dropped the limits -- so this pins the contract that made it
-        correct: ``Extractor`` takes ``layer=`` and ``protocol=``, and the CLI
+        The CLI half of GH-356. The defect there is the core dropping the
+        limits, not the forwarding, so this pins the contract the forwarding
+        rests on: ``Extractor`` takes ``layer=`` and ``protocol=``, and the CLI
         must not invent its own spelling for either.
 
         """

tests/conftest.py

@@ -77,7 +77,7 @@
 _pinned_snapshot = None  # type: Optional[dict[str, types.ModuleType]]
 
 #: What :func:`pytest_sessionstart` imports before the pin: the package, plus the
-#: two app-type registries it loads on first use rather than with itself (GitHub
+#: app-type registries it loads on first use rather than with itself (GitHub
 #: issue #1538). See that hook for why the registries cannot be left out.
 WARM_MODULES = ('pcapkit', 'pcapkit.const.reg.apptype.tcp', 'pcapkit.const.reg.apptype.udp')
 
@@ -163,7 +163,7 @@ def pytest_sessionstart(session: 'pytest.Session') -> 'None':
     that imports the library and nothing else leaves the region exactly as it
     found it, so there is nothing to put back.
 
-    The two lazily loaded app-type registries in :data:`WARM_MODULES` are
+    The lazily loaded app-type registries in :data:`WARM_MODULES` are
     imported here too, and that is for correctness rather than speed. Left out
     of the pin, they were dropped from :data:`sys.modules` after whichever test
     first loaded them, while the package kept the classes it had already bound
@@ -692,7 +692,7 @@ def _tier_guard_reader_hold() -> 'Iterator[None]':
 
 @pytest.fixture(autouse=True)
 def _tier_guard_reader_lock(request: 'pytest.FixtureRequest') -> 'Iterator[None]':
-    """Hold the probe/scan mutex shared, for every unit-tier test but the two
+    """Hold the probe/scan mutex shared, for every unit-tier test but those
     that self-manage it.
 
     See :func:`_tier_guard_lock` for the race this closes. Deciding by

tests/const/test_const_apptype_split_unit.py

@@ -43,8 +43,8 @@
 def _dunder_sample(registry: 'type') -> 'list':
     """The members of ``registry`` the byte-identity sweep formats, in row order.
 
-    GitHub issue #1062. Sweeping every member ran a subtest per member, and
-    per-test coverage contexts found only a few distinct arc sets among them:
+    GitHub issue #1062. Sweeping every member runs a subtest per member, and
+    per-test coverage contexts find only a few distinct arc sets among them:
     ``repr`` and ``str``, each with and without an ``(aliases: ...)`` suffix --
     the registry, the port and the service name never change which code runs.
     So the sample keeps every member that carries an alias (the suffix branch),
@@ -144,8 +144,8 @@ def test_a_member_is_still_an_apptype(self) -> None:
 
         # One service on two transports is two members, not one shared object --
         # they carry the same name and differ in which registry they belong to,
-        # which since GitHub issue #806 is what ``proto`` says. It named the whole
-        # IANA set on both of them before, so the two compared equal.
+        # which is what ``proto`` says (GitHub issue #806). Guards against it
+        # naming the whole IANA set on both, under which the two compare equal.
         self.assertIsNot(TCP.http, UDP.http)
         self.assertEqual(TCP.http.svc, UDP.http.svc)
         self.assertNotEqual(TCP.http.proto, UDP.http.proto)
@@ -1271,8 +1271,8 @@ def test_no_lookup_call_site_in_the_library_builds_a_composite_proto(self) -> No
                 apptype_registry.UDP.__proto__[65210] = previous
 
     def test_the_new_dunders_are_byte_identical_to_the_percent_form(self) -> None:
-        """GitHub issue #798: ``AppType``'s ``__new__``/``__repr__``/``__str__`` moved
-        from ``%`` formatting to f-strings, and ``__new__``'s format sets every
+        """GitHub issue #798: ``AppType``'s ``__new__``/``__repr__``/``__str__`` format
+        with f-strings rather than ``%``, and ``__new__``'s format sets every
         real member's underlying :class:`~aenum.StrEnum` value -- a far larger
         blast radius than an error path. It is checked on a deterministic
         sample rather than member by member, because one f-string formats every
@@ -1297,7 +1297,7 @@ def test_the_new_dunders_are_byte_identical_to_the_percent_form(self) -> None:
         :meth:`~unittest.TestCase.addCleanup`, but the population check below
         is only meaningful against a registry no other test has touched.
 
-        GitHub issue #807 grew ``repr``/``str`` an ``(aliases: ...)`` suffix
+        ``repr``/``str`` carry an ``(aliases: ...)`` suffix (GitHub issue #807)
         for a member that shares its port with another service in the same
         registry, so ``old_repr``/``old_str`` below append the identical
         suffix through ``member.aliases`` before comparing. ``old_value``
@@ -1349,10 +1349,11 @@ def test_every_member_renders_its_own_registrys_transport_protocol(self) -> None
 
         ``proto.name`` is folded into the member's underlying
         :class:`~aenum.StrEnum` *value* by ``__new__``, not merely into its display,
-        so retyping ``proto`` rewrites ``TCP.http.value`` from
-        ``'http [80 - tcp|udp|sctp]'`` to ``'http [80 - tcp]'``. ``_value_`` is the
-        live key in ``_value2member_map_``, which is why the retype has to happen in
-        the generated source rather than at runtime -- a member whose ``_value_``
+        so a single-transport ``proto`` makes ``TCP.http.value``
+        ``'http [80 - tcp]'`` where the whole IANA set would make it
+        ``'http [80 - tcp|udp|sctp]'``. ``_value_`` is the live key in
+        ``_value2member_map_``, which is why ``proto`` is set in the generated
+        source rather than at runtime -- a member whose ``_value_``
         were edited afterwards would no longer be reachable by its own value.
 
         Checked against the formula rather than against the member's own ``proto``:
@@ -1369,7 +1370,7 @@ def test_every_member_renders_its_own_registrys_transport_protocol(self) -> None
         modules declare (see :func:`_declared`), not against counts a vendor
         update moves (GitHub issue #1820).
 
-        GitHub issue #807 grew ``str``/``repr`` an ``(aliases: ...)`` suffix
+        ``str``/``repr`` carry an ``(aliases: ...)`` suffix (GitHub issue #807)
         for a member sharing its port with another service in this registry,
         so ``value``/``shown`` below grow the identical suffix through
         ``member.aliases`` before comparing. The lookup round-trip at the