Skip to content

Commit 1f3c2ac

Browse files
committed
docs(tests): state protocol, schema and misc tests' behaviour without change-relative narrative (#1103)
Rewrite comments and docstrings in tests/protocols/ (top level), tests/protocols/schema/ and tests/protocols/misc/ so they state the behaviour under test and the defect it guards against, rather than "now", "used to", "before the fix" or "on the unfixed tree". Comments and docstrings only; the AST with docstrings stripped is unchanged.
1 parent 6df74a6 commit 1f3c2ac

62 files changed

Lines changed: 493 additions & 488 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/protocols/misc/pcap/test_frame_endian_runtime.py‎

Lines changed: 10 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,18 @@
44
Classic PCAP declares its byte order in the magic number of the global header,
55
and the four fields of every record header -- ``ts_sec``, ``ts_usec``,
66
``incl_len`` and ``orig_len`` -- are written in that order rather than in the
7-
reading host's. Nothing in this suite read a big-endian ``.pcap`` before, because
8-
no such capture existed here: every fixture was little-endian, so on a
9-
little-endian runner a reader that ignored the file's declared order and used
10-
:data:`sys.byteorder` produced exactly the right answer.
7+
reading host's. Little-endian fixtures alone cannot show whether that order is
8+
honoured: on a little-endian runner, a reader that ignores the file's declared
9+
order and uses :data:`sys.byteorder` produces exactly the right answer.
1110
12-
That is what GitHub issue #605 was.
11+
This guards against GitHub issue #605, where
1312
:meth:`Frame.unpack <pcapkit.protocols.misc.pcap.frame.Frame.unpack>` seeded the
14-
order under the key ``bytesorder``, while ``byteorder_callback`` -- then in
15-
:file:`pcapkit/protocols/schema/misc/pcap/frame.py`, now in
16-
:file:`pcapkit/corekit/fields/byteorder.py` -- reads ``byteorder``, so the
13+
order under the key ``bytesorder``, while ``byteorder_callback``
14+
(:file:`pcapkit/corekit/fields/byteorder.py`) reads ``byteorder``, so the
1715
``.get()`` never found the key and always fell back to the host's order -- the
1816
sibling :meth:`Frame.pack <pcapkit.protocols.misc.pcap.frame.Frame.pack>`
19-
eleven lines earlier spelled it correctly, which is what marks it as a slip
20-
rather than a second key. Measured on the unfixed tree against
17+
spelled it correctly, which is what marks it as a slip rather than a second
18+
key. Measured without the fix against
2119
``big_endian.pcap``, whose first record really holds ``ts_sec=1500000000``,
2220
``ts_usec=123456`` and ``incl_len=74``: frame 1 came back with
2321
``ts_sec=3106905``, ``ts_usec=1088553216`` and ``incl_len=1241513984``, i.e.
@@ -179,7 +177,7 @@ def assertRecords(self, name: 'str', magic: 'bytes', endian: 'str',
179177
def test_big_endian_record_headers_are_read_in_the_files_byte_order(self) -> None:
180178
"""#605: ``a1 b2 c3 d4``, microsecond timestamps.
181179
182-
On the unfixed tree this raises ``ValueError: read length must be
180+
Without the fix this raises ``ValueError: read length must be
183181
non-negative or -1`` before reaching any assertion: frame 1's swapped
184182
``incl_len`` of 1241513984 consumes the whole file, and the read that
185183
follows is handed a negative payload length.
@@ -203,7 +201,7 @@ def test_big_endian_nanosecond_record_headers_are_read_in_the_files_byte_order(s
203201
def test_little_endian_twin_is_unaffected(self) -> None:
204202
"""The control: the same three records in the little-endian container.
205203
206-
This passes on the unfixed tree too, and that is what it is for. It
204+
This passes without the fix too, and that is what it is for. It
207205
pins the expectations of the big-endian tests to a file whose byte
208206
order was never in question, so a failure there cannot be blamed on the
209207
records themselves being wrong.

‎tests/protocols/misc/pcap/test_frame_from_data_runtime.py‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
# -*- coding: utf-8 -*-
22
"""``Frame.from_data`` rebuilds a captured frame.
33
4-
GitHub issue #1126: :meth:`~pcapkit.protocols.protocol.ProtocolBase.from_data`
5-
took nothing but the data, so the ``num`` and ``header`` that
4+
This guards against GitHub issue #1126, where
5+
:meth:`~pcapkit.protocols.protocol.ProtocolBase.from_data` took nothing but the
6+
data, so the ``num`` and ``header`` that
67
:class:`~pcapkit.protocols.misc.pcap.frame.Frame` requires could not reach it,
7-
and every call raised :exc:`TypeError`. ``from_data`` now forwards extra
8-
keywords to the construction, so the caller passes both alongside the data.
8+
and every call raised :exc:`TypeError`. ``from_data`` forwards extra keywords to
9+
the construction, so the caller passes both alongside the data.
910
1011
The frames are read from :file:`examples/captures/in.pcap`, so this belongs to
1112
the runtime tier.

‎tests/protocols/misc/pcap/test_frame_incl_len_overrun_1541_unit.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
# -*- coding: utf-8 -*-
22
"""A PCAP record claiming more octets than its file holds warns, and is kept as captured.
33
4-
GitHub issue #1541. A record whose ``incl_len`` runs past the end of the file
5-
parsed silently. It is now reported the way the PCAP-NG reader reports a
4+
This guards against GitHub issue #1541, where a record whose ``incl_len`` runs
5+
past the end of the file parsed silently. It is reported the way the PCAP-NG
6+
reader reports a
67
captured length running past its block (#1405), and is kept as captured in the
78
same way: ``incl_len`` and ``cap_len`` stay as declared, the packet is the octets
89
present, and the frame rebuilds as exactly the octets read, from ``info`` and

‎tests/protocols/misc/pcap/test_frame_length_runtime.py‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@
33
44
Both readers that build a
55
:class:`~pcapkit.protocols.data.misc.pcap.frame.Frame` have to agree about which
6-
of the two wire fields lands in which attribute, and until GitHub issue #618 they
7-
did not: the classic-PCAP reader in
6+
of the two wire fields lands in which attribute. GitHub issue #618 is the
7+
defect where they did not: the classic-PCAP reader in
88
:mod:`pcapkit.protocols.misc.pcap.frame` wrote ``len=incl_len,
99
cap_len=orig_len`` while :func:`pcapkit.toolkit.pcapng.block2frame` wrote
1010
``len=original_len, cap_len=captured_len``. Exactly inverted, so ``frame.len``
@@ -31,12 +31,12 @@
3131
been truncated", which "SHOULD NOT be less than the Captured Packet Length". So
3232
neither format is the odd one out -- only the reader was.
3333
34-
Why it survived so long: **the two lengths are equal unless the snapshot length
34+
Why fixtures can miss it: **the two lengths are equal unless the snapshot length
3535
cut the frame short**, so a fixture without a truncated frame compares a value
36-
against itself and cannot tell the two assignments apart. There was no such
37-
fixture here until #614 added one. This module therefore leans on the two that
38-
exist, and asserts that they really are truncated before asserting anything
39-
about them -- a fixture regenerated into something untruncated fails
36+
against itself and cannot tell the two assignments apart. This module therefore
37+
leans on the two truncated fixtures (#614), and asserts that they really are
38+
truncated before asserting anything about them -- a fixture regenerated into
39+
something untruncated fails
4040
:meth:`PcapFrameLengthRuntimeTests.test_the_fixture_really_holds_a_truncated_frame`
4141
loudly rather than making everything below vacuous:
4242
@@ -226,7 +226,7 @@ def test_the_fixture_really_holds_a_truncated_frame(self) -> None:
226226
def test_len_is_the_on_wire_length_and_cap_len_the_captured_one(self) -> None:
227227
"""#618: the PCAP reader had these two the other way round.
228228
229-
On the unfixed tree the truncated frame comes back with ``len=96`` and
229+
Without the fix the truncated frame comes back with ``len=96`` and
230230
``cap_len=1200`` -- the captured length under the name that means
231231
on-wire, and vice versa -- so this fails on that frame in every fixture
232232
while passing on the two untruncated ones, which is exactly the shape of
@@ -283,9 +283,9 @@ def test_cap_len_counts_the_octets_the_frame_actually_carries(self) -> None:
283283
class PcapngFrameLengthRuntimeTests(unittest.TestCase):
284284
"""#618, on the PCAP-NG reader -- the one that was already right.
285285
286-
This is the control. It passes on the unfixed tree too, and that is what it
287-
is for: it pins the convention the PCAP reader was brought into line with, so
288-
a later change that "fixes" the disagreement from the other end fails here.
286+
This is the control. It passes without the fix too, and that is what it is
287+
for: it pins the convention the PCAP reader follows, so a change that
288+
"fixes" the disagreement from the other end fails here.
289289
290290
"""
291291

@@ -383,7 +383,7 @@ def setUp(self) -> None:
383383
def test_a_truncated_frame_reads_alike_whichever_container_it_came_from(self) -> None:
384384
"""One caller, two capture formats, one meaning per attribute.
385385
386-
On the unfixed tree the PCAP side reports ``len < cap_len`` and the
386+
Without the fix the PCAP side reports ``len < cap_len`` and the
387387
PCAP-NG side ``len > cap_len`` for the same kind of frame, and this fails
388388
on the first assertion of the pair.
389389
@@ -411,7 +411,7 @@ def test_a_truncated_frame_reads_alike_whichever_container_it_came_from(self) ->
411411
for frame in truncated:
412412
with self.subTest(cap_len=frame.cap_len):
413413
# the on-wire length is the larger of the two, in both formats.
414-
# This is the assertion #618 breaks: before the fix the PCAP
414+
# This is the assertion #618 breaks: without the fix the PCAP
415415
# frame reports 96 against 1200 and fails here, while the
416416
# PCAP-NG one reports 314 against 32 and passes
417417
self.assertGreater(frame.len, frame.cap_len)

‎tests/protocols/misc/pcap/test_frame_runtime.py‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -90,16 +90,15 @@ def test_extracted_frames_carry_their_own_record_bytes(self) -> None:
9090
self.assertEqual(bytes(frame), expected)
9191
self.assertEqual(frame.packet.header, expected[:16])
9292
self.assertEqual(frame.packet.payload, expected[16:])
93-
# the nested layer was always right -- it is parsed from the
94-
# schema's payload rather than from the frame's raw data -- so this
95-
# pins the two to each other, which is what was broken.
93+
# the nested layer is parsed from the schema's payload rather than
94+
# from the frame's raw data, so this pins the two to each other.
9695
#
9796
# Sliced by ``cap_len`` rather than by ``len``: the octets in the
98-
# file are the *captured* ones, and since #618 ``len`` is the on-wire
99-
# length, which for a truncated frame runs past the end of the
97+
# file are the *captured* ones, and ``len`` is the on-wire length
98+
# (#618), which for a truncated frame runs past the end of the
10099
# record. ``arp.pcap`` is not truncated, so the two are equal here
101-
# and this is a correctness fix rather than a behaviour change --
102-
# which is exactly why it needs stating.
100+
# and the choice changes no result -- which is exactly why it needs
101+
# stating.
103102
self.assertEqual(bytes(frame.payload), expected[16:16 + frame.info.cap_len])
104103

105104

‎tests/protocols/misc/pcap/test_frame_snaplen_zero_1385_unit.py‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
11
# -*- coding: utf-8 -*-
22
"""Building a PCAP frame under a zero snaplen keeps the whole packet.
33
4-
GitHub issue #1385: :meth:`Frame.make <pcapkit.protocols.misc.pcap.frame.Frame.make>`
5-
defaulted ``incl_len`` to ``min(len(packet), snaplen)``, so a global header with
6-
snaplen 0 produced a 16-octet record holding no packet data. The PCAP draft says
7-
snaplen "MUST NOT be zero" (draft-ietf-opsawg-pcap, section 4), and libpcap reads
8-
a zero value as the maximum for the link type (``pcapint_adjust_snapshot``), so
9-
a zero snaplen is now no limit, as it already is for PCAP-NG.
4+
This guards against GitHub issue #1385, where
5+
:meth:`Frame.make <pcapkit.protocols.misc.pcap.frame.Frame.make>` defaulted
6+
``incl_len`` to ``min(len(packet), snaplen)``, so a global header with snaplen 0
7+
produced a 16-octet record holding no packet data. The PCAP draft says snaplen
8+
"MUST NOT be zero" (draft-ietf-opsawg-pcap, section 4), and libpcap reads a zero
9+
value as the maximum for the link type (``pcapint_adjust_snapshot``), so a zero
10+
snaplen is no limit, as it is for PCAP-NG.
1011
1112
Every case builds its own octets and reads no capture. Classes are imported
1213
inside each test, after :func:`~tests._support.reimport_once_per_class`.

‎tests/protocols/misc/pcap/test_frame_trailing_bytes_1265_unit.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
# -*- coding: utf-8 -*-
22
"""A PCAP file ending in a partial record header stops cleanly at EOF.
33
4-
GitHub issue #1265: with fewer than sixteen octets left after the last record,
4+
This guards against GitHub issue #1265, where, with fewer than sixteen octets
5+
left after the last record,
56
:meth:`Frame.unpack <pcapkit.protocols.misc.pcap.frame.Frame.unpack>` parsed a
67
record header out of zero padding, and the payload read got a negative length
7-
(``ValueError: read length must be non-negative or -1``). A tail that short now
8+
(``ValueError: read length must be non-negative or -1``). A tail that short
89
raises :exc:`~pcapkit.utilities.exceptions.StreamEOFError`, which the extractor
910
treats as the end of the file, as it does for a truncated PCAP-NG block (#678).
1011

‎tests/protocols/misc/pcap/test_header_frame_unit.py‎

Lines changed: 9 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -219,8 +219,8 @@ class Other(Raw):
219219

220220
# ``register`` resolves a ``ModuleDescriptor`` before storing it,
221221
# so the entry above is already the plain ``Raw`` class, not the
222-
# descriptor -- passing ``Raw`` again would now be the same-object
223-
# no-op GitHub issue #718 added an identity guard for (see
222+
# descriptor -- passing ``Raw`` again would be the same-object
223+
# no-op covered by the identity guard for GitHub issue #718 (see
224224
# ``test_frame_register_stays_quiet_on_same_object_reregistration``).
225225
# A genuinely different class is needed to still warn here.
226226
with mock.patch('pcapkit.protocols.misc.pcap.frame.warn') as warn:
@@ -297,7 +297,7 @@ class Other(Raw):
297297
bad_time._file = io.BytesIO(b'')
298298
# Faked through frame.py's own binding of
299299
# :func:`pcapkit.utilities.datetime.fromtimestamp`, which it calls
300-
# instead of :meth:`datetime.datetime.fromtimestamp` since #2099.
300+
# instead of :meth:`datetime.datetime.fromtimestamp` (#2099).
301301
with mock.patch('pcapkit.protocols.misc.pcap.frame.fromtimestamp', side_effect=ValueError), \
302302
mock.patch.object(Frame, '_decode_next_layer',
303303
lambda self, info, proto=None, length=None, packet=None: info), \
@@ -326,9 +326,9 @@ class Other(Raw):
326326
def test_frame_register_stays_quiet_on_same_object_reregistration(self) -> None:
327327
"""GitHub issue #718: replaying a call with the identical class is a no-op.
328328
329-
Before the fix the guard fired on presence alone, so the *second* of
329+
Without the fix the guard fires on presence alone, so the *second* of
330330
two calls registering the exact same class under the exact same code
331-
warned about an overwrite that never happened. Matches the identity
331+
warns about an overwrite that never happens. Matches the identity
332332
guard :func:`register_protocol
333333
<pcapkit.foundation.registry.protocols.register_protocol>` already
334334
applies.
@@ -441,13 +441,11 @@ def test_frame_header_is_read_in_the_files_byte_order(self) -> None:
441441
442442
:meth:`Frame.unpack <pcapkit.protocols.misc.pcap.frame.Frame.unpack>`
443443
seeded the file's byte order under the key ``bytesorder``, where
444-
``byteorder_callback`` -- then in
445-
:file:`pcapkit/protocols/schema/misc/pcap/frame.py`, now in
446-
:file:`pcapkit/corekit/fields/byteorder.py` -- reads ``byteorder``,
447-
so the lookup always missed and always fell back to
444+
``byteorder_callback`` (:file:`pcapkit/corekit/fields/byteorder.py`)
445+
reads ``byteorder``, so the lookup always missed and always fell back to
448446
:data:`sys.byteorder`. On a little-endian host reading a little-endian
449-
capture that is the right answer by coincidence, which is why every
450-
fixture here passed; on a big-endian capture all four record-header
447+
capture that is the right answer by coincidence, so little-endian
448+
fixtures cannot catch it; on a big-endian capture all four record-header
451449
fields came back byte-swapped.
452450
453451
The capture is built here rather than read from

‎tests/protocols/misc/test_pcapng_captured_len_overrun_1405_unit.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
# -*- coding: utf-8 -*-
22
"""GitHub issue #1405: a captured length running past the block rebuilds byte-exactly.
33
4-
An Enhanced Packet Block whose ``captured_len`` runs past the block read that
5-
many octets as packet data: the trailing Block Total Length and whatever
6-
followed went with them, so a 36-octet block rebuilt as 40 or 41. The packet
7-
data is now bounded by the block, the padding and option area are sized from
4+
Without the fix, an Enhanced Packet Block whose ``captured_len`` runs past the
5+
block reads that many octets as packet data: the trailing Block Total Length and
6+
whatever follows go with them, so a 36-octet block rebuilds as 40 or 41. The
7+
packet data is bounded by the block, the padding and option area are sized from
88
the octets read, and the declared ``captured_len`` is kept, so the block rebuilds
99
as captured. The obsolete Packet Block has the same shape and the same fix.
1010

‎tests/protocols/misc/test_pcapng_dsb_secrets_overrun_1980_unit.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
# -*- coding: utf-8 -*-
22
"""GitHub issue #1980: a Decryption Secrets Block's secrets are bounded by the block.
33
4-
A Decryption Secrets Block whose ``secrets_length`` ran far past the block read
5-
that many octets as secrets: the trailing Block Total Length and the blocks after
6-
it went with them, and past the zero-pad ceiling the read raised
7-
:exc:`~pcapkit.utilities.exceptions.FieldValueError` from inside the block's
8-
schema, which ended the whole extraction. The secrets are now bounded by the
4+
Without the fix, a Decryption Secrets Block whose ``secrets_length`` runs far
5+
past the block reads that many octets as secrets: the trailing Block Total Length
6+
and the blocks after it go with them, and past the zero-pad ceiling the read
7+
raises :exc:`~pcapkit.utilities.exceptions.FieldValueError` from inside the
8+
block's schema, which ends the whole extraction. The secrets are bounded by the
99
block, as an Enhanced Packet Block's packet data is (#1405): the declared
1010
``secrets_length`` is kept, a :class:`~pcapkit.utilities.warnings.ProtocolWarning`
1111
reports the overrun, and extraction carries on to the next block.

0 commit comments

Comments
 (0)