docs(35-07): complete gap-closure tests plan

- SUMMARY for the G-35-1 and G-35-8 tests, the read-only consumers stage
  and the validation map
This commit is contained in:
Jakub Zych
2026-11-13 22:11:03 +01:00
parent a3ce097455
commit d00e2c8d6f

View File

@@ -0,0 +1,265 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 07
subsystem: testing
tags: [postcard, cabana, admin-spa, mail-templates, locales, css-inlining, go-premailer, gate, gap-closure]
status: complete
requires:
- phase: 35-05
provides: TemplateBase, Catalog.TemplateFor, EnsureLocaleRows, migration 202611130001, RecordMeta.LocaleVariants, LocaleVariantSwitcher.vue
- phase: 35-06
provides: finished built-in layouts, header/footer partials, Brand.SiteName, CSS inlining with disable_auto_inline_css, the mailer.inline seam, migrations 202611130002-3
provides:
- "check-phase35.sh consumers stage: read-only scratch -modfile runs (GOWORK=off, GOPROXY=off, sibling go.sum merged with the framework's), dirty-sibling refusal before and after, two new self-test planted cases"
- "postcard unit tests: TestTemplateBase, TestTemplateFor, TestSendLocaleFallback, TestBuiltinLayoutsLogo, TestHeaderFooterPartials, TestButtonPartial, TestSiteName, TestInlineCSS, TestInlineCSSOptOut, TestInlineFailure; Postgres: TestEnsureLocaleRows"
- "cabana Postgres tests: TestMailLocaleGroups, TestMailBrandSiteName, TestMailLayoutInlineOptOut"
- "SPA tests: LocaleVariantSwitcher.test.ts extended (9 cases), FormViewMail.test.ts (one-variant case, unsaved-changes confirm on switching)"
- "35-VALIDATION.md G-35-1/G-35-8 rows, superseded D-05 and byte-identity rows, manual and deferred checks; 35-UAT.md G-35-8 closure_note and rerun_scope"
affects: [35 verify-work, UAT test 1 and 8 re-runs, sm-user-plugin follow-up, sm-paymentgateway-plugin follow-up]
actuals:
tokens: 21300
tasks: 3
commits: 5
plan_head_before: 0e97113a4f4d513a7d3fdbab28cf7687112e2f6c
plan_head_after: a3ce097455c244bc2e6c2fa886239e84547494f0
tech-stack:
added: []
patterns:
- "Gate consumers stage: scratch -modfile copy of a sibling's go.mod with its go.sum merged with the framework's, GOWORK=off and GOPROXY=off, git status --porcelain checked before and after"
- "Inlined-HTML assertions by tag and attribute (htmlTags/withClass helpers in layouts_test.go), never whole-markup equality"
- "Recording OverrideSource (recordingOverrides) to pin the order a send asks for overrides"
key-files:
created:
- modules/postcard/locale_test.go
- modules/postcard/locale_postgres_test.go
- modules/postcard/layouts_test.go
- modules/postcard/inline_test.go
- modules/cabana/mail_locale_postgres_test.go
- modules/cabana/mail_brand_layout_postgres_test.go
modified:
- scripts/check-phase35.sh
- admin/tests/form/LocaleVariantSwitcher.test.ts
- admin/tests/form/FormViewMail.test.ts
- .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md
key-decisions:
- "The consumers stage merges the framework's go.sum into each sibling's scratch go.sum and runs with GOPROXY=off, so go-premailer resolves from verified hashes and the module cache without network or writes to the sibling"
- "The dirty-sibling check runs before and after the consumer runs; a sibling with uncommitted changes is refused up front instead of after the tests"
- "G-35-8 is recorded as framework-closed with the plugin part deferred; the UAT test 8 re-run is scoped to the built-in layouts"
- "The unsafe Branding site name (URL scheme) stays an open item: TestMailBrandSiteName pins the current behaviour (saved as typed, preview refused) without a production change"
patterns-established:
- "Each gap-closure test name is added to the gate's required arrays in the same commit as the test"
requirements-completed: [G-35-1, G-35-8, D-21]
coverage:
- id: D1
description: "Phase gate stays read-only against the core plugins with the new go-premailer requirement: scratch modfiles, framework resolves to this checkout, dirty-tree refusal, planted self-test cases"
requirement: D-21
verification:
- kind: other
ref: "bash scripts/check-phase35.sh --self-test (dirty-sibling, workspace-modfile)"
status: pass
- kind: other
ref: "bash scripts/check-phase35.sh --consumers; git status --porcelain of sm-user-plugin and sm-paymentgateway-plugin empty"
status: pass
human_judgment: false
- id: D2
description: "Locale resolution and fallback rows in postcard: TemplateBase/TemplateFor rules, send order own customization > base customization > base file, EnsureLocaleRows, base_code, reset of a fallback code, migrations roll back"
requirement: G-35-1
verification:
- kind: unit
ref: "modules/postcard/locale_test.go#TestTemplateBase, TestTemplateFor, TestSendLocaleFallback"
status: pass
- kind: integration
ref: "modules/postcard/locale_postgres_test.go#TestEnsureLocaleRows"
status: pass
human_judgment: false
- id: D3
description: "Grouped mail templates in the admin API: one row per template, customized locales, grouped states and filter, localeVariants, fallback row default version, save/send/reset/drift, file version against the base, 404 outside the group, permission split, locales enabled at run time"
requirement: G-35-1
verification:
- kind: integration
ref: "modules/cabana/mail_locale_postgres_test.go#TestMailLocaleGroups"
status: pass
human_judgment: false
- id: D4
description: "Locale switcher in the SPA: options, current, navigation, restored selection; FormView shows it with two or more variants and asks the unsaved-changes confirm"
requirement: G-35-1
verification:
- kind: unit
ref: "admin/tests/form/LocaleVariantSwitcher.test.ts"
status: pass
- kind: unit
ref: "admin/tests/form/FormViewMail.test.ts#asks the unsaved-changes confirm before switching locale and stays on cancel"
status: pass
human_judgment: false
- id: D5
description: "Built-in layouts: logo img with alt = site name in default/system headers and above the message in minimal, site name or nothing without a logo, header/footer partials, button partial in every built-in layout, site name with the mail.from fallback"
requirement: G-35-8
verification:
- kind: unit
ref: "modules/postcard/layouts_test.go#TestBuiltinLayoutsLogo, TestHeaderFooterPartials, TestButtonPartial, TestSiteName"
status: pass
human_judgment: false
- id: D6
description: "CSS inlining: brand colour on the button, DOCTYPE kept, media query in a style block, text part unchanged, safety check, per-layout opt-out, inliner failure fallback with rate-limited warning"
requirement: G-35-8
verification:
- kind: unit
ref: "modules/postcard/inline_test.go#TestInlineCSS, TestInlineCSSOptOut, TestInlineFailure"
status: pass
human_judgment: false
- id: D7
description: "Admin side of G-35-8: Branding site name (trimmed, max 255, preview and send header, no header row without name or logo) and the layout form's inlining switch (file layout, reset, custom layout)"
requirement: G-35-8
verification:
- kind: integration
ref: "modules/cabana/mail_brand_layout_postgres_test.go#TestMailBrandSiteName, TestMailLayoutInlineOptOut"
status: pass
human_judgment: false
- id: D8
description: "Whole gap closure proven by one command"
requirement: D-21
verification:
- kind: other
ref: "bash scripts/check-phase35.sh --all (Phase 35 gate passed)"
status: pass
human_judgment: false
- id: D9
description: "UAT test 1 re-run and UAT test 8 re-run scoped to the built-in layouts on sm-demo-app; real-inbox check of inlined mail; deferred plugin follow-up check"
verification: []
human_judgment: true
rationale: "Visual placement of the switcher and rendering of the layouts in the admin preview and real mail clients need a human (35-VALIDATION.md Manual-Only rows)"
duration: 49min
completed: 2026-11-13
---
# Phase 35 Plan 07: Gap-closure tests for G-35-1 and G-35-8 Summary
**Named unit, Postgres and SPA tests pin the mail template locale groups (G-35-1) and the finished built-in layouts with CSS inlining (G-35-8). The phase gate requires every one of them by name and runs the core plugins read-only through scratch `-modfile` copies, offline. `--all` passes.**
## Performance
- **Duration:** 49 min
- **Started:** 2026-11-13T20:20:50Z
- **Completed:** 2026-11-13T21:09:57Z
- **Tasks:** 3
- **Files modified:** 11 (6 created)
## Accomplishments
- `scripts/check-phase35.sh --consumers` copies each sibling's go.mod into a scratch directory, with a go.sum that merges the sibling's and the framework's. It runs `workspace_check`, `go vet` and the named mail tests with `GOWORK=off GOPROXY=off -mod=mod -modfile=<scratch>/go.mod`. A sibling whose `git status --porcelain` prints anything before or after the runs is refused. The self-test plants a dirty repository and a consumer whose scratch modfile resolves the framework elsewhere; the second case is refused only because the modfile is read.
- postcard: ten Docker-free tests and one Postgres test cover locale resolution, the order overrides are asked for, fallback rows, the logo, header and footer, the button partial, the site name, inlining, the opt-out and the inliner-failure fallback.
- cabana: three Postgres tests cover the grouped templates screen, the Branding site name and the layout inlining switch.
- SPA: the switcher test now has 9 cases, and FormViewMail gains the one-variant case and the unsaved-changes confirm on switching locale.
- 35-VALIDATION.md and 35-UAT.md record G-35-8 as framework-closed with the plugin part deferred, and scope the UAT test 8 re-run.
## Required test names added to the gate
- **GO_TESTS (Docker-free, never skip under -short):** `./modules/postcard:` TestTemplateBase, TestTemplateFor, TestSendLocaleFallback, TestBuiltinLayoutsLogo, TestHeaderFooterPartials, TestButtonPartial, TestSiteName, TestInlineCSS, TestInlineCSSOptOut, TestInlineFailure
- **DOCKER_TESTS:** `./modules/postcard:TestEnsureLocaleRows`, `./modules/cabana:` TestMailLocaleGroups, TestMailBrandSiteName, TestMailLayoutInlineOptOut
- **ADMIN_FILES:** `tests/form/LocaleVariantSwitcher.test.ts` (FormViewMail.test.ts was already required)
## Gate output
The fourth `bash scripts/check-phase35.sh --all` run passed: PASS self-test, go, consumers, admin (vitest 1679 passed, browser 13 passed, typecheck, openapi, dist), docs, marker, additive (8 packages against v0.6.3), docker (`go test ./...` plus the named Postgres tests). It printed "Phase 35 gate passed", and both sibling trees stayed clean. Docker answered directly, so PHASE35_ALLOW_NO_DOCKER was not used.
The earlier runs each failed once on a test this plan does not touch (see Issues Encountered).
## Task Commits
1. **Task 1: read-only consumers with a scratch modfile (tracer)** - `ae13e4dd` (test)
2. **Task 2: postcard unit tests** - `a0dde086` (test)
3. **Task 3: cabana Postgres tests** - `eed91c82` (test); **SPA tests** - `a9381165` (test); **validation map** - `a3ce0974` (docs)
## Files Created/Modified
- `scripts/check-phase35.sh` - the consumers stage (scratch modfile, clean check), the new self-test cases and the required names.
- `modules/postcard/locale_test.go` - TemplateBase, TemplateFor and the send order through a recording OverrideSource.
- `modules/postcard/locale_postgres_test.go` - EnsureLocaleRows, SyncIndex base_code, reset of a fallback code and the migration rollback.
- `modules/postcard/layouts_test.go` - the logo, header and footer, the button partial and the site name, with the tag and attribute helpers.
- `modules/postcard/inline_test.go` - inlining, the opt-out (file key, column, draft) and the inliner failure.
- `modules/cabana/mail_locale_postgres_test.go` - TestMailLocaleGroups, with a mutable TranslationWriter.
- `modules/cabana/mail_brand_layout_postgres_test.go` - TestMailBrandSiteName and TestMailLayoutInlineOptOut.
- `admin/tests/form/LocaleVariantSwitcher.test.ts` and `admin/tests/form/FormViewMail.test.ts` - the switcher cases and the FormView confirm.
- `35-VALIDATION.md` and `35-UAT.md` - the planning docs.
## Decisions Made
- The scratch go.sum merges the framework's go.sum, and the consumer runs use `GOPROXY=off`. This keeps the gate offline: a missing module fails loudly instead of being downloaded.
- The sibling clean check also runs before the consumer runs. A sibling another session is editing is refused up front, so the gate never tests foreign work in progress.
- Tests that assert on delivered HTML read tags by attribute. Inlining re-serialises the markup (attribute order, added style attributes), so whole-markup comparison would be brittle.
## Deviations from Plan
### Auto-fixed Issues
None. No test exposed a production defect, and no production code changed.
### Notes
**1. [Test scope] TestEnsureLocaleRows checks `bases` with a template name that is not in the catalog.**
- The plan does not cover `bases`. I first tried a file-backed locale variant as the base, but `TemplateBase` with a locale list that leaves out `en` treats `welcome-en` as a base of its own, so that check would have been misleading. Passing a name that is not in the catalog shows plainly that `bases` limits the run.
**2. [Scope] Unsafe site name documented, not fixed.**
- `TestMailBrandSiteName/unsafe_name_current_behaviour` pins the current behaviour: a name holding `javascript:` is saved, and the Branding preview refuses it with 422. The save-time check stays an open item, as the orchestrator directed.
**3. [Verification] Mutation checks stand in for RED.**
- Each new postcard test file was run against temporarily broken assets or code: the header row removed, the minimal alt changed, the button type ignored, the header span removed, the opt-out ignored, and the validation of the inlined output skipped. The tests failed every time, and each file was restored with `git checkout -- <file>`.
---
**Total deviations:** 0 auto-fixed; 3 notes (test scope, documented open item, verification method).
**Impact on plan:** none. The plan's files and commits are as written, and nothing outside it changed.
## TDD Gate Compliance
Tasks 2 and 3 carry `tdd="true"`, but they test behaviour 35-05 and 35-06 already shipped. Each new test therefore passed on its first run (an "unexpected GREEN" that is expected here), and there is no separate `test(...)` RED commit followed by a `feat(...)` commit. Mutation runs, which break the shipped asset or code and confirm the test fails, show the tests are not vacuous (Note 3). CLAUDE.md's green-at-every-commit rule also rules out failing commits.
## Issues Encountered
- **Flaky, unrelated: `modules/surf` TestStreamingRoute.** Its access-log assertion failed once under the load of the full `go test ./...` in the docker stage. It passes 5 times in a row in isolation, and on the standalone docker stage and the final `--all` run. It dates from 19.7-05, and no surf file changed in this phase.
- **Flaky, unrelated: admin `test:browser` code-editor suites.** Twice in `--all`, `codeeditor.test.ts` and `codeeditor-smoke.test.ts` failed to import ("Failed to fetch dynamically imported module", no assertion failure). They pass when run alone, after `npm run test`, through `--prefix` from the repository root, and in the admin stage alone and the final `--all` runs. I could not reproduce it on demand.
- Both flaky tests are listed here rather than in `deferred-items.md`, because another session holds uncommitted edits in that file.
- `modules/postcard/store_postgres_test.go` already had a gofmt difference before this plan; the new files are gofmt-clean.
## Open Items
- **The Branding site name is not checked for a URL scheme at save time** (35-06 threat flag). A name holding `javascript:`, `vbscript:` or `data:` is saved as typed, and the preview refuses it (pinned by a test). From `mailer.render`, which applies the Branding to the file version too, every send in the built-in layouts would then fail until the name is changed; no test exercises that send path. A save-time check (cabana validation, or a postcard `Editor.Validate` brand rule) is a follow-up outside this plan.
- **Plugin follow-up after the framework tag (G-35-8 plugin part):** sm-user-plugin and sm-paymentgateway-plugin need the framework bump with `go mod tidy`, the button partial in their templates and finished layouts. The deferred follow-up check is in 35-VALIDATION.md.
## Known Stubs
None.
## Threat Flags
None. These are test and gate changes only. T-35-39 is mitigated: scratch modfiles, `workspace_check` under the modfile, and the dirty-tree refusal, with planted self-test cases. T-35-40 is mitigated: every new name is required, and `detect_go` refuses skips, zero matches and missing names.
## User Setup Required
None.
## Next Phase Readiness
- Ready for `/msd-verify-work 35`: re-run UAT test 1 in full. Re-run test 8 scoped to the built-in layouts, after resetting the UAT overrides of `golem15.user::mail.activate` and `golem15.user::mail.layouts.user`. The plugin CTA and the plugin layouts stay a deferred follow-up check.
- Nothing was pushed or tagged. No sibling repository changed.
---
*Phase: 35-mail-templates-and-layouts-editor*
*Completed: 2026-11-13*
## Self-Check: PASSED
- Created files exist: the 4 postcard test files, the 2 cabana test files and this SUMMARY.
- Commits exist: ae13e4dd, a0dde086, eed91c82, a9381165, a3ce0974.
- Acceptance criteria re-run: `modfile` 21 lines and `status --porcelain` 5 lines in the gate; 11 `func Test` across the postcard files; no `t.Skip` in the Docker-free files; the required names are present in the gate; the 3 cabana test functions exist; `localeVariants` appears 6 times in FormViewMail.test.ts; the G-35-1 and G-35-8 rows, closure_note, rerun_scope and the deferred follow-up row are present; `status: diagnosed` is unchanged in 35-UAT.md.
- Plan verification: `go vet ./...`, `go test -short ./...`, the full `go test ./...` (docker stage), the admin test, test:browser and typecheck all pass, and `bash scripts/check-phase35.sh --all` printed "Phase 35 gate passed"; both sibling trees are clean.