onboarding-export.test.ts

apps/dashboard/test/onboarding-export.test.ts

1. /**
2. * The training recap: what it carries, what it refuses to carry, and the seven
3. * absences it must keep apart.
4. *
5. * The first test is the point of the file. The page carries an "Accomplished:"
6. * line, a sentence about how somebody's first week went, and that reads exactly
7. * like the `did` box of her end-of-day note. It is not that. It is the
8. * trainer's own summary, in a reviewed config file, shown to the same people
9. * who can already open her plan; her words live in D1 behind CHECKIN_READERS,
10. * a shorter list than this page's audience. The control is not care, it is the
11. * import graph: this module can see `config/onboarding.ts` and nothing else.
12. * Whoever is next asked to "pull in what she actually said" will reach for
13. * `readableCheckinAuthors` long before they reach for a comment.
14. *
15. * What is not asserted: the recap's wording. It is a hand-written document
16. * that may be rewritten at any time, and tests assert properties, not wording.
17. */
19. import { readFile } from 'node:fs/promises'
20. import { fileURLToPath } from 'node:url'
21. import { describe, expect, it } from 'vitest'
22. import { EXPORT_CSS, INBOX_CSS_FOR_TEST, QUEUE_CSS, THEME_CSS } from './css-surface.js'
23. import {
24. EXPORT_BRIEF_TOPICS,
25. EXPORT_DEFAULT_DAYS,
26. EXPORT_WINDOWS,
27. addDays,
28. buildRecap,
29. parseWindow,
30. recapHtml,
31. recapPage,
32. recapRange,
33. recapText,
34. recapTextAll,
35. sentencesOf,
36. sliceFor,
37. } from '../src/onboarding-export.js'
38. import {
39. ONBOARDING,
40. hasOnboarding,
41. onboardingFor,
42. type OnboardingDay,
43. type OnboardingPlan,
44. } from '../../../config/onboarding.js'
45. import { MERIDIAN_PEOPLE } from '../../../config/meridian-people.js'
46. import { COMPANY_VIEWER, viewerFor } from '../src/viewer.js'
47. import { esc } from '../src/html.js'
49. const TODAY = '2026-09-16'
50. const plan = ONBOARDING[0]!
52. const PLAN = (over: Partial<OnboardingPlan> = {}): OnboardingPlan => ({
53. person: 'Rosa Galván',
54. role: 'Client Success',
55. startedOn: '2026-09-14',
56. active: true,
57. summary: 'x',
58. days: [],
59. resources: [],
60. sources: [],
61. recapDoc: { title: 'A Recap', preparedBy: 'Sam Whitaker' },
62. ...over,
63. })
65. /** A training day with topics but no write-up. */
66. const session = (day: number, date: string, titles: string[] = ['a']): OnboardingDay => ({
67. day,
68. date,
69. title: `Day ${day}`,
70. sections: titles.map((t) => ({ title: t })),
71. })
73. /** The same, written up. */
74. const written = (
75. day: number,
76. date: string,
77. over: Partial<NonNullable<OnboardingDay['recap']>> = {},
78. ): OnboardingDay => ({
79. ...session(day, date),
80. recap: {
81. label: 'A Session',
82. sessions: [{ points: ['did a thing'] }],
83. accomplished: 'a thing',
84. ...over,
85. },
86. })
88. const standing = (title = 'Every day'): OnboardingDay => ({
89. day: null,
90. date: null,
91. title,
92. sections: [{ title: 'x' }],
93. })
95. describe('it cannot leak a note, because it cannot see one', () => {
96. it('imports the onboarding config and nothing that touches the note store', async () => {
97. const src = await readFile(
98. fileURLToPath(new URL('../src/onboarding-export.ts', import.meta.url)),
99. 'utf8',
100. )
101. const imports = [...src.matchAll(/^import[\s\S]*?from '([^']+)'/gm)].map((m) => m[1]!)
102. for (const forbidden of ['checkin', 'checkin-view', 'checkin-store']) {
103. expect(
104. imports.filter((i) => i.includes(forbidden)),
105. `onboarding-export.ts must not import anything named ${forbidden}`,
106. ).toEqual([])
107. }
108. expect(imports.some((i) => i.includes('config/onboarding'))).toBe(true)
109. })
111. it('carries the authored recap and no prose from anywhere else', () => {
112. // Over the days the window selects, not every day on the plan. `TODAY` is
113. // frozen, so a session recorded after it is correctly future-dated and
114. // correctly absent.
115. const win = parseWindow('all', TODAY)
116. const text = recapTextAll([plan], win)
117. const shown = sliceFor(plan, win).sessions
118. expect(shown.length).toBeGreaterThan(0)
119. for (const d of shown) {
120. for (const s of d.recap?.sessions ?? []) {
121. for (const pt of s.points) expect(text, pt).toContain(pt)
122. }
123. }
124. expect(text).not.toMatch(/what I'm unsure about/i)
125. })
126. })
128. describe('the window', () => {
129. it('reads the listed values, and “all”', () => {
130. for (const n of EXPORT_WINDOWS) {
131. const w = parseWindow(String(n), TODAY)
132. expect(w.days).toBe(n)
133. expect(w.fellBack).toBe(false)
134. }
135. expect(parseWindow('all', TODAY).days).toBeNull()
136. expect(parseWindow('all', TODAY).from).toBeNull()
137. })
139. it('defaults quietly with no input, and LOUDLY with bad input', () => {
140. expect(parseWindow(null, TODAY)).toMatchObject({ days: EXPORT_DEFAULT_DAYS, fellBack: false })
141. for (const bad of ['99', 'seven', '-3', '1.5', '0']) {
142. expect(parseWindow(bad, TODAY), bad).toMatchObject({
143. days: EXPORT_DEFAULT_DAYS,
144. fellBack: true,
145. })
146. }
147. })
149. it('counts a one-day window as today, not as yesterday', () => {
150. expect(parseWindow('1', TODAY)).toMatchObject({ from: TODAY, to: TODAY })
151. expect(parseWindow('3', TODAY).from).toBe('2026-09-14')
152. expect(addDays(TODAY, -2)).toBe('2026-09-14')
153. expect(addDays('2026-01-01', -1)).toBe('2025-12-31')
154. })
155. })
157. describe('what the window selects', () => {
158. const p = PLAN({
159. days: [standing(), written(1, '2026-09-01'), written(2, '2026-09-15'), standing('Reference')],
160. })
162. it('takes the dated days inside it, in order', () => {
163. const s = sliceFor(p, parseWindow('7', TODAY))
164. expect(s.sessions.map((d) => d.day)).toEqual([2])
165. expect(s.lastBefore?.day).toBe(1)
166. expect(s.totalSessions).toBe(2)
167. })
169. it('NEVER includes standing material, and says how much it held back', () => {
170. for (const w of ['1', '7', 'all']) {
171. const s = sliceFor(p, parseWindow(w, TODAY))
172. expect(s.sessions.every((d) => d.day !== null), w).toBe(true)
173. expect(s.standingHeld, w).toBe(2)
174. }
175. expect(recapText(buildRecap(p, parseWindow('all', TODAY)))).toContain('2 other sections')
176. })
178. it('does not show a day dated in the future', () => {
179. const future = PLAN({ days: [written(9, '2026-12-25')] })
180. expect(sliceFor(future, parseWindow('all', TODAY)).sessions).toEqual([])
181. })
182. })
184. /**
185. * The seven states. Collapsing any two turns "nobody has written this up" into
186. * "nothing happened", and this document is the evidence somebody's first weeks
187. * are going well, so that is the version of the prime invariant that actually
188. * misleads a person rather than merely a spreadsheet.
189. */
190. describe('the seven things that must not look alike', () => {
191. const states = {
192. written: () => buildRecap(PLAN({ days: [written(1, TODAY)] }), parseWindow('1', TODAY)),
193. noRecap: () => buildRecap(PLAN({ days: [session(1, TODAY)] }), parseWindow('1', TODAY)),
194. noAccomplished: () =>
195. buildRecap(
196. PLAN({ days: [written(1, TODAY, { accomplished: null })] }),
197. parseWindow('1', TODAY),
198. ),
199. emptyWindow: () =>
200. buildRecap(PLAN({ days: [written(1, '2026-09-01')] }), parseWindow('3', TODAY)),
201. noDays: () => buildRecap(PLAN({ days: [standing()] }), parseWindow('3', TODAY)),
202. noRecapAnywhere: () =>
203. buildRecap(PLAN({ days: [session(1, TODAY), session(2, TODAY)] }), parseWindow('7', TODAY)),
204. }
206. it('a day with no recap still RENDERS, so the day count cannot shrink', () => {
207. const m = states.noRecap()
208. expect(m.blocks).toHaveLength(1)
209. expect(m.blocks[0]!.kind).toBe('none')
210. expect(recapText(m)).toMatch(/no recap has been written for this day yet/i)
211. // And it carries the evidence that the day happened at all.
212. expect(recapText(m)).toMatch(/the training plan records 1 topic under it/i)
213. })
215. it('a null accomplished says "not recorded", never a bare label', () => {
216. const t = recapText(states.noAccomplished())
217. expect(t).toMatch(/accomplished: not recorded for this day/i)
218. expect(t).not.toMatch(/Accomplished:\s*$/m)
219. })
221. it('an empty window names the most recent day, so the next move is obvious', () => {
222. const t = recapText(states.emptyWindow())
223. expect(t).toMatch(/no training days fall in this window/i)
224. expect(t).toContain('Day 1')
225. })
227. it('a plan with no training days says something DIFFERENT, with no window language', () => {
228. const t = recapText(states.noDays())
229. expect(t).toMatch(/no training days are recorded on this plan yet/i)
230. expect(t).not.toMatch(/in this window/i)
231. })
233. it('days with no recap anywhere still list the days', () => {
234. const m = states.noRecapAnywhere()
235. expect(m.empty).toMatch(/no recap has been written for this plan yet/i)
236. expect(m.blocks).toHaveLength(2)
237. })
239. it('no visible plan exports nothing, rather than an empty document', () => {
240. expect(recapTextAll([], parseWindow('7', TODAY))).toMatch(/no onboarding plans/i)
241. })
243. it('produces a DISTINCT rendering for every one of them', () => {
244. // The test that catches a future refactor folding two absences together.
245. const seen = new Map<string, string>()
246. for (const [name, build] of Object.entries(states)) {
247. const line = recapText(build())
248. expect(seen.has(line), `${name} reads identically to ${seen.get(line)}`).toBe(false)
249. seen.set(line, name)
250. }
251. expect(seen.size).toBe(Object.keys(states).length)
252. })
253. })
255. describe('it never claims fewer training days than happened', () => {
256. it('renders one block per training day in the window, written or not', () => {
257. const p = PLAN({ days: [written(1, '2026-09-14'), session(2, '2026-09-15'), standing()] })
258. const m = buildRecap(p, parseWindow('all', TODAY))
259. expect(m.blocks).toHaveLength(2)
260. expect(m.blocks.map((b) => b.kind)).toEqual(['recap', 'none'])
261. })
263. it('states coverage at EVERY window, including when nothing was withheld', () => {
264. // Rule 9: "3 of 3" is a claim worth making out loud. Leaving it off when
265. // nothing is missing means completeness has to be inferred from silence,
266. // and silence is what a bug looks like too.
267. for (const w of [...EXPORT_WINDOWS.map(String), 'all']) {
268. const win = parseWindow(w, TODAY)
269. const m = buildRecap(plan, win)
270. expect(m.coverage, w).toContain(
271. `Covering ${m.blocks.length} of ${sliceFor(plan, win).totalSessions}`,
272. )
273. }
274. })
276. it('never says the recap points are a truncation of the plan topics', () => {
277. // Eight curated points are not "the first 8 of 11", and "… and 3 more"
278. // would promise a list the reader cannot reach. The disclosure is made
279. // ONCE, in the footer, because it is a fact about the document.
280. const m = buildRecap(plan, parseWindow('all', TODAY))
281. expect(m.coverage).toMatch(/curated write-ups/i)
282. const text = recapText(m)
283. expect((text.match(/curated write-ups/gi) ?? []).length).toBe(1)
284. for (const b of m.blocks) {
285. if (b.kind !== 'recap') continue
286. for (const s of b.sessions) expect(s.points.join(' ')).not.toMatch(/and \d+ more/)
287. }
288. })
290. it('still truncates-and-labels the ONE list that IS a truncation', () => {
291. // Rule 5 keeps a home: the plan-topic evidence line under a day nobody has
292. // written up yet.
293. const many = Array.from({ length: EXPORT_BRIEF_TOPICS + 3 }, (_, i) => `t${i}`)
294. const m = buildRecap(PLAN({ days: [session(1, TODAY, many)] }), parseWindow('1', TODAY))
295. const b = m.blocks[0]!
296. expect(b.kind).toBe('none')
297. if (b.kind === 'none') {
298. expect(b.sentence).toContain('and 3 more')
299. expect(b.sentence).toContain(`${many.length} topics`)
300. }
301. })
302. })
304. describe('the subtitle', () => {
305. it('never asserts a range wider than what it shows', () => {
306. for (const w of [...EXPORT_WINDOWS.map(String), 'all']) {
307. const win = parseWindow(w, TODAY)
308. const dates = sliceFor(plan, win).sessions.map((d) => d.date!)
309. if (!dates.length) continue
310. const sub = buildRecap(plan, win).subtitle!
311. expect(sub, w).toContain(String(Number(dates[0]!.slice(8))))
312. expect(sub, w).toContain(String(Number(dates.at(-1)!.slice(8))))
313. }
314. })
316. it('formats one day, a same-month span, a cross-month span and a cross-year span', () => {
317. const d = (x: string) => session(1, x)
318. expect(recapRange([d('2026-09-14')])).toBe('September 14, 2026')
319. expect(recapRange([d('2026-09-14'), d('2026-09-16')])).toBe('September 14 to 16, 2026')
320. expect(recapRange([d('2026-09-28'), d('2026-10-02')])).toBe('September 28 to October 2, 2026')
321. expect(recapRange([d('2026-12-30'), d('2027-01-02')])).toBe(
322. 'December 30, 2026 to January 2, 2027',
323. )
324. expect(recapRange([])).toBeNull()
325. })
327. it('takes the role from the roster rather than storing a second spelling', () => {
328. // The role comes from the roster: one fact, one place.
329. expect(buildRecap(plan, parseWindow('all', TODAY)).subtitle).toContain(plan.role)
330. })
331. })
333. describe('the document and the clipboard say the same thing', () => {
334. it('puts every sentence of the model into both renderers', () => {
335. // What "build once, render twice" buys, and it is only true if something
336. // checks it.
337. for (const w of ['1', '7', 'all']) {
338. const m = buildRecap(plan, parseWindow(w, TODAY))
339. const html = recapHtml(m)
340. const text = recapText(m)
341. for (const s of sentencesOf(m)) {
342. expect(html, `html/${w}: ${s}`).toContain(esc(s))
343. expect(text, `text/${w}: ${s}`).toContain(s)
344. }
345. }
346. })
348. it('escapes once in HTML and leaves the text raw, so a pasted apostrophe is one', () => {
349. // The recap prose is dense with them ("the client's order history", "a
350. // client's stated budget").
351. const p = PLAN({
352. days: [written(1, TODAY, { sessions: [{ points: ["a client's budget & scope"] }] })],
353. })
354. const m = buildRecap(p, parseWindow('1', TODAY))
355. expect(recapHtml(m)).toContain('a client's budget & scope')
356. expect(recapHtml(m)).not.toContain(''')
357. expect(recapText(m)).toContain("a client's budget & scope")
358. })
359. })
361. describe('who can run it', () => {
362. const viewers = [
363. ...MERIDIAN_PEOPLE.map((p) => viewerFor(p.email)),
364. COMPANY_VIEWER,
365. viewerFor(null),
366. viewerFor('stranger@example.com'),
367. ]
369. it('never lets the gate and the content disagree', () => {
370. for (const v of viewers) {
371. expect(hasOnboarding(v), v.email ?? 'anonymous').toBe(onboardingFor(v).length > 0)
372. }
373. })
375. it('gives everyone who gets in exactly the plans they may already read', () => {
376. for (const v of viewers) {
377. const visible = onboardingFor(v)
378. const text = recapTextAll(visible, parseWindow('all', TODAY))
379. for (const other of ONBOARDING) {
380. const mayRead = visible.some((p) => p.person === other.person)
381. const doc = other.recapDoc?.title
382. if (doc) expect(text.includes(doc), `${v.email ?? 'anonymous'} / ${other.person}`).toBe(mayRead)
383. }
384. if (!visible.length) expect(text).toMatch(/no onboarding plans/i)
385. }
386. })
388. it('lets Nora run it, and Rosa read her own', () => {
389. // Anyone who asks the morning question can run it themselves, the trainee
390. // included.
391. for (const email of ['nora.l@meridiandisplay.example', 'accounts@meridiandisplay.example']) {
392. const v = viewerFor(email)
393. expect(hasOnboarding(v), email).toBe(true)
394. expect(recapTextAll(onboardingFor(v), parseWindow('7', TODAY)), email).toContain(
395. 'Training Recap',
396. )
397. }
398. })
399. })
401. describe('the page is actually styled where it is actually served', () => {
402. const served = THEME_CSS + INBOX_CSS_FOR_TEST + EXPORT_CSS
404. it('defines every class the recap page emits', () => {
405. const html = recapPage(ONBOARDING, parseWindow('7', TODAY), '7')
406. const used = new Set(
407. [...html.matchAll(/class="([^"]+)"/g)].flatMap((m) => m[1]!.trim().split(/\s+/)),
408. )
409. expect(used.size).toBeGreaterThan(4)
410. for (const cls of used) {
411. expect(
412. served,
413. `.${cls} is emitted by the recap page but styled nowhere it is served`,
414. ).toContain(`.${cls}`)
415. }
416. })
418. it('puts the print rules in the sheet the Worker serves, not the board-only one', () => {
419. // QUEUE_CSS never reaches a Worker-served page, and the .ob-* rules already
420. // in it invite putting export rules there by mistake.
421. expect(EXPORT_CSS).toContain('@page')
422. expect(EXPORT_CSS).toContain('@media print')
423. expect(QUEUE_CSS).not.toContain('.rc-')
424. })
426. it('does not need background printing to be legible', () => {
427. // Browsers default to NOT printing backgrounds, so a document leaning on
428. // fills prints wrong for most people the first time.
429. //
430. // Removing a fill is fine and is not what this guards: `background:none`
431. // is how the on-screen card stops being a card on paper. What must not
432. // appear is a fill the layout depends on, or print-color-adjust forcing the
433. // reader's settings.
434. const block = EXPORT_CSS.slice(EXPORT_CSS.indexOf('@media print'))
435. const fills = [...block.matchAll(/background[^;}]*/g)].map((m) => m[0])
436. for (const f of fills) expect(f, f).toMatch(/:\s*(none|transparent)\s*$/)
437. expect(block).not.toMatch(/print-color-adjust/)
438. })
440. it('keeps the document out of a .card, so a long recap can paginate', () => {
441. // THEME_CSS's print block sets .card{break-inside:avoid}; the wrapper holds
442. // the WHOLE document, which runs to several pages once a few days are in.
443. // Asking a box taller than the sheet not to break produces a worse break
444. // than letting it.
445. //
446. // Asserted on the PAGE, not just the document fragment: the fragment never
447. // had a card, and the first version of this wrapper did.
448. const page = recapPage(ONBOARDING, parseWindow('all', TODAY), 'all')
449. expect(page).toContain('<article class="rc-doc">')
450. const shell = page.slice(page.indexOf('rc-shell'))
451. expect(shell.slice(0, shell.indexOf('</div>'))).not.toContain('class="card"')
452. // And the only `card` on the page is nowhere near the document.
453. expect(page).not.toMatch(/class="card[^"]*"[\s\S]{0,200}rc-doc/)
454. })
455. })
457. describe('the links on the page carry what they say', () => {
458. const unescape = (s: string): string =>
459. s.replace(/&/g, '&').replace(/"/g, '"').replace(/'/g, "'")
461. const parse = (html: string): URL[] =>
462. [...html.matchAll(/href="([^"]+)"/g)]
463. .map((m) => unescape(m[1]!))
464. .filter((h) => h.startsWith('/onboarding/export'))
465. .map((h) => new URL(h, 'https://board.example'))
467. it('never emits a parameter the Worker would not recognise', () => {
468. // `amp;days` is what a double-escape produces and is indistinguishable
469. // from a typo at the far end.
470. const allowed = new Set(['days', 'format'])
471. for (const u of parse(recapPage(ONBOARDING, parseWindow('7', TODAY), '7'))) {
472. for (const key of u.searchParams.keys()) {
473. expect(allowed.has(key), `${u.href} carries "${key}"`).toBe(true)
474. }
475. }
476. })
478. it('offers every window, and a plain-text twin of the one you are on', () => {
479. const links = parse(recapPage(ONBOARDING, parseWindow('3', TODAY), '3'))
480. expect(links.filter((u) => !u.searchParams.has('format'))).toHaveLength(
481. EXPORT_WINDOWS.length + 1,
482. )
483. const txt = links.filter((u) => u.searchParams.get('format') === 'txt')
484. expect(txt).toHaveLength(1)
485. expect(txt[0]!.searchParams.get('days')).toBe('3')
486. })
488. it('round-trips every link back through the parser it ships with', () => {
489. for (const u of parse(recapPage(ONBOARDING, parseWindow('3', TODAY), '3'))) {
490. expect(parseWindow(u.searchParams.get('days'), TODAY).fellBack, u.href).toBe(false)
491. }
492. })
494. it('says so when a retired parameter is passed, rather than ignoring it', () => {
495. // `&detail=full` links exist for a retired control; the page acknowledges
496. // the parameter rather than ignoring it.
497. expect(recapPage(ONBOARDING, parseWindow('7', TODAY), '7', true)).toContain('no longer does')
498. expect(recapPage(ONBOARDING, parseWindow('7', TODAY), '7', false)).not.toContain(
499. 'no longer does',
500. )
501. })
502. })
504. describe('the committed plan', () => {
505. it('has a recap on every training day, and none on any standing group', () => {
506. for (const d of plan.days) {
507. if (d.day === null) expect(d.recap, d.title).toBeUndefined()
508. else expect(d.recap, d.title).toBeDefined()
509. }
510. })
512. it('renders as the document it was seeded from', () => {
513. // DERIVED, not pinned at 3: every training day in the window gets a block,
514. // and every one of them is written up. A hardcoded count here measures only
515. // how long ago the test was written.
516. const win = parseWindow('all', TODAY)
517. const m = buildRecap(plan, win)
518. expect(m.title).toBeTruthy()
519. expect(m.blocks).toHaveLength(sliceFor(plan, win).sessions.length)
520. expect(m.blocks.length).toBeGreaterThan(0)
521. expect(m.blocks.every((b) => b.kind === 'recap')).toBe(true)
522. expect(m.empty).toBeNull()
523. })
524. })