|
| 1 | +# Template Automation Regression Suite |
| 2 | + |
| 3 | +## Goal |
| 4 | + |
| 5 | +This suite is for **repeatable template automation patterns that the project explicitly covers**. |
| 6 | +It is not a claim that every arbitrary HWPX template is safe to automate. |
| 7 | + |
| 8 | +The regression cases focus on four questions: |
| 9 | + |
| 10 | +1. Is the automation step reproducible? |
| 11 | +2. Does it validate after modification? |
| 12 | +3. Does it preserve structure closely enough to avoid obvious package/layout drift? |
| 13 | +4. Does it make silent failure visible through explicit counts or explicit errors? |
| 14 | + |
| 15 | +## Fixture Layout |
| 16 | + |
| 17 | +Fixtures live under `tests/template_automation/fixtures/<fixture-id>/`. |
| 18 | + |
| 19 | +Each fixture contains: |
| 20 | + |
| 21 | +- `scenario.json` |
| 22 | +- `package/` - a pack-ready extracted HWPX workspace with `.hwpx-pack-metadata.json` |
| 23 | + |
| 24 | +The suite repacks these workspaces with `hwpx-pack` behavior during tests instead of storing opaque `.hwpx` binaries directly. That keeps fixture diffs reviewable and exercises the real pack/unpack path. |
| 25 | + |
| 26 | +To regenerate the extracted fixture packages: |
| 27 | + |
| 28 | +```bash |
| 29 | +PYTHONPATH=src python3 tests/template_automation/generate_fixtures.py |
| 30 | +``` |
| 31 | + |
| 32 | +## Covered Fixture Categories |
| 33 | + |
| 34 | +- `simple-placeholder`: single token in a normal body paragraph |
| 35 | +- `repeated-placeholder`: one logical value repeated across multiple locations |
| 36 | +- `split-run-placeholder`: token split across runs, where exact token replacement must not silently pretend success |
| 37 | +- `whitespace-variant`: uneven internal spacing that only matches when normalized replacement is requested explicitly |
| 38 | +- `table-placeholder`: token inside a table cell |
| 39 | +- `header-footer-placeholder`: header/footer token handling |
| 40 | +- `multi-section-placeholder`: section-targeted replacement |
| 41 | +- `checkbox-toggle`: explicit checkbox/symbol toggles |
| 42 | +- `extract-repack`: analyze -> extract -> patch -> repack workflow |
| 43 | +- `nonstandard-rootfile`: engine-openable package with a nondefault rootfile path |
| 44 | + |
| 45 | +## What The Suite Protects Against |
| 46 | + |
| 47 | +- Exact token replacement returning success when nothing actually matched |
| 48 | +- Split-run placeholders being mistaken for normal contiguous tokens |
| 49 | +- Missing-token operations silently doing no work when the caller required a replacement |
| 50 | +- Multi-location replacement losing count information |
| 51 | +- Table/header/footer/section-specific automation accidentally being tested only against top-level body text |
| 52 | +- Extracted workspaces that repack into invalid or engine-unopenable archives |
| 53 | +- Simple text substitutions causing unexpected structural drift according to `hwpx-page-guard` |
| 54 | + |
| 55 | +## What The Suite Does Not Guarantee |
| 56 | + |
| 57 | +- Correct final rendering in Hancom Office |
| 58 | +- True rendered page counts |
| 59 | +- Safety for arbitrary real-world templates with unknown controls, fields, or editor-specific behaviors |
| 60 | +- Semantic correctness of a template beyond the covered operation contract |
| 61 | + |
| 62 | +`hwpx-page-guard` is used here exactly as documented: a **layout-drift proxy**, not a renderer. |
| 63 | + |
| 64 | +## Operation Terms |
| 65 | + |
| 66 | +### Exact Replacement |
| 67 | + |
| 68 | +Literal search and replacement against explicit target surfaces such as body paragraphs, table paragraphs, headers, or footers. |
| 69 | +This is the safest covered mode when the placeholder is actually contiguous text. |
| 70 | + |
| 71 | +### Normalized-Text Replacement |
| 72 | + |
| 73 | +Matches a logical phrase after removing whitespace differences. |
| 74 | +This is broader than exact token replacement and should only be used when the caller explicitly wants whitespace tolerance. |
| 75 | + |
| 76 | +### Token-Based Replacement |
| 77 | + |
| 78 | +An exact replacement flow aimed at explicit placeholders such as `{{NAME}}`. |
| 79 | +It is intentionally conservative: if the token is split across runs, the suite expects zero matches or an explicit error, not magical reconstruction. |
| 80 | + |
| 81 | +### Structural Safety vs Semantic Template Correctness |
| 82 | + |
| 83 | +Structural safety means the package still opens, validates, and stays within expected structure/layout-drift thresholds. |
| 84 | +Semantic template correctness is a stronger claim about whether the template still means the right thing to a human reader. This suite does not try to prove the latter in the general case. |
| 85 | + |
| 86 | +## Adding A New Regression From A Bug Report |
| 87 | + |
| 88 | +1. Reduce the bug to the smallest template pattern that still reproduces the failure. |
| 89 | +2. Add a new fixture directory under `tests/template_automation/fixtures/`. |
| 90 | +3. Capture the package in extracted form with the smallest possible synthetic content. |
| 91 | +4. Add one or more scenarios to `scenario.json` that describe: |
| 92 | + - the operation |
| 93 | + - the expected replacement count or expected explicit failure |
| 94 | + - the postconditions that should stay true |
| 95 | +5. If you need a new automation mode in the helper layer, keep it narrow and evidence-driven. |
| 96 | +6. Regenerate the fixture package workspace if the source builder changed. |
| 97 | +7. Run the targeted template automation tests plus validators/type checks you touched. |
| 98 | + |
| 99 | +If a bug only reproduces for one very specific document, do not describe the fix as “general template support” unless the operation truly generalizes. |
0 commit comments