docs(35-09): complete site name safety unit tests plan

This commit is contained in:
Jakub Zych
2026-11-14 16:08:01 +01:00
parent fbbfce0702
commit dce002ee45

View File

@@ -0,0 +1,234 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 09
subsystem: mail
tags: [postcard, cabana, tests, gate, gap-closure, CR-01]
requires:
- phase: 35-08
provides: decoded URL-scheme check (unsafeMarkup), postcard.UnsafeText, render-time site-name drop, Branding 422, inliner fallback, literal footer
provides:
- named Docker-free regression tests for site names on the send path, the scheme check, the unsafe inlined result and the literal footer
- cabana Postgres test for the Branding refusal and names stored before the check
- check-phase35.sh requires every new name; IN-03 self-test compares the planted consumer's go.mod
- 35-VALIDATION.md CR-01, WR-01, WR-05 rows and the CR-01 status line
affects: [35-verify-work, mail, postcard, cabana]
actuals:
tokens: 9052
tasks: 3
commits: 5
plan_head_before: 8751f922307fe476961a5e97e1525b8bbff84c52
plan_head_after: fbbfce07024f162c30e8ce4d44a7e0984a7a4b46
tech-stack:
added: []
patterns:
- "Tests that pin shipped behaviour show they are not vacuous through mutation runs (break the rule, see the named test fail, restore with git checkout)"
- "Site-name tests are table subtests named <layout>/<source or case>/<render path>"
key-files:
created:
- modules/postcard/sitename_test.go
- modules/postcard/safety_test.go
- modules/cabana/mail_site_name_postgres_test.go
modified:
- modules/cabana/mail_screens_smoke_test.go
- scripts/check-phase35.sh
- .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md
key-decisions:
- "The mail screens test env reads mail.from from its configuration (default noreply@example.test unchanged), so a mutate hook sets the sender; the plan assumed it already did"
patterns-established:
- "A Postgres test models data saved before a save-time check by writing the row through env.gdb and clearing it in t.Cleanup"
requirements-completed: [CR-01, WR-01, WR-05, D-13, D-14, D-21]
coverage:
- id: D1
description: "Prose site names from mail.from and Branding send on the default and system layouts on the file-version, override and override-failure fallback paths"
requirement: CR-01
verification:
- kind: unit
ref: "modules/postcard/sitename_test.go#TestSiteNameSend"
status: pass
human_judgment: false
- id: D2
description: "Unsafe site names are dropped on every render path with one value-free warning; editor validate and preview are not refused"
requirement: D-14
verification:
- kind: unit
ref: "modules/postcard/sitename_test.go#TestUnsafeSiteNameDropped"
status: pass
- kind: unit
ref: "modules/postcard/sitename_test.go#TestUnsafeText"
status: pass
human_judgment: false
- id: D3
description: "Anchored, decoded scheme check: prose passes, every URL-bearing attribute and encoded form refused, send and editor with inlining on and off"
requirement: WR-05
verification:
- kind: unit
ref: "modules/postcard/safety_test.go#TestURLSchemeCheck"
status: pass
human_judgment: false
- id: D4
description: "An inlined result that fails the check sends the style-block version with one warning per layout"
requirement: WR-05
verification:
- kind: unit
ref: "modules/postcard/safety_test.go#TestInlineUnsafeOutput"
status: pass
human_judgment: false
- id: D5
description: "Footer prints the site name literally and escaped; body argument stays Markdown"
requirement: WR-01
verification:
- kind: unit
ref: "modules/postcard/sitename_test.go#TestFooterSiteNameLiteral"
status: pass
human_judgment: false
- id: D6
description: "Branding 422 on site_name in en and pl, prose names save, stored unsafe names never block saves or sends, mail.from prose name shows"
requirement: D-13
verification:
- kind: integration
ref: "modules/cabana/mail_site_name_postgres_test.go#TestMailSiteNameSafety"
status: pass
human_judgment: false
- id: D7
description: "Branding refusal line under the Site name field in the embedded admin"
verification: []
human_judgment: true
rationale: "Visual; recorded as a Manual-Only row in 35-VALIDATION.md for /msd-verify-work 35"
duration: 31min
completed: 2026-11-14
status: complete
---
# Phase 35 Plan 09: Unit tests for the CR-01 site name safety fix Summary
**Seven named postcard tests and one cabana Postgres test pin the 35-08 fix (prose site names send on every render path, unsafe ones are dropped or refused at save, decoded scheme check, style-block fallback, literal footer). Fourteen mutation runs prove they are not vacuous, and `check-phase35.sh --all` requires every name and passes with Docker.**
## Performance
- **Duration:** 31 min
- **Started:** 2026-11-14T14:35:52Z
- **Completed:** 2026-11-14T15:07:06Z
- **Tasks:** 3
- **Files modified:** 6
## Accomplishments
- `TestSiteNameSend`, `TestUnsafeSiteNameDropped`, `TestUnsafeText` (Task 1, tracer) cover the verifier's regression on a small MapFS catalog. Subtests are named `<layout>/<source|case>/<file_version|override|override_fallback>`.
- `TestURLSchemeCheck` covers 5 accepts and 21 refuses, each refuse checked for its error text and for a snippet that points at the markup. It also covers the send path through `assertFileFallback` and the editor, each with inlining on and off. `TestInlineUnsafeOutput` uses plain and entity-encoded links and checks the per-layout warning key. `TestFooterSiteNameLiteral` covers the footer (Task 2).
- `TestMailSiteNameSafety` covers the admin side with six subtests: `refused_on_save` (en and pl), `prose_names_saved`, `preview_drops_unsafe_name`, `stored_unsafe_name_saves`, `stored_unsafe_name_send` and `mail_from_prose_name` (Task 3).
- IN-03: the self-test's workspace-modfile case now compares the planted consumer's go.mod with `cmp -s` against a copy taken before the run.
- 35-VALIDATION.md maps CR-01 (3 rows), WR-01 and WR-05, closes the open item with a "CR-01 status" line, and adds a Manual-Only row for the Branding refusal and the Wave 0 entry.
## Task Commits
1. **Task 1: site-name send tests (tracer)**: `e0016e0c` test(postcard): site names on the built-in layouts never stop a send
2. **Task 2: scheme check, unsafe inlined output, literal footer**: `446a77ef` test(postcard): decoded URL scheme check, unsafe inlined output and the literal footer
3. **Task 3: cabana test, IN-03, validation map**: `54617f78` test(cabana): unsafe Branding site names refused at save, stored ones never block saves or sends; `e54be76c` test(35): self-test compares the planted consumer's go.mod; `fbbfce07` docs(35): validation map for the site name safety gap
**Plan metadata:** recorded in the docs(35-09) completion commit.
## Required test names (scripts/check-phase35.sh)
- GO_TESTS (new): `./modules/postcard:` TestMailSafetySmoke, TestSiteNameSend, TestUnsafeSiteNameDropped, TestUnsafeText, TestURLSchemeCheck, TestInlineUnsafeOutput, TestFooterSiteNameLiteral
- DOCKER_TESTS (new): `./modules/cabana:TestMailSiteNameSafety`
## Gate output
`bash scripts/check-phase35.sh --all` exit 0, with the Docker daemon up (PHASE35_ALLOW_NO_DOCKER not used):
- PASS self-test (includes `PASS self-test workspace-modfile`), go (24 postcard top-level tests by name), consumers, admin, docs, marker, additive (8 packages against v0.6.3), docker (full `go test ./...`, 12 cabana top-level tests by name, no skips)
- "Phase 35 gate passed"
- `git status --porcelain` of sm-user-plugin and sm-paymentgateway-plugin was empty before and after; go.mod and go.sum unchanged
## Mutation runs (stand-ins for RED)
Each test was green on its first run, as expected for tests of shipped code. Each mutation was applied, run, and then restored with `git checkout -- <file>`:
| # | Mutation | Failing tests |
|---|----------|---------------|
| M1 | validateHTML checks dangerousScheme over the whole document (35-06 rule) | TestSiteNameSend (all 14 subtests), TestUnsafeText |
| M2 | UnsafeText always false | TestUnsafeText, TestUnsafeSiteNameDropped (handler, mail_from_source, ...) |
| M3 | scriptURLText without the scheme boundary | TestUnsafeText, TestSiteNameSend (mail_from) |
| M4 | site-name warning not rate-limited | TestUnsafeSiteNameDropped (warning count) |
| M5 | formaction, background, poster, xlink:href dropped from urlAttributes | TestURLSchemeCheck refuse/{button_formaction,table_background,video_poster,svg_xlink_href} |
| M6 | hasDangerousScheme keeps whitespace and case | TestURLSchemeCheck refuse/{href_space_mixed_case,tab_split,newline_split} |
| M7 | text tokens checked for schemes | TestURLSchemeCheck accept/prose_*, editor/*; TestSiteNameSend |
| M8 | an inlined result that fails the check stops the send | TestInlineUnsafeOutput/{plain,encoded} |
| M9 | footer partial renders text as Markdown | TestFooterSiteNameLiteral (all 6 layout cases, partial/text_literal) |
| M10 | Branding BeforeValidate accepts unsafe names | TestMailSiteNameSafety/refused_on_save |
| M11 | layouts get the Branding name unfiltered | TestMailSiteNameSafety/{preview_drops_unsafe_name,stored_unsafe_name_send} |
| M12 | settings refusal returned unlocalized | TestMailSiteNameSafety/refused_on_save |
| M13 | pre-35-08 behaviour (M1 + M11) | TestMailSiteNameSafety: 5 of 6 subtests, including stored_unsafe_name_saves |
| M14 | env mailer ignores mail.from (helper before the deviation) | TestMailSiteNameSafety/mail_from_prose_name |
| M15 | self-test: the modfile run appends to the planted consumer's go.mod | `refuse: self-test the modfile run wrote the planted consumer's go.mod` |
M11 alone leaves `stored_unsafe_name_saves` green, because the decoded check no longer reads text. A stored name could only refuse a save with both halves of the old code in place, which is what M13 restores.
## Files Created/Modified
- `modules/postcard/sitename_test.go`: TestSiteNameSend, TestUnsafeSiteNameDropped, TestUnsafeText, TestFooterSiteNameLiteral, fixture `siteNameMailer`
- `modules/postcard/safety_test.go`: TestURLSchemeCheck, TestInlineUnsafeOutput
- `modules/cabana/mail_site_name_postgres_test.go`: TestMailSiteNameSafety, helpers `storedSiteName`, `putInLanguage`, `moveWelcome`
- `modules/cabana/mail_screens_smoke_test.go`: env mailer From read from `mail.from` (deviation 1)
- `scripts/check-phase35.sh`: GO_TESTS/DOCKER_TESTS entries, IN-03 `cmp -s`
- `.planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md`
## Decisions Made
- The mail screens env takes its sender from `mail.from` in its configuration (see deviation 1).
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 3 - Blocking] The mail screens env ignored mail.from**
- **Found during:** Task 3 (`mail_from_prose_name`)
- **Issue:** `newMailScreensEnvWith` built the mailer with a hard-coded `From: "noreply@example.test"`, so the plan's "mail.from through the mutate hook" never reached the mailer.
- **Fix:** the env sets `mail.from` to `noreply@example.test` before `mutate` and builds the mailer with `cfg.String("mail.from")`. Every other mail test sees the same sender as before. This is a test-helper change, not production code. The full cabana Docker suite is green.
- **Files modified:** modules/cabana/mail_screens_smoke_test.go
- **Verification:** M14 above; `go test ./modules/cabana` (Docker) green
- **Committed in:** `54617f78`
**2. [Note] No production defects found**
- None of the new tests exposed a defect in the 35-08 code, so no `fix(...)` commits were needed. The prohibition on production changes holds: only test files, the gate script and the validation doc changed.
---
**Total deviations:** 1 auto-fixed (blocking, test helper), 1 note
**Impact on plan:** none on scope; the mail.from case runs in its own environment as planned.
## TDD Gate Compliance
Tasks 2 and 3 carry `tdd="true"`, but they pin code 35-08 already shipped, so no failing commit was possible (CLAUDE.md keeps every commit green). As the plan directs, the mutation runs M1-M15 above stand in for RED. Each one shows a named test failing against broken code and passing against the shipped code.
## Issues Encountered
- `gofmt -l` still lists modules/postcard/store_postgres_test.go and modules/cabana/mail_routes.go. Both predate this plan and were left alone, as in 35-08.
## Verification
- `go vet ./...` and `go test -short ./...` were green after every code commit. `go test ./modules/postcard` and `go test ./modules/cabana` (Docker) were green, and `check-phase35.sh --all` ran the full `go test ./...`.
- Acceptance greps: 3 `func Test` lines in sitename_test.go for Task 1 and 1 for the footer; 2 in safety_test.go; 1 in the cabana file; no `t.Skip` in the Docker-free files; 7 encoded-colon lines in safety_test.go; no non-comment `unsafe_name_current_behaviour` in modules/cabana; no non-comment `status --porcelain -- go.mod` and 1 `cmp -s` in `self_test_consumers`; 6 CR-01 lines, 2 WR-01/WR-05 lines and 1 "CR-01 status" line in 35-VALIDATION.md.
- Nothing pushed or tagged; no sibling repository changed.
## User Setup Required
None.
## Next Phase Readiness
- Ready for `/msd-verify-work 35`. It re-verifies the CR-01 gap, then runs the pending human items in 35-VERIFICATION.md (UAT test 1 re-run, scoped UAT test 8 re-run, real-inbox check, judgment-tier prohibitions) and the new Manual-Only row for the Branding refusal.
---
*Phase: 35-mail-templates-and-layouts-editor*
*Completed: 2026-11-14*
## Self-Check: PASSED