Summary
The filter tests in opendmarc/tests/ have no documentation beyond the Lua scripts and shell wrappers themselves. The test names (t-verify-nodata, t-verify-unspec, etc.) are cryptic, and there is no index or README explaining what scenario each test covers, what preconditions it requires, or what a failure means.
This makes it difficult to:
- Understand at a glance which tests cover which features
- Diagnose a CI failure without reading through Lua
- Know which tests require optional features (
--with-spf, --enable-filter-tests)
- Onboard contributors who want to add new tests
What would help
A README in opendmarc/tests/ with a table covering each test:
- What scenario it exercises
- What domain/IP it uses and why
- Any configure-time prerequisites (
--with-spf, etc.)
- What a pass/fail looks like
Even the in-script comments are inconsistent — t-verify-authservid-jobid.lua has a clear two-line description; t-verify-unspec.lua just says "unspecified protocol family test" with no explanation of what "unspec" means to the filter.
Summary
The filter tests in
opendmarc/tests/have no documentation beyond the Lua scripts and shell wrappers themselves. The test names (t-verify-nodata,t-verify-unspec, etc.) are cryptic, and there is no index or README explaining what scenario each test covers, what preconditions it requires, or what a failure means.This makes it difficult to:
--with-spf,--enable-filter-tests)What would help
A
READMEinopendmarc/tests/with a table covering each test:--with-spf, etc.)Even the in-script comments are inconsistent —
t-verify-authservid-jobid.luahas a clear two-line description;t-verify-unspec.luajust says "unspecified protocol family test" with no explanation of what "unspec" means to the filter.