[red] require instructional visuals in every tutorial

Signed-off-by: Viwat Vchirawongkwin <viwat.v@chula.ac.th>

Author: yyods

tools/web/src/test/learn-content-contract.test.tsx

@@ -144,6 +144,8 @@ const lessonPages: Array<{
   },
 ];
 
+const physicalTabletLessonPages = lessonPages.slice(0, 6);
+
 function mainText(Page: ComponentType): string {
   render(<Page />);
   return screen.getByRole("main").textContent ?? "";
@@ -305,6 +307,55 @@ describe("shared tutorial structure", () => {
   );
 });
 
+describe("instructional visual contract", () => {
+  it.each(lessonPages)(
+    "$href includes a purposeful, accessible visual",
+    ({ Page }) => {
+      render(<Page />);
+      const main = screen.getByRole("main");
+      const figures = [...main.querySelectorAll("figure")];
+
+      expect(figures.length).toBeGreaterThan(0);
+      for (const figure of figures) {
+        expect(figure.querySelector("figcaption")).not.toBeNull();
+        const images = [...figure.querySelectorAll("img")];
+        for (const image of images) {
+          expect(image).toHaveAttribute("alt");
+          expect(image.getAttribute("alt")?.trim().length).toBeGreaterThan(20);
+          expect(Number(image.getAttribute("width"))).toBeGreaterThan(0);
+          expect(Number(image.getAttribute("height"))).toBeGreaterThan(0);
+          expect(image).toHaveAttribute("loading", "lazy");
+        }
+      }
+    },
+  );
+
+  it.each(physicalTabletLessonPages)(
+    "$href includes truthful physical Lenovo app evidence",
+    ({ Page }) => {
+      render(<Page />);
+      const main = screen.getByRole("main");
+      const physicalFigures = [...main.querySelectorAll("figure")].filter(
+        (figure) =>
+          figure
+            .querySelector("figcaption")
+            ?.textContent?.includes("Actual Android tablet · Lenovo TB-J616X"),
+      );
+
+      expect(physicalFigures.length).toBeGreaterThan(0);
+      for (const figure of physicalFigures) {
+        const image = within(figure).getByRole("img");
+        expect(image.getAttribute("src")).toMatch(
+          /^\/learn\/app\/[a-z0-9.-]+\.png$/,
+        );
+        expect(image.getAttribute("alt")).toMatch(/PyBLE 0\.2\.0 beta/i);
+        expect(figure).not.toHaveTextContent(/integration test|debug|golden/i);
+      }
+      expect(main).not.toHaveTextContent(/PyBLE Integration Test/i);
+    },
+  );
+});
+
 describe("tutorial truth and safety content", () => {
   it("teaches exact provisioning boundaries before BLE use", () => {
     const text = mainText(SetupTutorial);
@@ -325,6 +376,8 @@ describe("tutorial truth and safety content", () => {
 
     expect(text).toContain('print("Hello from PyBLE!")');
     expect(text).toMatch(/hardware-free/i);
+    expect(text).toMatch(/In Files.*New file.*hello\.py.*open.*Editor/is);
+    expect(text).not.toMatch(/New file in the Editor.*name.*hello\.py/is);
     expect(text).toMatch(/hello\.py.*Save.*Run.*Console/is);
     expect(text).toMatch(/Stop.*soft reboot.*reconnect/is);
   });
@@ -352,7 +405,8 @@ describe("tutorial truth and safety content", () => {
     expect(text).toMatch(/editable.*repository URL/is);
     expect(text).toMatch(/branch.*only branches/is);
     expect(text).toMatch(/main.*branch discovery/is);
-    expect(text).toMatch(/advanced.*tag or commit.*full.*commit/is);
+    expect(text).toMatch(/Use a tag or commit.*40-character commit/is);
+    expect(text).not.toMatch(/Open Advanced/i);
     expect(text).toMatch(/public.*no.*account.*token/is);
     expect(text).toMatch(/rate limit/is);
     expect(text).toMatch(/lowercase \.py.*direct.*one folder/is);

tools/web/src/test/tutorial-app-capture-assets.test.ts

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: MIT
+// Part of PyBLE (https://pyble.dev) — see /LICENSE.
+
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { tutorialAppCaptures } from "@/lib/tutorial-app-captures";
+
+const expectedCaptureIds = [
+  "setupScanResults",
+  "setupConnectedIdentity",
+  "firstProgramEditorConsole",
+  "filesMultiDeleteReview",
+  "githubBranchChooser",
+  "githubPrewriteReview",
+  "examplesImportComplete",
+  "blocksHelloWorkspace",
+] as const;
+
+const pngSignature = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+const forbiddenMetadataChunks = new Set([
+  "eXIf",
+  "iTXt",
+  "tEXt",
+  "tIME",
+  "zTXt",
+]);
+
+function pngChunkTypes(bytes: Buffer): string[] {
+  const chunkTypes: string[] = [];
+  let offset = pngSignature.length;
+
+  while (offset + 12 <= bytes.length) {
+    const dataLength = bytes.readUInt32BE(offset);
+    const chunkEnd = offset + 12 + dataLength;
+    expect(chunkEnd).toBeLessThanOrEqual(bytes.length);
+
+    const chunkType = bytes.toString("ascii", offset + 4, offset + 8);
+    chunkTypes.push(chunkType);
+    offset = chunkEnd;
+
+    if (chunkType === "IEND") {
+      break;
+    }
+  }
+
+  return chunkTypes;
+}
+
+describe("reviewed physical tutorial capture assets", () => {
+  it("keeps the reviewed capture registry complete and unique", () => {
+    expect(Object.keys(tutorialAppCaptures)).toEqual(expectedCaptureIds);
+    expect(
+      new Set(Object.values(tutorialAppCaptures).map(({ src }) => src)).size,
+    ).toBe(expectedCaptureIds.length);
+  });
+
+  it.each(expectedCaptureIds)(
+    "%s binds content-versioned, stripped PNG bytes to reviewed provenance",
+    async (captureId) => {
+      const capture = tutorialAppCaptures[captureId];
+      const { review } = capture.provenance;
+
+      if (review.status !== "reviewed") {
+        throw new Error(`${captureId} has not completed derivative review`);
+      }
+
+      expect(review.sha256).toMatch(/^[0-9a-f]{64}$/);
+      expect(basename(capture.src)).toContain(review.sha256.slice(0, 12));
+      expect(capture.src).not.toContain("pending");
+      expect(capture.provenance.rawCapture).toMatch(
+        /production-release\.raw\.png$/,
+      );
+      expect(capture.provenance.rawCapture).not.toMatch(
+        /debug|golden|integration/i,
+      );
+      expect(capture.provenance.processing).toMatch(
+        /crop.*status.*navigation.*strip metadata.*not retouch/is,
+      );
+
+      const asset = await readFile(
+        join(process.cwd(), "public", capture.src.slice(1)),
+      );
+      expect(asset.subarray(0, pngSignature.length)).toEqual(pngSignature);
+      expect(asset.readUInt32BE(16)).toBe(capture.width);
+      expect(asset.readUInt32BE(20)).toBe(capture.height);
+      expect({ width: capture.width, height: capture.height }).toEqual({
+        width: 2000,
+        height: 1092,
+      });
+      expect(createHash("sha256").update(asset).digest("hex")).toBe(
+        review.sha256,
+      );
+
+      const chunkTypes = pngChunkTypes(asset);
+      expect(chunkTypes.at(0)).toBe("IHDR");
+      expect(chunkTypes.at(-1)).toBe("IEND");
+      expect(
+        chunkTypes.filter((chunkType) =>
+          forbiddenMetadataChunks.has(chunkType),
+        ),
+      ).toEqual([]);
+    },
+  );
+});