Skip to content

Commit 0bc5b37

Browse files
committed
test: capture-driven parse→rebuild and dumper round trips (#1202)
- tests/protocols/test_capture_roundtrip_runtime.py: every layer of every frame in examples/captures/ (payload chain plus IPv6 extension headers) rebuilds from its info, from info.to_dict(), and Info survives to_dict/from_dict; every capture rebuilds whole, byte for byte. - tests/dumpkit/test_capture_dump_runtime.py: format='pcap' is byte-identical to its input; json/plist/tree are deterministic and hold one section per record or block; json frames carry every Info key and the protocol chain; plistlib reads the plist dump. - Known failures sit in LAYER_GAPS (#1446), DICT_GAPS (#1447) and KNOWN_FAILURES (#1448), asserted in both directions; the existing plistlib skip in tests/integration/test_output_formats.py cites #1448. Both modules are fixture tier (integration job): 4 + 6 tests, 24 s and 33 s, peak RSS 223 and 279 MiB.
1 parent 78991b7 commit 0bc5b37

3 files changed

Lines changed: 488 additions & 1 deletion

File tree

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# -*- coding: utf-8 -*-
2+
"""Every output format over every sample capture: exact, complete, deterministic.
3+
4+
GitHub issue #1202. For each capture in :file:`examples/captures/`:
5+
6+
* ``format='pcap'`` writes a file byte-identical to its input. PCAP-NG input is
7+
left out, because PCAP output of it is refused by design.
8+
* ``json``, ``plist`` and ``tree`` each write the same bytes on a second run.
9+
* each of the three holds one section per record or block of the input, counted
10+
from the file itself rather than from the extractor, and in the same order;
11+
* a ``json`` frame section carries every top-level key of the frame's
12+
:class:`~pcapkit.corekit.infoclass.Info` and its protocol chain.
13+
14+
Deeper key-by-key completeness is not asserted: options dump as one mapping per
15+
entry (#1263), so the rendering legitimately differs from ``Info.to_dict()``.
16+
17+
A failing check is listed in :data:`KNOWN_FAILURES` with its tracking issue and
18+
must still fail in the recorded way; every other check must pass.
19+
20+
The module reads generated captures, so it belongs to the fixture-dependent tier.
21+
22+
"""
23+
from __future__ import annotations
24+
25+
import importlib.util
26+
import json
27+
import os
28+
import pathlib
29+
import plistlib
30+
import struct
31+
import tempfile
32+
import unittest
33+
import warnings
34+
import xml.etree.ElementTree as ET
35+
from typing import TYPE_CHECKING, NamedTuple
36+
37+
from tests._support import close_extractor, reimport_once_per_class, time_limit
38+
from tests._tiers import SAMPLE_ROOT
39+
40+
if TYPE_CHECKING:
41+
from typing import Any, Optional
42+
43+
RUNTIME_DEPS = ('tbtrim', 'aenum', 'chardet', 'dictdumper')
44+
HAS_RUNTIME = all(importlib.util.find_spec(name) is not None for name in RUNTIME_DEPS)
45+
46+
#: Whole seconds one sweep over every capture may take. The slowest takes ~15.
47+
SWEEP_TIMEOUT = 300
48+
49+
50+
class Gap(NamedTuple):
51+
"""One check that fails today, and the defect that stops it."""
52+
53+
#: Tracking issue, or :data:`None` while the defect is not yet filed.
54+
issue: 'Optional[int]'
55+
#: Name of the exception the check raises.
56+
status: 'str'
57+
#: The defect and how to reproduce it.
58+
defect: 'str'
59+
60+
61+
#: Every check that fails today, by test method; each applies to every capture.
62+
KNOWN_FAILURES = {
63+
'test_plist_dump_reads_back_through_plistlib': Gap(
64+
1448, 'AttributeError',
65+
"dictdumper/plist.py:278 writes each timestamp as '%Y-%m-%dT%H:%M:%S.%fZ', "
66+
'and a property list <date> has no fractional part, so plistlib.load '
67+
"raises AttributeError: 'NoneType' object has no attribute 'groupdict' on "
68+
"every capture's first frame. Repro: extract(fin='in.pcap', fout='o', "
69+
"format='plist'); plistlib.load(open('o.plist', 'rb')). Also skipped, "
70+
'citing #1448, in tests/integration/test_output_formats.py PlistRoundTripTests.',
71+
),
72+
}
73+
74+
75+
def captures(pcapng: 'bool' = True) -> 'list[str]':
76+
"""Every capture under :data:`~tests._tiers.SAMPLE_ROOT`, by file name."""
77+
return sorted(path.name for path in SAMPLE_ROOT.iterdir()
78+
if path.suffix in ('.pcap', '.cap') or (pcapng and path.suffix == '.pcapng'))
79+
80+
81+
def section_count(raw: 'bytes') -> 'int':
82+
"""Sections a dump of ``raw`` should hold, counted from the file's own framing.
83+
84+
PCAP: the global header plus one per record. PCAP-NG: one per block.
85+
86+
"""
87+
count, offset = 0, 0
88+
if raw[:4] == b'\x0a\x0d\x0d\x0a':
89+
endian = '<'
90+
while offset < len(raw):
91+
if raw[offset:offset + 4] == b'\x0a\x0d\x0d\x0a':
92+
endian = '<' if raw[offset + 8:offset + 12] == b'\x4d\x3c\x2b\x1a' else '>'
93+
offset += struct.unpack(f'{endian}I', raw[offset + 4:offset + 8])[0]
94+
count += 1
95+
return count
96+
endian = '<' if raw[:4] in (b'\xd4\xc3\xb2\xa1', b'\x4d\x3c\xb2\xa1') else '>'
97+
offset, count = 24, 1
98+
while offset + 16 <= len(raw):
99+
offset += 16 + struct.unpack(f'{endian}I', raw[offset + 8:offset + 12])[0]
100+
count += 1
101+
return count
102+
103+
104+
def sections(fmt: 'str', path: 'str') -> 'list[str]':
105+
"""Top-level section names of a ``fmt`` dump, read without pcapkit."""
106+
if fmt == 'json':
107+
with open(path, encoding='utf-8') as file:
108+
return list(json.load(file))
109+
if fmt == 'plist':
110+
# ElementTree, not plistlib, which cannot read the dump at all; see
111+
# :data:`KNOWN_FAILURES`.
112+
root = ET.parse(path).getroot()
113+
return [key.text or '' for key in root[0].findall('key')]
114+
with open(path, encoding='utf-8') as file:
115+
return [line.rstrip('\n') for line in file if line.strip() and not line[0].isspace()]
116+
117+
118+
@unittest.skipUnless(HAS_RUNTIME, 'runtime dependencies not installed')
119+
class CaptureDumpTests(unittest.TestCase):
120+
"""Pin what each writer makes of every capture, by reading the file back."""
121+
122+
def setUp(self) -> None:
123+
reimport_once_per_class(self)
124+
self.tmpdir = tempfile.TemporaryDirectory() # pylint: disable=consider-using-with
125+
self.addCleanup(self.tmpdir.cleanup)
126+
quiet = warnings.catch_warnings()
127+
quiet.__enter__() # pylint: disable=unnecessary-dunder-call
128+
self.addCleanup(quiet.__exit__, None, None, None)
129+
warnings.simplefilter('ignore')
130+
131+
def dump(self, name: 'str', fmt: 'str', stem: 'str', **kwargs: 'Any') -> 'tuple[Any, str]':
132+
"""Extract capture ``name`` to ``stem`` as ``fmt``; return the extractor and output path."""
133+
from pcapkit import extract
134+
135+
out = os.path.join(self.tmpdir.name, stem)
136+
extractor = extract(fin=str(SAMPLE_ROOT / name), fout=out, format=fmt, **kwargs)
137+
self.addCleanup(close_extractor, extractor)
138+
return extractor, extractor.output
139+
140+
def test_pcap_output_is_byte_identical_to_its_input(self) -> None:
141+
with time_limit(SWEEP_TIMEOUT):
142+
for name in captures(pcapng=False):
143+
_, path = self.dump(name, 'pcap', f'{name}.out.pcap', store=False, extension=False)
144+
with self.subTest(capture=name), open(path, 'rb') as file:
145+
self.assertEqual(file.read(), (SAMPLE_ROOT / name).read_bytes())
146+
147+
def assertDumpIsCompleteAndDeterministic(self, fmt: 'str') -> None:
148+
"""Two runs agree byte for byte, with one section per record or block."""
149+
with time_limit(SWEEP_TIMEOUT):
150+
for name in captures():
151+
outputs = [self.dump(name, fmt, f'{name}.{run}', store=False)[1] for run in (1, 2)]
152+
first, second = (pathlib.Path(path).read_bytes() for path in outputs)
153+
names = sections(fmt, outputs[0])
154+
with self.subTest(capture=name, format=fmt):
155+
self.assertEqual(first, second, 'the second run wrote different bytes')
156+
self.assertEqual(len(names), section_count((SAMPLE_ROOT / name).read_bytes()))
157+
self.assertEqual(len(set(names)), len(names), 'a section name repeats')
158+
# Every format names the same sections in the same order.
159+
if fmt != 'json':
160+
json_path = self.dump(name, 'json', f'{name}.ref', store=False)[1]
161+
self.assertEqual(names, sections('json', json_path))
162+
163+
def test_json_dump_is_complete_and_deterministic(self) -> None:
164+
self.assertDumpIsCompleteAndDeterministic('json')
165+
166+
def test_plist_dump_is_complete_and_deterministic(self) -> None:
167+
self.assertDumpIsCompleteAndDeterministic('plist')
168+
169+
def test_tree_dump_is_complete_and_deterministic(self) -> None:
170+
self.assertDumpIsCompleteAndDeterministic('tree')
171+
172+
def test_json_frame_sections_carry_every_info_key_and_the_chain(self) -> None:
173+
with time_limit(SWEEP_TIMEOUT):
174+
for name in captures():
175+
extractor, path = self.dump(name, 'json', f'{name}.frames', store=True)
176+
with open(path, encoding='utf-8') as file:
177+
report = json.load(file)
178+
for number, frame in enumerate(extractor.frame, start=1):
179+
section = report[f'Frame {number}']
180+
with self.subTest(capture=name, frame=number):
181+
self.assertEqual(list(section), list(frame.info.to_dict()))
182+
self.assertEqual(section['protocols'], str(frame.protochain))
183+
184+
def test_plist_dump_reads_back_through_plistlib(self) -> None:
185+
gap = KNOWN_FAILURES.get('test_plist_dump_reads_back_through_plistlib')
186+
with time_limit(SWEEP_TIMEOUT):
187+
for name in captures():
188+
_, path = self.dump(name, 'plist', f'{name}.lib', store=False)
189+
with self.subTest(capture=name), open(path, 'rb') as file:
190+
try:
191+
report = plistlib.load(file)
192+
except Exception as exc: # pylint: disable=broad-except
193+
got = type(exc).__name__
194+
else:
195+
got = 'OK'
196+
self.assertEqual(list(report), sections('plist', path))
197+
self.assertEqual(got, 'OK' if gap is None else gap.status)
198+
199+
200+
if __name__ == '__main__':
201+
unittest.main()

‎tests/integration/test_output_formats.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@ class PlistRoundTripTests(EndToEndTestCase):
119119
"""
120120

121121
@unittest.skip('blocked on dictdumper writing <date> values with fractional seconds, '
122-
'which plistlib rejects (dictdumper/plist.py:278)')
122+
'which plistlib rejects (dictdumper/plist.py:278, #1448)')
123123
def test_plist_report_round_trips_through_plistlib(self) -> None:
124124
"""A ``plist`` report should be readable by :func:`plistlib.load`.
125125

0 commit comments

Comments
 (0)