From d00e2c8d6fd1ce688503a47ba127b02cff4e915f Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Fri, 13 Nov 2026 22:11:03 +0100 Subject: [PATCH] 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 --- .../35-07-SUMMARY.md | 265 ++++++++++++++++++ 1 file changed, 265 insertions(+) create mode 100644 .planning/phases/35-mail-templates-and-layouts-editor/35-07-SUMMARY.md diff --git a/.planning/phases/35-mail-templates-and-layouts-editor/35-07-SUMMARY.md b/.planning/phases/35-mail-templates-and-layouts-editor/35-07-SUMMARY.md new file mode 100644 index 00000000..3e045cf3 --- /dev/null +++ b/.planning/phases/35-mail-templates-and-layouts-editor/35-07-SUMMARY.md @@ -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=/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 -- `. + +--- + +**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.