@lernapps/app-templates 0.1.0 → 0.2.0

package/runtime/explainer/e2e.ts

@@ -1,9 +1,15 @@
-// The end-to-end tests of every explainer (@lernapps/app-templates/explainer/e2e), run by `lernapps check --pre-push`
-// on the built app with the app's own content. An app's e2e/explainer.e2e.ts is
+// The end-to-end tests of the explainer (@lernapps/app-templates/explainer/e2e), run by `lernapps check --pre-push` on
+// the built app with its own content, in two parts. explainerTests() tests the app's content, and every app runs it:
+// its e2e/explainer.e2e.ts, part of the scaffold, is
 //
 //   import { explainerTests } from "@lernapps/app-templates/explainer/e2e";
 //   explainerTests();
 //
+// Without JavaScript every page as its content says, in every language; previous and next (at desktop width); the
+// app's own components and the checks of its exercise components. explainerRuntimeTests() tests the runtime, the same
+// in every app: the exercises of each type, the videos, the tutor ways, the start page, the self-assessments and what
+// is stored. Only this repo runs it, on the template and its fixtures (explainer/e2e/runtime.e2e.ts, not in the
+// scaffold). What follows is what the two parts check together.
 // What they expect comes from the content in src/ (outline.ts), not from the rendered pages. Without JavaScript, for
 // every page in every language: the heading levels follow the nesting (page h1, section h2, subsection h3, a box one
 // below its place), every section heading is visible, the number of <math> elements is the number of formulas in the
@@ -67,6 +73,7 @@ import { message as messageOf } from "./messages.ts";
 import { ASSESSMENT_TASK_EVENT, nextTaskNumber, taskNumber } from "./tasks.ts";
 import {
   outline,
+  shownText,
   type AssessmentOutline,
   type ComponentOutline,
   type ExerciseOutline,
@@ -157,6 +164,12 @@ const BAND_WORDS = {
   unasked: "assessmentUnasked",
 } as const;
 
+/**
+ * `text` without space. A browser's text of a formula has space between its parts ("2 7" for 2⁷) where the content's
+ * has none, so texts with formulas are compared without it (in the order of their characters, which is what counts).
+ */
+const squash = (text: string): string => text.replace(/\s+/g, "");
+
 /** The task number of the deep link the tests open a generated exercise with. */
 const SEED = 7;
 
@@ -169,7 +182,7 @@ async function expectExercises(page: Page, item: PageOutline): Promise<void> {
   const main = page.locator("main");
   const expected = item.exercises.map((exercise) =>
     exercise.kind === "question"
-      ? { id: exercise.id, texts: [exercise.question.text], answers: [exercise.answers] }
+      ? { id: exercise.id, texts: [shownText(exercise.question.text)], answers: [exercise.answers] }
       : exercise.kind === "open"
         ? { id: exercise.id, texts: [exercise.task], answers: [exercise.solution] }
         : {
@@ -178,29 +191,31 @@ async function expectExercises(page: Page, item: PageOutline): Promise<void> {
             answers: exercise.worked.map((worked) => [worked.answer]),
           },
   );
-  const read = () =>
-    main.locator(".explainer-exercise").evaluateAll((elements) =>
-      elements.map((element) => {
-        const fold = (text: string | null) => (text ?? "").replace(/\s+/g, " ").trim();
-        const own = element.classList.contains("explainer-question")
-          ? [...element.querySelectorAll("legend")]
-          : element.classList.contains("explainer-open-task")
-            ? [...element.querySelectorAll(":scope > .explainer-open-task-text")]
-            : [...element.querySelectorAll(".explainer-worked-task > .explainer-task")];
-        const solutions = [...element.querySelectorAll<HTMLDetailsElement>("details.explainer-solution")];
-        return {
-          id: element.id,
-          texts: own.map((text) => fold(text.textContent)),
-          // what a learner sees of each "Lösung": nothing while it is closed
-          shown: solutions.map((details) => (details.open ? fold((details as HTMLElement).innerText) : "")),
-        };
-      }),
-    );
+  const read = async () =>
+    (
+      await main.locator(".explainer-exercise").evaluateAll((elements) =>
+        elements.map((element) => {
+          const fold = (text: string | null) => (text ?? "").replace(/\s+/g, " ").trim();
+          const own = element.classList.contains("explainer-question")
+            ? [...element.querySelectorAll("legend")]
+            : element.classList.contains("explainer-open-task")
+              ? [...element.querySelectorAll(":scope > .explainer-open-task-text")]
+              : [...element.querySelectorAll(".explainer-worked-task > .explainer-task")];
+          const solutions = [...element.querySelectorAll<HTMLDetailsElement>("details.explainer-solution")];
+          return {
+            id: element.id,
+            texts: own.map((text) => fold(text.textContent)),
+            // what a learner sees of each "Lösung": nothing while it is closed
+            shown: solutions.map((details) => (details.open ? fold((details as HTMLElement).innerText) : "")),
+          };
+        }),
+      )
+    ).map((item) => ({ ...item, texts: item.texts.map(squash), shown: item.shown.map(squash) }));
   const before = await read();
   expect(
     before.map(({ id, texts }) => ({ id, texts })),
     `${item.url}: each exercise with its text`,
-  ).toEqual(expected.map(({ id, texts }) => ({ id, texts })));
+  ).toEqual(expected.map(({ id, texts }) => ({ id, texts: texts.map(squash) })));
   // a click on each summary, as a learner opens a <details> (its own behaviour, no script of the page)
   await main
     .locator(".explainer-exercise details.explainer-solution > summary")
@@ -212,7 +227,7 @@ async function expectExercises(page: Page, item: PageOutline): Promise<void> {
         expect(
           after[index]?.shown[at] ?? "",
           `${item.url}: ${exercise.id}, Lösung ${at + 1} shows ${answer}`,
-        ).toContain(answer);
+        ).toContain(squash(answer));
       }
     });
   }
@@ -484,7 +499,9 @@ const feedback = (page: Page, id: string) => page.locator(`[id="${id}"] .questio
 function reasonFor(question: Question, answer: Answer): string {
   const quiz = questionMessagesIn("de");
   const [first] = wrongReasons(question, answer);
-  if (first !== undefined) return first.option === undefined ? first.text : `${first.option}: ${first.text}`;
+  if (first !== undefined) {
+    return first.option === undefined ? shownText(first.text) : `${shownText(first.option)}: ${shownText(first.text)}`;
+  }
   return missesRight(question, answer) ? quiz.missingRight : quiz.lookAgain;
 }
 
@@ -495,9 +512,12 @@ function reasonFor(question: Question, answer: Answer): string {
 async function wrongThenSolution(page: Page, exercise: string, question: Question, reason: string): Promise<void> {
   const item = page.locator(`[id="${questionId(question)}"]`);
   await expect(feedback(page, questionId(question))).toContainText(questionMessagesIn("de").wrong);
-  await expect(item.locator(".question-diagnosis").first(), `${exercise}: the reason of the wrong answer`).toHaveText(
-    reason,
-  );
+  await expect
+    .poll(
+      async () => squash((await item.locator(".question-diagnosis").first().textContent()) ?? ""),
+      `${exercise}: the reason of the wrong answer`,
+    )
+    .toBe(squash(reason));
   await expectFeedbackInView(page, question);
   await expect(item.locator(".question-reveal"), `${exercise}: no solution after a wrong answer`).toBeHidden();
   await expect(item.locator("input, select").first(), `${exercise}: another try`).toBeEnabled();
@@ -813,148 +833,183 @@ async function expectResultLine(
   expect(await response.text(), "the tutor page has the exercise").toContain(id);
 }
 
-/** The explainer's tests, for the content in `root`/src. */
+/**
+ * The tests of an explainer's content, for the content in `root`/src: what every app runs (e2e/explainer.e2e.ts).
+ * Without JavaScript every page as its content says, previous and next, the app's own components and the checks of
+ * its exercise components. What the runtime does the same in every app is explainerRuntimeTests.
+ */
 export function explainerTests(root = "."): void {
+  explainerSuite(root, "content");
+}
+
+/**
+ * The tests of the explainer's runtime on the content in `root`/src: the exercises of each type, the videos, the tutor
+ * ways, the start page, the self-assessments, what is stored. The template folder and the fixtures of
+ * lernapps/app-templates run them (e2e/runtime.e2e.ts); an app does not, its scaffold has no such file: they test the
+ * runtime, which is the same in every app, not the app's content.
+ */
+export function explainerRuntimeTests(root = "."): void {
+  explainerSuite(root, "runtime");
+}
+
+/** Only at desktop width, in a test of what does not depend on the width; what a page shows is tested at 360 px too. */
+const desktopOnly = (page: Page) => test.skip((page.viewportSize()?.width ?? 0) <= 400, "only at desktop width");
+
+function explainerSuite(root: string, part: "content" | "runtime"): void {
   const app = outline(root);
+  const content = part === "content";
 
   test.describe("explainer", () => {
     test.describe.configure({ mode: "parallel" });
     test.use({ reducedMotion: "reduce" });
 
-    test.describe("without JavaScript", () => {
-      test.use({ javaScriptEnabled: false });
+    if (content)
+      test.describe("without JavaScript", () => {
+        test.use({ javaScriptEnabled: false });
 
-      for (const lang of app.languages) {
-        for (const item of app.pages[lang] ?? []) {
-          test(`${item.url || "./"}: headings, sections, formulas, figures and anchors as in the content`, async ({
-            page,
-          }) => {
-            await page.goto(`./${item.url}`);
-            const main = page.locator("main");
-            const headings = await main.locator("h1, h2, h3, h4, h5, h6").evaluateAll((elements) =>
-              elements.map((element) => ({
-                level: Number(element.tagName.slice(1)),
-                text: (element.textContent ?? "").replace(/\s+/g, " ").trim(),
-              })),
-            );
-            expect(headings, "the heading levels follow the nesting").toEqual(item.headings);
-            for (const section of item.sections) {
-              const heading = page.locator(`[id="${section.id}"]`);
-              await expect(heading, `section ${section.id}`).toBeVisible();
-              await expect(heading).toHaveText(section.title);
-            }
-            // the formulas of the content; an exercise component's no-JS task, from its describe, is not content
-            const formulas = await main
-              .locator("math")
-              .evaluateAll((elements) => elements.filter((math) => !math.closest(".explainer-described")).length);
-            expect(formulas, "one <math> per formula").toBe(item.formulas);
-            for (const name of item.figures) {
-              await expect(main.getByRole("img", { name, exact: true }).first(), `the figure "${name}"`).toBeVisible();
-            }
-            await expectAnchors(page);
-            await expectLanguages(page, item, app.languages);
-            await expectExercises(page, item);
-            await expectNojs(page, item);
-            await expectVideos(page, item);
-          });
-        }
+        for (const lang of app.languages) {
+          for (const item of app.pages[lang] ?? []) {
+            test(`${item.url || "./"}: headings, sections, formulas, figures and anchors as in the content`, async ({
+              page,
+            }) => {
+              await page.goto(`./${item.url}`);
+              const main = page.locator("main");
+              const headings = await main.locator("h1, h2, h3, h4, h5, h6").evaluateAll((elements) =>
+                elements.map((element) => ({
+                  level: Number(element.tagName.slice(1)),
+                  text: (element.textContent ?? "").replace(/\s+/g, " ").trim(),
+                })),
+              );
+              expect(headings, "the heading levels follow the nesting").toEqual(item.headings);
+              for (const section of item.sections) {
+                const heading = page.locator(`[id="${section.id}"]`);
+                await expect(heading, `section ${section.id}`).toBeVisible();
+                await expect(heading).toHaveText(section.title);
+              }
+              // the formulas of the content; an exercise component's no-JS task, from its describe, is not content
+              const formulas = await main
+                .locator("math")
+                .evaluateAll((elements) => elements.filter((math) => !math.closest(".explainer-described")).length);
+              expect(formulas, "one <math> per formula").toBe(item.formulas);
+              for (const name of item.figures) {
+                await expect(
+                  main.getByRole("img", { name, exact: true }).first(),
+                  `the figure "${name}"`,
+                ).toBeVisible();
+              }
+              await expectAnchors(page);
+              await expectLanguages(page, item, app.languages);
+              await expectExercises(page, item);
+              await expectNojs(page, item);
+              await expectVideos(page, item);
+            });
+          }
+
+          for (const item of app.others[lang] ?? []) {
+            test(`${item.url || "./"}: its heading, its links and anchors, its languages`, async ({ page }) => {
+              await page.goto(`./${item.url}`);
+              await expect(page.locator("main h1")).toHaveText(item.title);
+              await expectAnchors(page);
+              await expectLanguages(page, item, app.languages);
+              // only a content page starts a tutor; the start page says what it is
+              await expect(page.locator(".explainer-tutor"), "no way to the tutor here").toHaveCount(0);
+              if (item.kind === "start") {
+                await expect(page.locator(".explainer-tutor-about h2")).toHaveText(messageOf(item.lang, "tutorTitle"));
+              }
+            });
+          }
 
-        for (const item of app.others[lang] ?? []) {
-          test(`${item.url || "./"}: its heading, its links and anchors, its languages`, async ({ page }) => {
-            await page.goto(`./${item.url}`);
-            await expect(page.locator("main h1")).toHaveText(item.title);
-            await expectAnchors(page);
-            await expectLanguages(page, item, app.languages);
-            // only a content page starts a tutor; the start page says what it is
-            await expect(page.locator(".explainer-tutor"), "no way to the tutor here").toHaveCount(0);
-            if (item.kind === "start") {
-              await expect(page.locator(".explainer-tutor-about h2")).toHaveText(messageOf(item.lang, "tutorTitle"));
+          test(`${lang}: previous and next form one chain over all pages`, async ({ page }) => {
+            desktopOnly(page);
+            const order = (app.pages[lang] ?? []).map((item) => item.url);
+            const first = order[0];
+            if (first === undefined) throw new Error(`no page in ${lang}`);
+            const relative = (url: string) => {
+              const path = new URL(url).pathname;
+              const at = order.find((candidate) => path.endsWith(`/${candidate}`));
+              return at ?? path;
+            };
+            const forward: string[] = [];
+            await page.goto(`./${first}`);
+            for (let step = 0; step <= order.length; step++) {
+              forward.push(relative(page.url()));
+              const next = page.locator('a[rel="next"]');
+              if ((await next.count()) === 0) break;
+              // the next page before its links count: a large page may still load when the loop looks again
+              const here = page.url();
+              await next.click();
+              await page.waitForURL((url) => url.href !== here);
+            }
+            expect(forward, "next leads through every page in order").toEqual(order);
+            const backward: string[] = [];
+            for (let step = 0; step <= order.length; step++) {
+              backward.push(relative(page.url()));
+              const previous = page.locator('a[rel="prev"]');
+              if ((await previous.count()) === 0) break;
+              const here = page.url();
+              await previous.click();
+              await page.waitForURL((url) => url.href !== here);
             }
+            expect(backward, "previous leads back through every page").toEqual([...order].reverse());
           });
         }
-
-        test(`${lang}: previous and next form one chain over all pages`, async ({ page }) => {
-          const order = (app.pages[lang] ?? []).map((item) => item.url);
-          const first = order[0];
-          if (first === undefined) throw new Error(`no page in ${lang}`);
-          const relative = (url: string) => {
-            const path = new URL(url).pathname;
-            const at = order.find((candidate) => path.endsWith(`/${candidate}`));
-            return at ?? path;
-          };
-          const forward: string[] = [];
-          await page.goto(`./${first}`);
-          for (let step = 0; step <= order.length; step++) {
-            forward.push(relative(page.url()));
-            const next = page.locator('a[rel="next"]');
-            if ((await next.count()) === 0) break;
-            // the next page before its links count: a large page may still load when the loop looks again
-            const here = page.url();
-            await next.click();
-            await page.waitForURL((url) => url.href !== here);
-          }
-          expect(forward, "next leads through every page in order").toEqual(order);
-          const backward: string[] = [];
-          for (let step = 0; step <= order.length; step++) {
-            backward.push(relative(page.url()));
-            const previous = page.locator('a[rel="prev"]');
-            if ((await previous.count()) === 0) break;
-            const here = page.url();
-            await previous.click();
-            await page.waitForURL((url) => url.href !== here);
-          }
-          expect(backward, "previous leads back through every page").toEqual([...order].reverse());
-        });
-      }
-    });
+      });
 
     // with JavaScript in German, one exercise of each type per page; the other languages render the same code
     test.describe("with JavaScript", () => {
       // at the narrowest width only, where the feedback is hardest to keep in view: the exercises' logic is the same
       // at every width, and the hooks stay fast
       test.skip(({ viewport }) => (viewport?.width ?? 0) > 400, "the exercises run at 360 px");
-      for (const item of app.pages["de"] ?? []) {
-        const types = new Map<string, ExerciseOutline>();
-        for (const exercise of item.exercises) if (!types.has(exercise.type)) types.set(exercise.type, exercise);
-        if (types.size === 0) continue;
-        test(`${item.url}: one exercise of each type checks its answers (${[...types.keys()].join(", ")})`, async ({
-          page,
-        }) => {
-          for (const exercise of types.values()) {
-            if (exercise.kind === "question") await checkQuestion(page, item.url, exercise);
-            else if (exercise.kind === "open") await checkOpenTask(page, item.url, exercise);
-            else await checkGenerated(page, item.url, exercise);
-          }
-          // only an open task keeps something, its answer, and only while the tab is open
-          expect(await page.evaluate(() => Object.keys(localStorage))).toEqual([]);
-          const kept = await page.evaluate(() => Object.keys(sessionStorage));
-          expect(
-            kept.filter((key) => !/^lernapps:[^:]+:antwort:/.test(key)),
-            "nothing else in the tab",
-          ).toEqual([]);
-          expect(kept.length, "an answer per open task").toBe(types.has("open-task") ? 1 : 0);
-        });
-      }
-      for (const item of app.pages["de"] ?? []) {
-        if (item.videos.length === 0) continue;
-        test(`${item.url}: the videos load nothing before a click, the player after it, directly once chosen`, async ({
-          page,
-          baseURL,
-        }) => {
-          await checkVideos(page, item, new URL(baseURL ?? page.url()).origin);
-        });
-      }
-      for (const item of app.pages["de"] ?? []) {
-        if (item.components.length === 0) continue;
-        test(`${item.url}: each component hydrates without a console error (${item.components.map((component) => component.name).join(", ")})`, async ({
-          page,
-        }) => {
-          await checkComponents(page, item);
-          expect(await page.evaluate(() => [...Object.keys(localStorage), ...Object.keys(sessionStorage)])).toEqual([]);
-        });
-      }
+      if (!content)
+        for (const item of app.pages["de"] ?? []) {
+          const types = new Map<string, ExerciseOutline>();
+          for (const exercise of item.exercises) if (!types.has(exercise.type)) types.set(exercise.type, exercise);
+          if (types.size === 0) continue;
+          test(`${item.url}: one exercise of each type checks its answers (${[...types.keys()].join(", ")})`, async ({
+            page,
+          }) => {
+            for (const exercise of types.values()) {
+              if (exercise.kind === "question") await checkQuestion(page, item.url, exercise);
+              else if (exercise.kind === "open") await checkOpenTask(page, item.url, exercise);
+              else await checkGenerated(page, item.url, exercise);
+            }
+            // only an open task keeps something, its answer, and only while the tab is open
+            expect(await page.evaluate(() => Object.keys(localStorage))).toEqual([]);
+            const kept = await page.evaluate(() => Object.keys(sessionStorage));
+            expect(
+              kept.filter((key) => !/^lernapps:[^:]+:antwort:/.test(key)),
+              "nothing else in the tab",
+            ).toEqual([]);
+            expect(kept.length, "an answer per open task").toBe(types.has("open-task") ? 1 : 0);
+          });
+        }
+      if (!content)
+        for (const item of app.pages["de"] ?? []) {
+          if (item.videos.length === 0) continue;
+          test(`${item.url}: the videos load nothing before a click, the player after it, directly once chosen`, async ({
+            page,
+            baseURL,
+          }) => {
+            await checkVideos(page, item, new URL(baseURL ?? page.url()).origin);
+          });
+        }
+      if (content)
+        for (const item of app.pages["de"] ?? []) {
+          if (item.components.length === 0) continue;
+          test(`${item.url}: each component hydrates without a console error (${item.components.map((component) => component.name).join(", ")})`, async ({
+            page,
+          }) => {
+            await checkComponents(page, item);
+            expect(await page.evaluate(() => [...Object.keys(localStorage), ...Object.keys(sessionStorage)])).toEqual(
+              [],
+            );
+          });
+        }
     });
 
+    // everything below tests the runtime
+    if (content) return;
+
     for (const item of (app.pages["de"] ?? []).filter((candidate) =>
       candidate.exercises.some((exercise) => exercise.kind === "generated"),
     )) {

package/runtime/explainer/exercises.ts

@@ -16,6 +16,7 @@ import { questionFor, taskKey } from "./generated/question.ts";
 import { WORKED_TASKS } from "./tasks.ts";
 import { type Data, type Generated, type LanguageTemplates, type Templates } from "./generated/types.ts";
 import { plain, renderInline, renderMarkdown, renderWithFormulas } from "../shared/text/markdown.ts";
+import { formulaAlternative } from "../shared/text/speech.ts";
 import { distinctSeeds } from "./tasks.ts";
 import { message } from "./messages.ts";
 
@@ -166,6 +167,7 @@ function questionExercise(block: QuestionBlock, lang: string, material: Material
     renderQuestion(question, {
       lang,
       format: renderWithFormulas,
+      describe: (text) => formulaAlternative(text, lang),
       ...(question.material === undefined ? {} : { materialHtml: renderMaterial(question.material, material) }),
     }),
     `<details class="explainer-solution"><summary>${plain(questionMessagesIn(lang).solution)}</summary>`,

package/runtime/explainer/outline.ts

@@ -8,6 +8,7 @@ import { answerText } from "../shared/questions/render.ts";
 import { inLanguage, timelineEvents, type Block, type ComponentExample, type Site, type Text } from "./content.ts";
 import { dataOf, renderExercise, templatesOf, workedTasks } from "./exercises.ts";
 import { kindOf } from "./generated/comparator.ts";
+import { renderWithFormulas } from "../shared/text/markdown.ts";
 import { plainText } from "./generated/texts.ts";
 import { type Data, type Generated, type Templates } from "./generated/types.ts";
 import { loadSite } from "./load.ts";
@@ -48,6 +49,12 @@ export interface ComponentOutline {
   examples?: { accepted?: ComponentExample; rejected?: ComponentExample };
 }
 
+/**
+ * A learner text of a question as the page shows it, as text: its formulas $…$ rendered (a formula has no space the
+ * tests could rely on in a browser's text, see squash in e2e.ts), the rest as written.
+ */
+export const shownText = (text: string): string => plainText(renderWithFormulas(text));
+
 /** An exercise of a page, in the page's language: what it shows and what it accepts. */
 export type ExerciseOutline =
   | {
@@ -244,7 +251,7 @@ function walk(
           question,
           answers:
             question.type === "single-choice" || question.type === "multiple-choice"
-              ? question.options.filter((option) => option.correct).map((option) => option.text)
+              ? question.options.filter((option) => option.correct).map((option) => shownText(option.text))
               : [plainText(answerText(question, lang))],
         });
       }