examples: ship without CI; docs and code drift apart silently

[carlos7ags]

Problem

examples/ has no *_test.go files. The example programs ship with detailed doc comments listing required system fonts and platform-specific expectations, but nothing exercises them end-to-end. Issue #227 was effectively the user being our CI for examples/cjk/main.go:

• The example's doc comment said it works on Windows with msyh.ttc and Ubuntu with NotoSansCJK-Regular.ttc
• Both paths hit the TTC-dispatch bug
• The example was tested on macOS, where findCJKFont() happens to return Arial Unicode.ttf (a TTF, not a TTC)
• Nobody caught it until a Windows user ran it

Proposal

Add a test per example that:

1. Compiles and runs the example with a synthetic / minimal-system fixture (reuse the loadAnySystemTTF + buildSyntheticTTC helpers that landed for CJK fail render some Chinese Characters. #227)
2. Asserts the produced PDF starts with %PDF- and embeds the requested font (BaseFont check)
3. Skips cleanly when no compatible fixture is available, rather than skipping silently the whole thing

Sketch:

// examples/cjk/main_test.go
func TestCJKExampleProducesValidPDF(t *testing.T) {
    if testing.Short() { t.Skip(\"example test (use -tags examples to enable in default runs)\") }
    // Stub findCJKFont to return a synthetic TTC built from a Latin TTF, so
    // the test runs on any host. Or use os.Setenv to point findCJKFont at
    // a fixture path.
    // Run main(), capture stdout, assert cjk.pdf starts with %PDF- and
    // includes the requested @font-face PostScript name as BaseFont.
}

Some examples may need a small refactor (extract buildHTML + findCJKFont from main() so tests can call them directly without re-running os.Exit).

Scope suggestion

Phase 1: examples/cjk (the one #227 reported). Phase 2: roll out to other examples on the same template (examples/fonts, examples/zugferd, examples/sign).

Acceptance criteria

• At least one example has an integration test that would have caught the broken path in CJK fail render some Chinese Characters. #227
• CI runs the example tests on every push
• A pattern others can copy for new examples

[carlos7ags]

Phase 1 done in #245: examples/cjk/main_test.go lands the test pattern (synthetic-TTC fixture, +<PostScriptName> embedding assertion, CSS-format guard, findCJKFont drift check). The same pattern is replicable for the remaining examples.

Phase 2 — outstanding examples to port

Each below needs a *_test.go next to its main.go with the appropriate fixture:

• examples/fonts — bundles @font-face from disk; needs synthetic TTF fixture (no TTC complexity)
• examples/zugferd — XML embedding + invoice rendering; needs to assert /AFRelationship /Alternative and embedded XML stream
• examples/sign — CMS/PKCS#7 signature; needs ephemeral cert + key fixture (or skip if the example uses a hardcoded test key, in which case assert the /ByteRange and signed-attributes structure are present)
• examples/invoice — PDF/A invoice; assert PDF/A metadata + ICC profile presence
• examples/report — multi-page report; assert page count > 1
• examples/template — golang/text/template-driven; assert variable substitution survived the round trip
• examples/links — hyperlink annotations; assert /Annot /Subtype /Link count matches expected
• examples/redact — text redaction; assert redacted strings do not appear in extractable content
• examples/import-page — page import; assert imported page count
• examples/merge — multi-doc merge; assert combined page count
• examples/optimize — optimizer pipeline; assert output is smaller than input
• examples/rtl — Arabic text shaping; assert shaped glyph IDs appear in content stream
• examples/indic — Devanagari shaping; same shape as rtl
• examples/html-to-pdf — generic HTML conversion; smoke test
• examples/showcase — broad feature demo; smoke test
• examples/barcode (if present)

Pattern

Each test follows the same shape established in #245:

// examples/X/main_test.go
package main

func TestExampleProducesValid<X>(t *testing.T) {
    // 1. Build any required fixtures into t.TempDir()
    // 2. Call the example's exported helpers (extract from main() if needed)
    // 3. Assert the output starts with %PDF- and is at least N KB
    // 4. Assert at least one example-specific structural property
    // 5. Verify the assertion catches a regression by simulating the failure mode
}

When a fixture would be reused across examples (e.g., synthetic TTF/TTC), consider promoting it to examples/internal/testfixtures — currently duplicated 3× across font/ttc_test.go, html/issue227_test.go, and examples/cjk/main_test.go. Threshold for the extraction was reached during Phase 1 review but explicitly deferred.

Discovery hook

Add examples/CONTRIBUTING.md (or extend the root one) documenting that new examples must ship with a main_test.go that asserts at least the %PDF- smoke test. Without this, Phase 2 is one-time effort rather than an ongoing guarantee.

Closing #231

When all sub-tasks above are checked, this issue can close. Until then, leaving open as the umbrella tracker for example CI rollout.