Skip to content

Commit 7a97658

Browse files
authored
docs(tests): seventh whole-repo pass over the tests (#1103) (#2267)
Full read of every docstring and comment under tests/. - protocols, vendor, const, integration: stale claims (RFC sections, byte counts, the L2TP field mapping, vendor-extra installs, HIP_COPIES), the 24-bit PRI value, change-relative narratives and counts. - project: claims checked against the workflows, util scripts, docs and pyproject; the #1967 parity tests describe the inline shell form as the reference the scripts must match. - corekit, foundation, utilities, toolkit, dumpkit, interface, cli, root modules: stale claims, "without the fix" restatements, counts, issue references as #NNN, never-released names dropped from docstrings. Docstrings and comments only; test names, assertion messages and string literals are unchanged.
1 parent 5fd197f commit 7a97658

271 files changed

Lines changed: 1925 additions & 1913 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎tests/_dependency_gates.py‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -120,8 +120,8 @@
120120
#: (#1732), and :file:`cron-vendor.yml` runs ``tests/const`` and ``tests/vendor``
121121
#: over a freshly crawled tree, where a failure discards modules rather than
122122
#: failing the job (#1853); neither is read here. Other workflows install
123-
#: ``.[all]`` somewhere -- a docs build, a conda recipe, the lint pass, and the
124-
#: release packaging workflow -- and none of them invokes the suite;
123+
#: ``.[all]`` somewhere -- a docs build, a conda recipe, and the lint pass --
124+
#: and none of them invokes the suite;
125125
#: :file:`python-compatibility.yml` installs a bare ``.`` and only compiles and
126126
#: imports, and :file:`codeql-analysis.yml` installs nothing explicitly at all
127127
#: (CodeQL's own autobuild step). That is exactly why this module keys on *jobs that
@@ -621,7 +621,7 @@ class AmbiguousProvider(NamedTuple):
621621
def requirement_key(text: 'str') -> 'Requirement':
622622
"""Split one requirement string into a :class:`Requirement`.
623623
624-
Deliberately not a PEP 508 parser: it handles the four things the extras in
624+
Deliberately not a PEP 508 parser: it handles what the extras in
625625
:file:`pyproject.toml` actually use -- a name, optional bracketed extras, an
626626
optional version specifier, and an optional ``;`` marker -- and normalises
627627
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]':
10401040
def flag_requirements() -> 'dict[tuple[str, str], frozenset[str]]':
10411041
"""``(module, flag)`` -> the modules that flag needs importable.
10421042
1043-
Resolved per file rather than per flag name, which matters for exactly one
1044-
flag and matters a lot: ``HAS_RUNTIME`` names the core dependencies in
1045-
every module but one, and in
1043+
Resolved per file rather than per flag name, because one flag name can
1044+
probe different modules in different files: ``HAS_RUNTIME`` names the core
1045+
dependencies in most modules, and in
10461046
:file:`tests/foundation/engines/test_runtime_engines.py` it names those
1047-
plus ``dpkt``, ``scapy`` and ``pyshark``. Keyed on the name alone, that one
1047+
plus ``dpkt``, ``scapy`` and ``pyshark``. Keyed on the name alone, one
10481048
module's requirements would be demanded of every other module that gates on
10491049
it, or they would excuse it.
10501050
@@ -1420,7 +1420,7 @@ def job_reaches(job: 'Job', gate: 'Gate') -> 'bool':
14201420
that gate skip, so one selected test is enough for the install line to
14211421
matter. A node ID naming one method of a class therefore does reach a
14221422
class-level gate on that class, even though the class's other methods run
1423-
elsewhere; :data:`Gap` counts gate decorators rather than methods, so nothing
1423+
elsewhere; :class:`Gap` counts gate decorators rather than methods, so nothing
14241424
is double-counted by that. The strict reading -- "every test the gate guards"
14251425
-- would be the unsafe one, because it would let a job that runs one gated
14261426
test out of three off the hook entirely.

‎tests/_tiers.py‎

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

‎tests/cli/test_main.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -386,9 +386,9 @@ def test_help_strings_have_no_known_slips(self) -> None:
386386
def test_layer_and_protocol_reach_the_extractor(self) -> None:
387387
"""``-L``/``-P`` are forwarded under the names ``Extractor`` reads.
388388
389-
The CLI half of GH-356. The forwarding was always correct -- it is the
390-
core that dropped the limits -- so this pins the contract that made it
391-
correct: ``Extractor`` takes ``layer=`` and ``protocol=``, and the CLI
389+
The CLI half of GH-356. The defect there is the core dropping the
390+
limits, not the forwarding, so this pins the contract the forwarding
391+
rests on: ``Extractor`` takes ``layer=`` and ``protocol=``, and the CLI
392392
must not invent its own spelling for either.
393393
394394
"""

‎tests/conftest.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@
7777
_pinned_snapshot = None # type: Optional[dict[str, types.ModuleType]]
7878

7979
#: What :func:`pytest_sessionstart` imports before the pin: the package, plus the
80-
#: two app-type registries it loads on first use rather than with itself (GitHub
80+
#: app-type registries it loads on first use rather than with itself (GitHub
8181
#: issue #1538). See that hook for why the registries cannot be left out.
8282
WARM_MODULES = ('pcapkit', 'pcapkit.const.reg.apptype.tcp', 'pcapkit.const.reg.apptype.udp')
8383

@@ -163,7 +163,7 @@ def pytest_sessionstart(session: 'pytest.Session') -> 'None':
163163
that imports the library and nothing else leaves the region exactly as it
164164
found it, so there is nothing to put back.
165165
166-
The two lazily loaded app-type registries in :data:`WARM_MODULES` are
166+
The lazily loaded app-type registries in :data:`WARM_MODULES` are
167167
imported here too, and that is for correctness rather than speed. Left out
168168
of the pin, they were dropped from :data:`sys.modules` after whichever test
169169
first loaded them, while the package kept the classes it had already bound
@@ -692,7 +692,7 @@ def _tier_guard_reader_hold() -> 'Iterator[None]':
692692

693693
@pytest.fixture(autouse=True)
694694
def _tier_guard_reader_lock(request: 'pytest.FixtureRequest') -> 'Iterator[None]':
695-
"""Hold the probe/scan mutex shared, for every unit-tier test but the two
695+
"""Hold the probe/scan mutex shared, for every unit-tier test but those
696696
that self-manage it.
697697
698698
See :func:`_tier_guard_lock` for the race this closes. Deciding by

‎tests/const/test_const_apptype_split_unit.py‎

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -43,8 +43,8 @@
4343
def _dunder_sample(registry: 'type') -> 'list':
4444
"""The members of ``registry`` the byte-identity sweep formats, in row order.
4545
46-
GitHub issue #1062. Sweeping every member ran a subtest per member, and
47-
per-test coverage contexts found only a few distinct arc sets among them:
46+
GitHub issue #1062. Sweeping every member runs a subtest per member, and
47+
per-test coverage contexts find only a few distinct arc sets among them:
4848
``repr`` and ``str``, each with and without an ``(aliases: ...)`` suffix --
4949
the registry, the port and the service name never change which code runs.
5050
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:
144144

145145
# One service on two transports is two members, not one shared object --
146146
# they carry the same name and differ in which registry they belong to,
147-
# which since GitHub issue #806 is what ``proto`` says. It named the whole
148-
# IANA set on both of them before, so the two compared equal.
147+
# which is what ``proto`` says (GitHub issue #806). Guards against it
148+
# naming the whole IANA set on both, under which the two compare equal.
149149
self.assertIsNot(TCP.http, UDP.http)
150150
self.assertEqual(TCP.http.svc, UDP.http.svc)
151151
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
12711271
apptype_registry.UDP.__proto__[65210] = previous
12721272

12731273
def test_the_new_dunders_are_byte_identical_to_the_percent_form(self) -> None:
1274-
"""GitHub issue #798: ``AppType``'s ``__new__``/``__repr__``/``__str__`` moved
1275-
from ``%`` formatting to f-strings, and ``__new__``'s format sets every
1274+
"""GitHub issue #798: ``AppType``'s ``__new__``/``__repr__``/``__str__`` format
1275+
with f-strings rather than ``%``, and ``__new__``'s format sets every
12761276
real member's underlying :class:`~aenum.StrEnum` value -- a far larger
12771277
blast radius than an error path. It is checked on a deterministic
12781278
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:
12971297
:meth:`~unittest.TestCase.addCleanup`, but the population check below
12981298
is only meaningful against a registry no other test has touched.
12991299
1300-
GitHub issue #807 grew ``repr``/``str`` an ``(aliases: ...)`` suffix
1300+
``repr``/``str`` carry an ``(aliases: ...)`` suffix (GitHub issue #807)
13011301
for a member that shares its port with another service in the same
13021302
registry, so ``old_repr``/``old_str`` below append the identical
13031303
suffix through ``member.aliases`` before comparing. ``old_value``
@@ -1349,10 +1349,11 @@ def test_every_member_renders_its_own_registrys_transport_protocol(self) -> None
13491349
13501350
``proto.name`` is folded into the member's underlying
13511351
:class:`~aenum.StrEnum` *value* by ``__new__``, not merely into its display,
1352-
so retyping ``proto`` rewrites ``TCP.http.value`` from
1353-
``'http [80 - tcp|udp|sctp]'`` to ``'http [80 - tcp]'``. ``_value_`` is the
1354-
live key in ``_value2member_map_``, which is why the retype has to happen in
1355-
the generated source rather than at runtime -- a member whose ``_value_``
1352+
so a single-transport ``proto`` makes ``TCP.http.value``
1353+
``'http [80 - tcp]'`` where the whole IANA set would make it
1354+
``'http [80 - tcp|udp|sctp]'``. ``_value_`` is the live key in
1355+
``_value2member_map_``, which is why ``proto`` is set in the generated
1356+
source rather than at runtime -- a member whose ``_value_``
13561357
were edited afterwards would no longer be reachable by its own value.
13571358
13581359
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
13691370
modules declare (see :func:`_declared`), not against counts a vendor
13701371
update moves (GitHub issue #1820).
13711372
1372-
GitHub issue #807 grew ``str``/``repr`` an ``(aliases: ...)`` suffix
1373+
``str``/``repr`` carry an ``(aliases: ...)`` suffix (GitHub issue #807)
13731374
for a member sharing its port with another service in this registry,
13741375
so ``value``/``shown`` below grow the identical suffix through
13751376
``member.aliases`` before comparing. The lookup round-trip at the

0 commit comments

Comments
 (0)