coulomb/email-connect
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

EMAIL-WP-0005 T05/T06: evidence realism and harness documentation
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 2s
Details

Browse source 
Adds harness.deliver_raw() to inject crafted .eml fixtures through the harness,
so they pick up the real Received: headers an MTA adds, and
harness.inject_maildir() as the byte-exact offline counterpart.

tests/test_evidence_realism.py asserts all ten recognized evidence classes
after passing through a real MTA, proves MTA delivery does not change which
evidence is produced, and covers Maildir injection offline.

Documents what no local server can honestly produce -- provider-generated DSNs,
real 4xx deferral and retry, ISP feedback loops, provider suppression behavior,
MX acceptance as distinct from provider acceptance -- and names SES simulator
addresses as the staging path. That tier stays out of the test run because it
needs real credentials.

Adds docs/test-harness-tutorial.md covering the three test tiers and the
start/send/scan/assert/reset walkthrough, with an explicit
assertable/not-assertable list so the evidence ceiling is stated where tests
get written. Adds a Maildir section to the mailbox report tutorial.

Completes EMAIL-WP-0005. Suite: 85 passed with the harness up, 64 passed +
21 skipped with it down.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
tegwick 2026-08-14 02:00:17 +02:00
parent e9609b4024
commit 3497ca88bf
7 changed files with 431 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

26
docs/mailbox-report-tutorial.md
View file

@ -50,6 +50,32 @@ export EMAIL_CONNECT_IMAP_PASSWORD='app-password'
IMAP scans select the folder read-only and fetch messages with `BODY.PEEK[]`.
The scanner does not mark messages seen, move messages, or delete messages.
## 3b. Scan A Maildir Instead
When mail is delivered locally — an MTA writing to disk, or the test harness —
point the scanner at the Maildir root instead of an IMAP server:
```yaml
mailbox:
protocol: maildir
folder: INBOX
source:
maildir_dir: /var/mail/returns/Maildir
```
The directory is the mailbox root containing `new/` and `cur/`; both are read.
No credentials are involved. Message identity is the Maildir unique name without
its `:2,FLAGS` suffix, so a message stays the same message when the MTA or a
mail client moves it from `new/` to `cur/`.
Like IMAP, Maildir scans are read-only: `mark_seen` is rejected, and the scanner
never moves, flags, or deletes a message. `include_seen: false` skips messages
already flagged `S`.
For a local Maildir or IMAP server to test against, see
`docs/test-harness-tutorial.md`.
## 4. Add Expected Recipients
Expected recipients are optional. A newline-separated file can look like: