Skip to content

test: correct docstrings on the #572 truncated-option tests - #580

Merged
JarryShaw merged 2 commits into
mainfrom
docs/572-followup-docstring-corrections
Sep 21, 2026
Merged

JarryShaw merged 2 commits into
mainfrom
docs/572-followup-docstring-corrections

Conversation

@JarryShaw

Copy link
Copy Markdown
Owner

Summary

Follow-up to #578, which merged before its cross-review finished. The
independent review (on a different model, per this repo's practice for
agent-raised changes) found the two new tests — TCPUDPUnitTests and
IPv4UnitTests' test_a_truncated_option_still_parses_its_declared_length
— correct in every constructed byte, assertion, and pass/fail outcome, but
flagged several factual errors in their docstring prose:

  • 0x4f is TCP's Option.Reserved_79, not an "unassigned" kind (the
    UnassignedOption schema class handles it, but the wire code itself is
    reserved, not unassigned).
  • The IPv4 docstring attributed the option_padding rewind-and-reread-as-
    padding mechanism to "OptionField.unpack never returns for a well-formed HOPOPT header with an SMF_DPD option #431 machinery" inside OptionField.unpack. It is
    actually in Schema.unpack (pcapkit/protocols/schema/schema.py:890),
    added by Fix seven PCAP-NG parser defects (#341-#347) #371, and predates OptionField.unpack never returns for a well-formed HOPOPT header with an SMF_DPD option #431 — OptionField.unpack never returns for a well-formed HOPOPT header with an SMF_DPD option #431's own contribution to
    OptionField.unpack is only the post-break progress check, which performs
    no rewind in this case.
  • The IPv4 docstring claimed declaring an 8-octet option area would trip
    IPv4's stricter length-sum check "before the accommodation under test is
    ever reached." That's mechanically false: the accommodation does run (the
    short data field is read and left-padded), the outer
    _read_ipv4_options check just discards that result afterwards, once its
    loop over the parsed options finishes.
  • The TCP docstring attributed the "sizes by what it consumed, not the
    declared length" measurement to OptionField.unpack; it is actually
    TCP._read_tcp_options itself (pcapkit/protocols/transport/tcp.py:698,
    counter += len(schema)).
  • The TCP docstring's opening sentence ("cut short mid-option") was wrong for
    the TCP fixture specifically — nothing in it is truncated (hdr_len == len(raw), and the test asserts a full round-trip); the over-declaration
    is internal to the option, not the capture. Reworded. Left the IPv4
    opening line as-is, since that fixture genuinely is short (28 physical vs
    36 declared octets).
  • The TCP docstring's justification for checking length=32 alongside 12
    ("the fix would reject both identically") argued for one case being
    sufficient rather than explaining why both are checked; replaced with the
    actual distinction — the pad width scales with the declared length (24
    zero octets vs 4).
  • Switched both tests' fixed 6-octet trailing literal from bytes([0xaa, ...]) to bytes.fromhex('aabbccddeeff'), matching the surrounding files'
    idiom.

No assertion, constructed byte, or test outcome changes here — this is a
docstring-only correction. Both tests still pass, and both still fail
against a reject-on-any-shortfall guard in FieldBase.unpack with the
FieldValueError text quoted in #572.

Test plan

  • pytest tests/protocols/transport/test_tcp_udp_unit.py tests/protocols/internet/test_ipv4_unit.py -k test_a_truncated_option_still_parses_its_declared_length -q — 2 passed, 2 subtests passed, unchanged from before this correction
  • Full unit tier on this branch: pytest -q --ignore=tests/integration --ignore-glob='*_runtime.py' --ignore-glob='*_regression.py'

An independent cross-review of #578 (which merged before the review
finished) found the two new tests correct in every constructed byte,
assertion, and pass/fail outcome, but flagged several prose errors in
their docstrings:

- 0x4f is TCP's Option.Reserved_79, not an "unassigned" kind (the
  UnassignedOption *schema class* handles it, but the wire code itself
  is reserved) -- fixed the TCP docstring's wording.
- The IPv4 docstring attributed the option_padding rewind-and-reread-
  as-padding mechanism to "#431 machinery" inside OptionField.unpack.
  It is actually in Schema.unpack (schema.py:890), added by #371, and
  predates #431; #431's own contribution to OptionField.unpack is only
  the post-break progress check, which performs no rewind here.
- The IPv4 docstring claimed declaring an 8-octet option area would
  trip IPv4's stricter length-sum check "before the accommodation
  under test is ever reached." The accommodation does run -- the short
  data field is read and left-padded -- the outer check just discards
  that result afterwards. Fixed to say so.
- The TCP docstring attributed the "sizes by what it consumed, not by
  the declared length" measurement to OptionField.unpack; it is
  TCP._read_tcp_options itself (tcp.py:698, `len(schema)`).
- The TCP docstring's opening line ("cut short mid-option") was wrong
  for the TCP fixture specifically: nothing is truncated there
  (hdr_len == len(raw), and the test asserts a full round-trip); the
  over-declaration is internal to the option, not the capture. Reworded.
  Left the IPv4 opening line as-is, since that fixture genuinely is short.
- The TCP docstring's justification for checking length=32 alongside 12
  ("the fix would reject both identically") argued for one case being
  enough; replaced with the actual distinction (pad width scales with
  the declared length: 24 zero octets vs 4).
- Switched both tests' fixed 6-octet trailing literal to bytes.fromhex(),
  matching the surrounding files' idiom.

No assertion, constructed byte, or test outcome changes. Both tests
still pass; both still fail against a reject-on-any-shortfall guard
with the FieldValueError text quoted in #572.

Build/test: unit tier (pytest -q --ignore=tests/integration
--ignore-glob='*_runtime.py' --ignore-glob='*_regression.py') green
on this branch, same as before the docstring changes.
@JarryShaw
JarryShaw merged commit 0503e6f into main Sep 21, 2026
24 checks passed
@JarryShaw
JarryShaw deleted the docs/572-followup-docstring-corrections branch September 21, 2026 19:03
@JarryShaw JarryShaw added the test Pull requests that add or correct tests (test: subject prefix) label Sep 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

test Pull requests that add or correct tests (test: subject prefix)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant