pdftract/notes/bf-lpyhe-template.md

Assertion Message Template

Bead ID: bf-lpyhe
Template Version: 1.0
Date: 2026-07-06

Standard Template

All assertion messages should follow this structure:

"<Description of expected behavior>. \
Expected: <expected condition with specific value>. \
Found: <actual condition or observed value>. \
Why this matters: <rationale and reference to source of truth>."

Template Components

1. Description of Expected Behavior

• What: Clear, concise statement of what should happen
• Format: Present tense, descriptive
• Example: ".notdef should be recognized as an unmapped glyph name"

2. Expected Condition

• what: The exact expected state or return value
• Format: Expected: <function call> == <expected value> or Expected: <expected state>
• Example: Expected: is_unmapped_glyph_name(".notdef") == true

3. Found / Actual Condition

• What: What was actually observed or returned
• Format: Found: <actual value> or use placeholder {:?} for runtime values
• Example: Found: false or Found: {:?} (for format! macros)

4. Why This Matters (Context)

• What: Rationale linking the expectation to its source of truth
• Format: Reference to configuration files, specs, or design docs
• Example: Why this matters: .notdef is defined in build/unmapped-glyph-names.json as a standard PDF special glyph.

Template Examples by Assertion Type

Example 1: Unmapped Glyph Detection (Positive Case)

".notdef should be recognized as an unmapped glyph name. \
Expected: is_unmapped_glyph_name(\".notdef\") == true. \
Found: false. \
Why this matters: .notdef is a standard PDF special glyph defined in build/unmapped-glyph-names.json that should never appear in text extraction output."

Example 2: Normal Glyph Verification (Negative Case)

"Normal glyph 'A' should not be recognized as unmapped. \
Expected: is_unmapped_glyph_name(\"A\") == false. \
Found: true. \
Why this matters: Letter glyphs are valid Unicode characters and should not be filtered by the unmapped glyph detection logic."

Example 3: Set Membership Verification

"UNMAPPED_GLYPH_NAMES set should contain '.notdef'. \
Expected: UNMAPPED_GLYPH_NAMES.contains(\".notdef\") == true. \
Found: false. \
Why this matters: .notdef is a core unmapped glyph defined in build/unmapped-glyph-names.json configuration and must be present in the runtime set."

Example 4: CMAP Parsing Behavior (Skip Verification)

"Code 39 should not have a mapping (.notdef skipped). \
Expected: None. \
Found: {:?}. \
Why this matters: .notdef is in the default unmapped_glyph_names set (from build/unmapped-glyph-names.json), so it should be silently filtered during /Differences array parsing."

Example 5: Count Verification

"Overlay should contain exactly 1 entry. \
Expected: 1 entry (grave at 96). \
Found: {} entries. \
Why this matters: .notdef at 39 was skipped per build/unmapped-glyph-names.json, leaving only grave in the overlay."

Example 6: Diagnostic Verification

"Skipping .notdef should not generate diagnostics. \
Expected: empty diagnostics. \
Found: {} diagnostics. \
Why this matters: Skipping unmapped glyphs is silent behavior by design - these glyphs are filtered during parsing without producing warnings."

Placeholders for Dynamic Values

When the actual value is determined at runtime, use these placeholders:

• {:?} - For Debug formatting (used in assert! macros with format strings)
• {} - For Display formatting
• {variable} - Document that a specific variable name will be interpolated

Configuration File References

Always reference the source of truth in the "Why this matters" section:

• build/unmapped-glyph-names.json - Default unmapped glyph set
• build/font-fingerprints.json - Font fingerprint database
• PDF specification - When referencing spec-defined behavior
• Design docs - When referencing architectural decisions

Template Usage Guidelines

1. Be Specific: Include exact function names, parameters, and expected values
2. Be Complete: Never omit the "Why this matters" section
3. Be Accurate: The "Found" value should match what the test actually observes
4. Be Consistent: Use the same phrasing for similar assertions across tests
5. Reference Sources: Always link to the configuration file or spec that defines the expectation

Template for Different Assertion Types

Positive Assertions (Should be true)

"<subject> should <expected behavior>. \
Expected: <condition> == true. \
Found: false. \
Why this matters: <rationale with source reference>."

Negative Assertions (Should NOT be true)

"<subject> should not <unexpected behavior>. \
Expected: <condition> == false. \
Found: true. \
Why this matters: <rationale with source reference>."

Set Membership Assertions

"<set> should contain '<item>'. \
Expected: <set>.contains(\"<item>\") == true. \
Found: false. \
Why this matters: <item> is defined in <config file> and must be present in the runtime set."

Count/Quantity Assertions

"<collection> should contain exactly <n> <items>. \
Expected: <n> entries (<item list>). \
Found: {} entries. \
Why this matters: <rationale explaining expected count based on filtering rules>."

Empty/None Assertions

"<subject> should be <empty|None>. \
Expected: <expected state>. \
Found: {:?}. \
Why this matters: <rationale explaining why this should be empty/None>."

---

Template Status: Active
Maintained By: pdftract testing team
Last Updated: 2026-07-06