@learnquest/learner-smoke

Learner-view smoke test (post-beta roadmap P1, lq-core docs/design/2026-10-19-post-beta-roadmap-specs.md). It plays every live (app, language, learner locale) tree the way a learner does and asserts on what is rendered, not on files. File-level gates were green while learners saw hidden lessons, English answer options in th/zh trees, broken card art and silent audio; this is the check that looks at the screen.

Usage

# every live tree of every lq-* checkout under --root (default: $LQ_ROOT, or the parent of an lq-* cwd)
learner-smoke --app all --root ~/Repos-internal/learn-quest --workers 4 --json smoke.json --md smoke.md

# one app, some trees
learner-smoke --app lq-germanic --lang german --locale en,th

# a local build (manifests from the working tree, app at a local URL)
learner-smoke --app lq-germanic --worktree --root <dir> --base-url http://localhost:4173 --lang german --locale en

# print the matrix only
learner-smoke --app all --list

Boot check for dependency-bump PRs

vite build and unit tests do not prove that the app starts. lq-germanic #96 (a drill-engine override) passed both, and production was blank at boot: "Cannot set properties of undefined (setting 'pluralize')". Attach this to every dependency-bump PR as evidence. It takes a few seconds:

# in the app worktree with the bump
pnpm build
npx vite preview --port 4181 --strictPort &      # any free port
learner-smoke --app lq-germanic --worktree --root "$PWD" --base-url http://localhost:4181 --boot-only
# boot pass lq-germanic http://localhost:4181/ (1.1 s): booted in 1.0 s (378 chars rendered)
# boot FAIL lq-germanic http://localhost:4181/ (2.0 s): page error at boot: Cannot set properties of undefined (setting 'pluralize') (2.0 s)

--boot-only opens one fresh headless context per app origin and waits up to ~15 s for the consent gate or another app marker. It fails on an uncaught page error, an unhandled promise rejection, an HTTP error for the document, or an empty #root, and it reports the first page error verbatim. With --lang/--locale it boots /<locale>/ once per (app, lang, locale) instead. The output is one line per target and then the JSON (or the JSON goes to --json <file>). Exit 0 means everything booted; exit 1 means a boot failed. --app all --boot-only checks every deployed app.

--root takes a directory of lq-* checkouts, or a single checkout or worktree (any folder name, e.g. lq-germanic.worktrees/my-bump). In the second case --app names it.

Exit 0 when no step failed, 1 when one did, 2 on a usage or setup error. Needs Chromium for the resolved playwright (npx playwright install chromium once on a fresh machine).

The matrix

From the repos, never a list: per app blueforge.config.json (apps.web.domains[0]) and per language languages/<lang>/data/locale-manifest.json. A course is live when the manifest does not set enabled: false, en is enabled and en's maturity is not retired; its trees are the enabled, non-retired locales. shipChapters comes from the top level, else from locales.en; none means "every published chapter".

What one tree does

A fresh browser context (browser locale = the learner locale) and no account: nothing is posted; progress lives in the context's localStorage and dies with it.

| blob-origin | every media request the run made (image, audio, font) came from the blob host (VITE_ASSETS_BASE_URL, minio-backed), not from the app origin. An app serving its own media is serving a stale copy or bypassing the CDN entirely | A tree whose boot, picker, onboarding, chapters, visible, lessons, drill-xp or audio failed is played once more from scratch (deploy lag); the second attempt is the result and the report says (retried). The other steps are verdicts on the same content and are not replayed.

Not automated

• Lessons after lesson 1 are opened by deep link, not by playing every earlier lesson to unlock them.
• Only multiple-choice drills are completed; a drill with typed or ordering questions is skip.
• The en-options check sees only questions on the screens visited (ch1 lesson 1, concept, conversation, quiz, drill).