xtr_webhook.testing ¶
Testing a parser against the payloads its sender actually posts.
A parser is only as trustworthy as the captures it has been shown, and those come from the sender: posted once, caught, kept. Keeping each in a file beside the events it must become turns adding a case into adding two files — nothing to register, nothing to write in the test — and leaves the payloads readable as what they are, byte for byte, which is what a signature is made over.
The helpers build their requests with xtr-http-message, which comes with this package, so there is nothing more to install.
ParserCase
dataclass
¶
A fixture pair as it was read off disk: what arrived, and what it must become.
A sender's payloads are the one thing a parser's test cannot invent — they come from the sender, captured once and kept. So a case is a record of two files rather than something assembled in a test, and it is frozen because the files it came from are: a case changed half way through a run would leave the failure naming a payload that was never on disk.
Attributes:
-
expected(RemoteEvent | list[RemoteEvent]) –What the parser must read out of
payload— one event, or every event when the capture carried a batch of them. -
id(str) –Where the capture lies under the directory it was found in, as a slash-separated relative path, extension and all. It names the case in the test report, so a failure says which file to look at.
-
payload(bytes) –The bytes of the capture, exactly as they lie on disk. A signature is made over the bytes that arrived, so nothing decodes, re-encodes or reformats them on the way here.
assert_parses
async
¶
assert_parses(parser: RequestParserInterface, case: ParserCase, *, secret: str = '', headers: Mapping[str, str] | None = None, method: str = 'POST') -> None
Post case to parser and check it read what the case expects.
The request is built from the capture's bytes under
Content-Type: application/json, which is what the matchers of a JSON
sender's parser look for. A sender that signs its webhooks needs its
signature headers too, and the secret they were made with::
await assert_parses(AcmeParser(), case, secret=SECRET, headers=signed(case.payload))
Parameters:
-
parser(RequestParserInterface) –The parser under test.
-
case(ParserCase) –The pair to drive it over.
-
secret(str, default:'') –What the parser checks the sender's signature against.
-
headers(Mapping[str, str] | None, default:None) –Headers to send alongside the content type — a signature, a timestamp, whatever the sender puts on its webhooks. An entry named
Content-Typereplaces the default. -
method(str, default:'POST') –The method the sender posts with.
Raises:
-
AssertionError–When the parser read something other than
case.expected. Raised rather than asserted so the check holds however the test suite is run, and carries both sides so the difference is in the failure itself.
parser_cases ¶
Read every fixture pair under fixtures_dir into a case.
A pair is a capture — *.<extension>, the bytes as the sender posted
them — and a *.py beside it naming EXPECTED: one
:class:~xtr_remote_event.RemoteEvent, or a list of them for a capture
that carried a batch. The expectation is Python rather than data so it can
say exactly which events, with the types the parser will produce, instead
of a second format to agree on.
The directory is walked recursively, so captures can be grouped by the event kind they belong to, and the result is sorted by id, so a run reports the same order whatever order the file system hands the files back in.
Parameters:
-
fixtures_dir(Path) –The directory the captures lie under.
-
extension(str, default:'json') –What the captures are named with, without the dot. A sender whose captures are not JSON is kept in files named for what they are.
Returns:
-
list[ParserCase]–One case per capture, sorted by id.
Raises:
-
InvalidArgumentError–When a capture has no expectation file beside it, or that file names no
EXPECTED. Either is a pair half-added, and silently skipping it would leave a payload nothing ever checks.