Mark
b112cb7861
Plan 01-10 Wave 3: extends the UAT harness with three new page-side
assertions covering the onboarding contract + the canonical-tokens
design-swap-readiness invariant. UAT baseline 21 → 24 GREEN.
tests/uat/extension-page-harness.ts (page-side):
- assertA15 — chrome.storage.local 'onboarding-completed' === true +
'installed-at' is number. Verifies SW's openWelcomeIfFirstInstall
side-effects.
- assertA16 — 2s settle window; chrome.tabs.query welcome-tab count
delta === 0. Verifies flag-gating across SW respawns.
- assertA17 — 7 sub-checks covering: welcome.html parse + .welcome-hero
+ >=7 mokosh-keyed attrs + welcome.css canonical @import literal OR
inlined --mks-* evidence + (zero hex OR canonical resolved) + >=5
var(--mks-*) refs + bundled JS preserves populate plumbing +
getComputedStyle --mks-rec → rgb(178, 84, 61) (canonical D-04 Loom).
- window.__mokoshHarness surface extended with the three new methods;
type declaration + assignment + page-ready status text updated.
tests/uat/lib/harness-page-driver.ts (host-side):
- driveA15, driveA16, driveA17 — standard page.evaluate wrappers
matching driveA14 / driveA18..A22 idiom. driveA16 dominates the
new wall-clock budget (~2.1s for the settle window).
tests/uat/harness.test.ts (orchestrator):
- Drivers array interleaves A15/A16/A17 AFTER A14 + BEFORE A18.
A22's skip-gate no longer triggers (Plan 01-10 lands welcome.html;
A22 now exercises the substantive token-usage path).
- FORBIDDEN_HOOK_STRINGS unchanged at 12 entries (A15-A17 use only
chrome.tabs.query / chrome.storage.local.get / fetch / DOMParser /
getComputedStyle — all production-API surfaces).
DEVIATION (Rule 1 — auto-fix bug in plan-supplied check):
The plan's A17.6 spec used literal substring checks 'COPY[' and
'chrome.i18n.getMessage(' which fail against minified production
output. Vite/Rollup terser renames `COPY` → `f` (local variable
mangling) and welcome.ts's source uses optional chaining
`chrome?.i18n?.getMessage?.(` which doesn't match the verbatim
literal. Replaced with two minification-survivable witnesses:
1. 'welcome.page.title' — literal Object.freeze key (terser
preserves object-literal keys verbatim).
2. 'i18n' + 'getMessage' + 'welcomeHero' substring conjunction —
chrome global + property access + fallback key literal; all
three survive minification regardless of optional-chaining
insertion or rename.
Both witnesses prove the populate plumbing survives the build (the
ground-truth contract A17.6 enforces). The relaxed contract is
semantically equivalent — neither substring is load-bearing on its
own; both witness the same underlying invariant.
Verify (all GREEN):
- npm run test:uat: 24/24 assertions passed (A0 grep gate + A1..A14
+ A15..A17 + A18..A22 + A23).
- npx tsc --noEmit: clean.
- npm run build:test: clean; dist-test/assets/welcome-wB0e_R_n.js
bundled; harness page bundle includes new asserts.
- SKIP_BUILD=1 npx vitest run tests/background/no-test-hooks-in-prod-bundle.test.ts:
13/13 GREEN (Tier-1 grep gate; FORBIDDEN_HOOK_STRINGS at 12).
- Full vitest baseline preserved: 137 ex-grep-gate + 13 grep-gate
= 150 GREEN (Plan 01-10 target).
A17.7 canonical proof: getComputedStyle.color = 'rgb(178, 84, 61)' —
the @import '../shared/tokens.css' directive resolves through to the
canonical D-04 Loom palette --mks-madder-600 = #b2543d at runtime, as
the empirical proof Plan 01-12 must_have #9 path-B contract demands.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Mokosh UAT harness (Plan 01-11)
Puppeteer-driven Node script that runs 14 assertions end-to-end against a real Chrome instance loaded with the Mokosh extension. Replaces Plan 01-09 Task 5's operator-empirical functional verification (the operator retains only step 1 — build — and step 14 — brand/design acceptance).
Quick start
npm run test:uat
This builds dist-test/ (the hook-enabled bundle) and runs the harness.
Exit 0 means all 14 assertions passed. Final line: UAT harness: 14/14 assertions passed.
Local-debug mode
HEADLESS=0 npm run test:uat
Opens a real Chrome window so you can watch the picker auto-accept, the badge transitions, the popup appear, etc.
Developer iteration tricks
# Skip the production build inside assertion 0 (uses existing dist/):
SKIP_PROD_REBUILD=1 npm run test:uat
# Run the harness against an existing dist-test/ (skip npm run build:test):
npx tsx tests/uat/harness.test.ts
Assertion catalog
| # | Title | Bug class | Hook used |
|---|---|---|---|
| 0 | Production bundle has no test-hook leaks | T-1-11-01 | filesystem grep |
| 1 | SW bootstrap → setIdleMode | — | sw.evaluate |
| 2 | Toolbar onClicked-idle → REC + popup | — | triggerExtensionAction |
| 3 | Offscreen displaySurface === monitor | D-15 | __mokoshTest.getCurrentStream |
| 4 | Toolbar onClicked-recording → popup, no new offscreen | — | targets count |
| 5 | SAVE_ARCHIVE → download fires | — | downloads polling |
| 6 | BUG B: simulateUserStop → badge OFF + no recovery notif | b9eeeeb |
dispatchEvent('ended') |
| 7 | RECORDING_ERROR codec-unsupported → ERR + recovery notif | — | sendMessage |
| 8 | BUG A: onStartup → mokosh-startup- notification creates | a881bf0 |
__mokoshTest.handlers.onStartup |
| 9 | Icon file sizes meet floors | Bug A precondition | sw.evaluate(fetch) |
| 10 | Manifest has notifications + 3 icons | Bug A precondition | chrome.runtime.getManifest |
| 11 | 35s recording → segments.length >= 3 | D-13 | __mokoshTest.getSegmentCount |
| 12 | ffprobe on extracted webm exits 0 | Plan 01-08 | jszip + execFile |
| 13 | Archive shape — video + meta.json version match | Plan 01-07 | jszip |
Failure isolation
Single browser, serial assertions, bail on first failure for setup- dependent assertions (assertion 0 abort means refusing to launch a potentially-leaky bundle). Per-assertion bail keeps the diagnostic output unambiguous — see RESEARCH §5 + Plan 01-11 open-question resolution 4.
On failure, the harness dumps the last 30 lines of SW console + last 30 lines of offscreen console (captured live during the run) to stderr BEFORE rethrowing — gives you contextual triage without needing to re- run with debug logging.
Known gotchas
Locale-specific picker auto-accept
The --auto-select-desktop-capture-source=Entire screen Chrome flag
auto-accepts the screen-share picker. The string "Entire screen" is
en_US-specific. If your Chrome is set to a non-English locale, the
picker option label will differ and the auto-accept will silently fail
(picker stays open; assertion 2 times out).
Fallback: switch your Chrome user-data-dir's locale to en_US for
harness runs, OR adjust the launch arg in tests/uat/lib/launch.ts to
match your locale's equivalent string.
dev-dep Chromium binary size
puppeteer pulls a ~150 MB Chromium binary at npm install time. CI
must accept this. Production npm install --omit=dev skips it cleanly.
Xvfb is NOT required
Per Plan 01-11 RESEARCH §3 empirical probes against Chrome 148, the
--headless=new mode handles screen capture without Xvfb on Linux CI
runners. If a future Chrome regresses this, Xvfb :99 & DISPLAY=:99 npm run test:uat is the fallback.
CI runner screen-capture concern
The 35s recording assertion (A11) captures whatever is on screen during that window. CI MUST run the harness in an isolated container with no concurrent workload — see T-1-11-02 in Plan 01-11's threat model.
Real Chrome download (assertion 5 → A12)
The harness configures per-page download behavior via CDP to a fresh
os.tmpdir()/mokosh-uat-downloads-* directory; downloads are NOT
written to your real ~/Downloads. The temp directory is deleted by OS
tmpdir GC.