From 90cae4c05db04b8667cd1657f6ee6eb5bcd84d86 Mon Sep 17 00:00:00 2001
From: Bill Stumbo <wstumbo@charter.net>
Date: Sat, 4 Jul 2026 07:30:50 -0400
Subject: [PATCH 1/2] Cleanup and refactoring of test cases

---
 tests/conftest.py                 | 153 ++++++
 tests/test_bibliography_jsonld.py | 765 ++++++++++++------------------
 2 files changed, 469 insertions(+), 449 deletions(-)
 create mode 100644 tests/conftest.py

diff --git a/tests/conftest.py b/tests/conftest.py
new file mode 100644
index 00000000..b90beda7
--- /dev/null
+++ b/tests/conftest.py
@@ -0,0 +1,153 @@
+"""
+tests/conftest.py
+=================
+Shared test infrastructure for the Interlisp bibliography test suite.
+
+Contains:
+  - Path constants consumed by all test modules
+  - FIXTURE_SLUGS: canonical list of every test fixture slug
+  - ``hugo_build``: session-scoped fixture — builds the *test* environment
+    (``tests/public_test/``) used by test_bibliography_jsonld.py
+  - ``production_build``: session-scoped fixture — builds the *production*
+    site (``public/``) used by test_hugo_build.py and test_html_validation.py
+
+Non-fixture utilities (JSON-LD extraction, assertion helpers) live in the
+test module that uses them.  Only things needed by *multiple* test files, or
+the pytest fixture infrastructure itself, belong here.
+"""
+
+import os
+import subprocess
+from pathlib import Path
+
+import pytest
+
+# ---------------------------------------------------------------------------
+# Paths
+# ---------------------------------------------------------------------------
+
+REPO_ROOT: Path = Path(__file__).parent.parent
+PROD_PUBLIC: Path = REPO_ROOT / "public"
+TEST_PUBLIC: Path = REPO_ROOT / "tests" / "public_test"
+BIB_PUBLIC: Path = TEST_PUBLIC / "history" / "bibliography"
+FIXTURES_DIR: Path = REPO_ROOT / "tests" / "fixtures" / "bibliography"
+CONTENT_DIR: Path = REPO_ROOT / "content" / "en" / "history" / "bibliography"
+
+# Hugo lowercases filenames when generating URL slugs.
+FIXTURE_SLUGS: tuple[str, ...] = (
+    "ztest-journal",
+    "ztest-magazine",
+    "ztest-conference",
+    "ztest-book",
+    "ztest-chapter",
+    "ztest-report",
+    "ztest-thesis",
+    "ztest-patent",
+    "ztest-webpage",
+    "ztest-blog",
+    "ztest-video",
+    "ztest-software",
+    "ztest-encyclopedia",
+    "ztest-message",
+    "ztest-no-urls",
+)
+
+
+# ---------------------------------------------------------------------------
+# Shared staleness helper
+# ---------------------------------------------------------------------------
+
+
+def _is_stale(output_dir: Path, *source_dirs: Path) -> bool:
+    """Return True when *output_dir* is absent, empty, or older than any file
+    in *source_dirs*.  Always returns True when ``PYTEST_FORCE_HUGO_BUILD=1``
+    is set.
+    """
+    if os.environ.get("PYTEST_FORCE_HUGO_BUILD"):
+        return True
+
+    html_files = list(output_dir.rglob("index.html"))
+    if not html_files:
+        return True
+
+    oldest_output = min(f.stat().st_mtime for f in html_files)
+
+    for source in source_dirs:
+        for path in source.rglob("*"):
+            if path.is_file() and path.stat().st_mtime > oldest_output:
+                return True
+
+    return False
+
+
+def _run_hugo(*extra_args: str) -> subprocess.CompletedProcess:
+    """Run Hugo with *extra_args* and return the CompletedProcess.  Raises a
+    pytest failure immediately if Hugo exits with a non-zero return code.
+    """
+    result = subprocess.run(
+        ["hugo", *extra_args],
+        cwd=str(REPO_ROOT),
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        pytest.fail(
+            f"Hugo build failed (exit {result.returncode}):\n"
+            f"--- stdout ---\n{result.stdout}\n"
+            f"--- stderr ---\n{result.stderr}"
+        )
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Session-scoped fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(scope="session", autouse=True)
+def hugo_build() -> None:
+    """Build the Hugo *test* site (``tests/public_test/``) when stale.
+
+    Uses ``--environment testing`` so that ``config/testing/hugo.yaml`` mounts
+    the fixture content without touching production content.
+
+    Set ``PYTEST_FORCE_HUGO_BUILD=1`` to force a rebuild unconditionally.
+    """
+    if not _is_stale(
+        BIB_PUBLIC,
+        REPO_ROOT / "layouts",
+        REPO_ROOT / "config" / "testing",
+        FIXTURES_DIR,
+    ):
+        return
+
+    result = _run_hugo("--environment", "testing", "--destination", "tests/public_test")
+    if result.stderr:
+        print(f"\n[hugo test-build warnings]\n{result.stderr}", flush=True)
+
+
+@pytest.fixture(scope="session")
+def production_build() -> subprocess.CompletedProcess:
+    """Build the *production* Hugo site (``public/``) when stale and return
+    the ``CompletedProcess`` so callers can inspect stdout/stderr.
+
+    Tests that need the production build should declare this fixture as a
+    parameter.  It is *not* autouse — only tests that explicitly request it
+    will trigger a production build.
+    """
+    if not _is_stale(
+        PROD_PUBLIC,
+        REPO_ROOT / "layouts",
+        REPO_ROOT / "content",
+        REPO_ROOT / "data",
+        REPO_ROOT / "config" / "_default",
+    ):
+        # Site is up-to-date; run a no-op build to capture stderr for tests.
+        return subprocess.run(
+            ["hugo", "--logLevel", "warn"],
+            cwd=str(REPO_ROOT),
+            capture_output=True,
+            text=True,
+        )
+
+    return _run_hugo("--cleanDestinationDir", "--logLevel", "warn")
diff --git a/tests/test_bibliography_jsonld.py b/tests/test_bibliography_jsonld.py
index ecd11e92..f8603849 100644
--- a/tests/test_bibliography_jsonld.py
+++ b/tests/test_bibliography_jsonld.py
@@ -5,140 +5,67 @@
 ``layouts/_partials/bibliography-json-ld.html`` for every Schema.org type
 used in the Interlisp bibliography.
 
-How it works
-------------
-Each ``ZTEST-*.md`` fixture in ``tests/fixtures/bibliography/`` is the
-**mock input**: it provides fully-controlled front-matter values that Hugo
-feeds into the template.  A test-environment Hugo build mounts those fixtures
-into the content tree without touching production content.  The tests then
-read the rendered ``tests/public_test/history/bibliography/<slug>/index.html``,
-extract the ``<script type="application/ld+json">`` block, and assert that the
-resulting JSON-LD object has the correct Schema.org ``@type`` and every
-type-specific field.
-
-Fixture files (mock inputs)
----------------------------
-    tests/fixtures/bibliography/ZTEST-JOURNAL.md     -> article-journal
-    tests/fixtures/bibliography/ZTEST-MAGAZINE.md    -> article-magazine
-    tests/fixtures/bibliography/ZTEST-CONFERENCE.md  -> paper-conference
-    tests/fixtures/bibliography/ZTEST-BOOK.md        -> book
-    tests/fixtures/bibliography/ZTEST-CHAPTER.md     -> chapter
-    tests/fixtures/bibliography/ZTEST-REPORT.md      -> report
-    tests/fixtures/bibliography/ZTEST-THESIS.md      -> thesis
-    tests/fixtures/bibliography/ZTEST-PATENT.md      -> patent
-    tests/fixtures/bibliography/ZTEST-WEBPAGE.md     -> webpage
-    tests/fixtures/bibliography/ZTEST-BLOG.md        -> post-weblog
-    tests/fixtures/bibliography/ZTEST-VIDEO.md       -> motion_picture
-    tests/fixtures/bibliography/ZTEST-SOFTWARE.md    -> software
-    tests/fixtures/bibliography/ZTEST-ENCYCLOPEDIA.md -> entry-encyclopedia
-    tests/fixtures/bibliography/ZTEST-MESSAGE.md     -> personal_communication
-    tests/fixtures/bibliography/ZTEST-NO-URLS.md     -> (sameAs absent edge case)
-
-Hugo build
-----------
-The session-scoped ``_hugo_build`` fixture runs:
-
-    hugo --environment testing --destination tests/public_test
-
-The ``config/testing/hugo.yaml`` environment mounts ``tests/fixtures/bibliography/``
-into the content tree via Hugo module mounts.  Test output lands in
-``tests/public_test/``, which is gitignored and never deployed.
-
-A rebuild is triggered automatically when any template or fixture file is
-newer than the most recent test output file.  Set the environment variable
-``PYTEST_FORCE_HUGO_BUILD=1`` to force a rebuild regardless.
-
-Prerequisites
--------------
-    pip install pytest    # only stdlib + pytest are required
+Design
+------
+Each ``ZTEST-*.md`` file in ``tests/fixtures/bibliography/`` is the **mock
+input**: controlled Hugo front matter that the template converts to JSON-LD.
+The session-scoped ``hugo_build`` fixture (defined in ``conftest.py``) builds
+those fixtures into ``tests/public_test/`` via the ``--environment testing``
+Hugo configuration, which never touches production content.
+
+Each per-type test class declares an ``ld`` fixture that loads the parsed
+JSON-LD dict for that class's fixture slug.  Because ``_load_jsonld`` is
+wrapped with ``functools.lru_cache``, each HTML file is read exactly once per
+session regardless of how many tests reference it.
+
+Cross-cutting invariants (context, language, date format, key isolation) are
+expressed as module-level parametrized functions so that pytest generates one
+test ID per slug or (slug, key) combination, making failures immediately
+identifiable.
+
+Fixture → Schema.org type map
+------------------------------
+    ZTEST-JOURNAL.md      article-journal       → ScholarlyArticle
+    ZTEST-MAGAZINE.md     article-magazine      → Article
+    ZTEST-CONFERENCE.md   paper-conference      → ScholarlyArticle
+    ZTEST-BOOK.md         book                  → Book
+    ZTEST-CHAPTER.md      chapter               → Chapter
+    ZTEST-REPORT.md       report                → Report
+    ZTEST-THESIS.md       thesis                → Thesis
+    ZTEST-PATENT.md       patent                → CreativeWork (+additionalType)
+    ZTEST-WEBPAGE.md      webpage               → WebPage
+    ZTEST-BLOG.md         post-weblog           → BlogPosting
+    ZTEST-VIDEO.md        motion_picture        → VideoObject
+    ZTEST-SOFTWARE.md     software              → SoftwareSourceCode
+    ZTEST-ENCYCLOPEDIA.md entry-encyclopedia    → Article
+    ZTEST-MESSAGE.md      personal_communication → Message
+    ZTEST-NO-URLS.md      report (no URLs)      → edge-case fixture
 
 Usage
 -----
     # From the repository root:
     pytest tests/test_bibliography_jsonld.py -v
 
-    # Force a fresh Hugo test build before running:
+    # Force a fresh Hugo test build first:
     PYTEST_FORCE_HUGO_BUILD=1 pytest tests/test_bibliography_jsonld.py -v
 """
 
 import functools
 import json
-import os
-import subprocess
 from html.parser import HTMLParser
 from pathlib import Path
 
 import pytest
 
-# ---------------------------------------------------------------------------
-# Paths
-# ---------------------------------------------------------------------------
-
-REPO_ROOT = Path(__file__).parent.parent
-TEST_PUBLIC = REPO_ROOT / "tests" / "public_test"
-BIB_PUBLIC = TEST_PUBLIC / "history" / "bibliography"
-FIXTURES_DIR = REPO_ROOT / "tests" / "fixtures" / "bibliography"
-
-# Hugo lowercases the filename slug when generating URLs.
-FIXTURE_SLUGS = [
-    "ztest-journal",
-    "ztest-magazine",
-    "ztest-conference",
-    "ztest-book",
-    "ztest-chapter",
-    "ztest-report",
-    "ztest-thesis",
-    "ztest-patent",
-    "ztest-webpage",
-    "ztest-blog",
-    "ztest-video",
-    "ztest-software",
-    "ztest-encyclopedia",
-    "ztest-message",
-    "ztest-no-urls",
-]
-
-
-# ---------------------------------------------------------------------------
-# Staleness check
-# ---------------------------------------------------------------------------
-
-def _needs_rebuild() -> bool:
-    """Return True when the test output is absent or older than any source file.
-
-    Source files watched: all Hugo templates, the test fixtures, and the
-    testing environment config.  Controlled by the ``PYTEST_FORCE_HUGO_BUILD``
-    environment variable (any non-empty value forces a rebuild).
-    """
-    if os.environ.get("PYTEST_FORCE_HUGO_BUILD"):
-        return True
-
-    html_files = list(BIB_PUBLIC.rglob("index.html"))
-    if not html_files:
-        return True
-
-    oldest_output = min(f.stat().st_mtime for f in html_files)
-
-    watched = [
-        REPO_ROOT / "layouts",
-        REPO_ROOT / "config" / "testing",
-        FIXTURES_DIR,
-    ]
-    for source in watched:
-        for path in source.rglob("*"):
-            if path.is_file() and path.stat().st_mtime > oldest_output:
-                return True
-
-    return False
-
+from conftest import BIB_PUBLIC, FIXTURE_SLUGS, TEST_PUBLIC
 
 # ---------------------------------------------------------------------------
-# HTML helper – extract <script type="application/ld+json"> blocks
+# HTML extraction
 # ---------------------------------------------------------------------------
 
 
 class _JSONLDExtractor(HTMLParser):
-    """Pull raw text out of every ``application/ld+json`` script element."""
+    """Collect the raw text of every ``application/ld+json`` script element."""
 
     def __init__(self) -> None:
         super().__init__()
@@ -161,24 +88,15 @@ def handle_data(self, data: str) -> None:
             self._buf.append(data)
 
 
-@functools.lru_cache(maxsize=None)
-def _load_jsonld(slug: str) -> dict:
-    """Return the Schema.org JSON-LD dict from the built bibliography page *slug*.
+def _parse_jsonld(path: Path, *, type_filter: str | None = None) -> dict:
+    """Return the first Schema.org JSON-LD block from *path*.
 
-    Results are cached so each fixture HTML file is read and parsed exactly
-    once per test session regardless of how many test methods reference it.
+    If *type_filter* is given, return the block whose ``@type`` matches it
+    (used for the CollectionPage section index).  Otherwise return the first
+    block whose ``@context`` is ``https://schema.org``.
 
-    Skips (not fails) when the built page is absent; the session fixture
-    ``_hugo_build`` normally ensures the build runs before any test.
+    Raises a pytest failure (not an exception) if no matching block is found.
     """
-    path = BIB_PUBLIC / slug / "index.html"
-    if not path.exists():
-        pytest.skip(
-            f"Built page not found: {path}\n"
-            "Run 'hugo --environment testing --destination tests/public_test' "
-            "from the repo root, then re-run the tests."
-        )
-
     parser = _JSONLDExtractor()
     parser.feed(path.read_text(encoding="utf-8"))
 
@@ -187,49 +105,50 @@ def _load_jsonld(slug: str) -> dict:
             data = json.loads(raw.strip())
         except json.JSONDecodeError:
             continue
-        if isinstance(data, dict) and data.get("@context") == "https://schema.org":
+        if not isinstance(data, dict):
+            continue
+        if type_filter:
+            if data.get("@type") == type_filter:
+                return data
+        elif data.get("@context") == "https://schema.org":
             return data
 
-    pytest.fail(f"No schema.org JSON-LD block found in {path}")
+    pytest.fail(f"No matching JSON-LD block found in {path}")
 
 
 # ---------------------------------------------------------------------------
-# Session-scoped Hugo build
+# Cached page loaders
 # ---------------------------------------------------------------------------
 
 
-@pytest.fixture(scope="session", autouse=True)
-def _hugo_build() -> None:
-    """Build the Hugo test site once per pytest session when sources have changed.
+@functools.lru_cache(maxsize=None)
+def _load_jsonld(slug: str) -> dict:
+    """Return the Schema.org JSON-LD dict for the bibliography page *slug*.
 
-    Uses ``--environment testing`` which reads ``config/testing/hugo.yaml``,
-    mounting ``tests/fixtures/bibliography/`` into the content tree and
-    writing output to ``tests/public_test/``.
+    Results are cached (lru_cache) so each HTML file is read exactly once per
+    test session regardless of how many test methods reference the same slug.
 
-    Set ``PYTEST_FORCE_HUGO_BUILD=1`` to bypass the staleness check.
+    Skips (does not fail) when the built page is absent so that collection
+    errors clearly identify the missing file rather than producing confusing
+    assertion failures.
     """
-    if not _needs_rebuild():
-        return
-
-    result = subprocess.run(
-        [
-            "hugo",
-            "--environment", "testing",
-            "--destination", "tests/public_test",
-        ],
-        cwd=str(REPO_ROOT),
-        capture_output=True,
-        text=True,
-    )
-    if result.returncode != 0:
-        pytest.fail(
-            f"Hugo test build failed (exit {result.returncode}):\n"
-            f"--- stdout ---\n{result.stdout}\n"
-            f"--- stderr ---\n{result.stderr}"
+    path = BIB_PUBLIC / slug / "index.html"
+    if not path.exists():
+        pytest.skip(
+            f"Built page not found: {path}\n"
+            "Run 'hugo --environment testing --destination tests/public_test' "
+            "from the repo root, then re-run the tests."
         )
-    if result.stderr:
-        # Surface warnings without failing so they're visible in CI logs.
-        print(f"\n[hugo warnings]\n{result.stderr}", flush=True)
+    return _parse_jsonld(path)
+
+
+@functools.lru_cache(maxsize=1)
+def _load_jsonld_section() -> dict:
+    """Return the CollectionPage JSON-LD dict from the bibliography index page."""
+    path = TEST_PUBLIC / "history" / "bibliography" / "index.html"
+    if not path.exists():
+        pytest.skip(f"Section index page not found: {path}")
+    return _parse_jsonld(path, type_filter="CollectionPage")
 
 
 # ---------------------------------------------------------------------------
@@ -238,7 +157,7 @@ def _hugo_build() -> None:
 
 
 def _assert_base(ld: dict, expected_type: str, expected_name: str) -> None:
-    """Assert the fields present on every single-page bibliography entry."""
+    """Assert the fields that must appear on every single bibliography page."""
     assert ld.get("@context") == "https://schema.org", (
         f"@context must be 'https://schema.org', got {ld.get('@context')!r}"
     )
@@ -264,10 +183,10 @@ def _assert_person(
 ) -> None:
     """Assert a Schema.org Person object."""
     assert person.get("@type") == "Person", (
-        f"Person @type must be 'Person', got {person.get('@type')!r}"
+        f"@type must be 'Person', got {person.get('@type')!r}"
     )
     assert person.get("name") == expected_name, (
-        f"Person name must be {expected_name!r}, got {person.get('name')!r}"
+        f"name must be {expected_name!r}, got {person.get('name')!r}"
     )
     if family is not None:
         assert person.get("familyName") == family, (
@@ -282,79 +201,83 @@ def _assert_person(
 def _assert_org(obj: dict, expected_name: str) -> None:
     """Assert a Schema.org Organization object."""
     assert obj.get("@type") == "Organization", (
-        f"Expected Organization, got @type={obj.get('@type')!r}"
+        f"@type must be 'Organization', got {obj.get('@type')!r}"
     )
     assert obj.get("name") == expected_name, (
-        f"Organization name must be {expected_name!r}, got {obj.get('name')!r}"
+        f"name must be {expected_name!r}, got {obj.get('name')!r}"
     )
 
 
 # ===========================================================================
 # Per-type test classes
+#
+# Each class declares an ``ld`` fixture (autouse=True) that loads the JSON-LD
+# for that class's fixture page into ``self.ld``.  All test methods access the
+# data via ``self.ld`` rather than calling ``_load_jsonld`` independently,
+# making the data dependency explicit.  ``_load_jsonld`` is cached so the
+# fixture is effectively free after the first call.
 # ===========================================================================
 
 
 class TestScholarlyArticle:
-    """article-journal → ScholarlyArticle
+    """article-journal → ScholarlyArticle.  Fixture: ZTEST-JOURNAL.md
 
-    Mock fixture: ZTEST-JOURNAL.md
-    Authors: Smith, Alice J. | Jones, Bob
-    Journal: Journal of Test Science  vol 5, issue 2, pp 45-67
-    Concepts: Interlisp, ProgrammingLanguages  (tests about[] + keywords)
+    Also exercises author name splitting, sameAs ordering, periodical
+    isPartOf, pagination fields, and concepts → about[]/keywords.
     """
 
-    def test_schema_type(self):
-        assert _load_jsonld("ztest-journal")["@type"] == "ScholarlyArticle"
+    @pytest.fixture(autouse=True)
+    def ld(self):
+        self.ld = _load_jsonld("ztest-journal")
 
     def test_base_fields(self):
-        _assert_base(_load_jsonld("ztest-journal"), "ScholarlyArticle", "Test Scholarly Article")
+        _assert_base(self.ld, "ScholarlyArticle", "Test Scholarly Article")
 
     def test_date_published(self):
-        assert _load_jsonld("ztest-journal")["datePublished"] == "2020-03-15"
+        assert self.ld["datePublished"] == "2020-03-15"
 
     def test_date_modified(self):
-        assert _load_jsonld("ztest-journal")["dateModified"] == "2023-01-10T00:00:00Z"
+        assert self.ld["dateModified"] == "2023-01-10T00:00:00Z"
 
     def test_description_from_abstract(self):
-        desc = _load_jsonld("ztest-journal").get("description", "")
-        assert "journal article" in desc.lower()
+        assert "journal article" in self.ld.get("description", "").lower()
 
     def test_authors_count_and_order(self):
-        authors = _load_jsonld("ztest-journal")["author"]
+        authors = self.ld["author"]
         assert len(authors) == 2, f"Expected 2 authors, got {len(authors)}"
-        # "Smith, Alice J." → givenName=Alice J., familyName=Smith
+        # "Smith, Alice J." → familyName=Smith, givenName=Alice J.
         _assert_person(authors[0], "Alice J. Smith", family="Smith", given="Alice J.")
-        # "Jones, Bob" → givenName=Bob, familyName=Jones
+        # "Jones, Bob" → familyName=Jones, givenName=Bob
         _assert_person(authors[1], "Bob Jones", family="Jones", given="Bob")
 
     def test_same_as_contains_both_urls(self):
-        same_as = _load_jsonld("ztest-journal")["sameAs"]
+        same_as = self.ld["sameAs"]
         assert "https://example.com/journal-article" in same_as
         assert "https://www.zotero.org/groups/test/items/ZTESTJNL" in same_as
 
     def test_same_as_url_source_precedes_zotero(self):
         """url_source must appear before zotero_url in the sameAs array."""
-        same_as = _load_jsonld("ztest-journal")["sameAs"]
-        src_idx = same_as.index("https://example.com/journal-article")
-        zoo_idx = same_as.index("https://www.zotero.org/groups/test/items/ZTESTJNL")
-        assert src_idx < zoo_idx, "url_source should appear before zotero_url in sameAs"
+        same_as = self.ld["sameAs"]
+        assert same_as.index("https://example.com/journal-article") < same_as.index(
+            "https://www.zotero.org/groups/test/items/ZTESTJNL"
+        )
 
     def test_periodical_is_part_of(self):
-        is_part_of = _load_jsonld("ztest-journal")["isPartOf"]
+        is_part_of = self.ld["isPartOf"]
         assert is_part_of["@type"] == "Periodical"
         assert is_part_of["name"] == "Journal of Test Science"
 
     def test_volume_number(self):
-        assert _load_jsonld("ztest-journal")["volumeNumber"] == "5"
+        assert self.ld["volumeNumber"] == "5"
 
     def test_issue_number(self):
-        assert _load_jsonld("ztest-journal")["issueNumber"] == "2"
+        assert self.ld["issueNumber"] == "2"
 
     def test_pagination(self):
-        assert _load_jsonld("ztest-journal")["pagination"] == "45-67"
+        assert self.ld["pagination"] == "45-67"
 
     def test_about_defined_terms(self):
-        about = _load_jsonld("ztest-journal")["about"]
+        about = self.ld["about"]
         ids = [term["@id"] for term in about]
         assert "https://interlisp.org/concepts/#Interlisp" in ids
         assert "https://interlisp.org/concepts/#ProgrammingLanguages" in ids
@@ -364,500 +287,444 @@ def test_about_defined_terms(self):
             assert "name" in term
 
     def test_keywords_from_concepts(self):
-        keywords = _load_jsonld("ztest-journal")["keywords"]
-        assert "Interlisp" in keywords
-        assert "Programming Languages" in keywords
+        assert "Interlisp" in self.ld["keywords"]
+        assert "Programming Languages" in self.ld["keywords"]
 
 
 class TestMagazineArticle:
-    """article-magazine → Article
+    """article-magazine → Article.  Fixture: ZTEST-MAGAZINE.md
 
-    Mock fixture: ZTEST-MAGAZINE.md
-    Maps to Schema.org Article (not ScholarlyArticle).
-    Shares the same journal-style field block as article-journal.
+    Shares the periodical field block with article-journal but maps to
+    Schema.org Article rather than ScholarlyArticle.
     """
 
-    def test_schema_type(self):
-        assert _load_jsonld("ztest-magazine")["@type"] == "Article"
+    @pytest.fixture(autouse=True)
+    def ld(self):
+        self.ld = _load_jsonld("ztest-magazine")
 
     def test_base_fields(self):
-        _assert_base(_load_jsonld("ztest-magazine"), "Article", "Test Magazine Article")
+        _assert_base(self.ld, "Article", "Test Magazine Article")
 
     def test_author(self):
-        authors = _load_jsonld("ztest-magazine")["author"]
+        authors = self.ld["author"]
         assert len(authors) == 1
         _assert_person(authors[0], "Jane Doe", family="Doe", given="Jane")
 
     def test_periodical_is_part_of(self):
-        is_part_of = _load_jsonld("ztest-magazine")["isPartOf"]
+        is_part_of = self.ld["isPartOf"]
         assert is_part_of["@type"] == "Periodical"
         assert is_part_of["name"] == "Computing Monthly"
 
     def test_volume_issue_pagination(self):
-        ld = _load_jsonld("ztest-magazine")
-        assert ld["volumeNumber"] == "10"
-        assert ld["issueNumber"] == "6"
-        assert ld["pagination"] == "12-14"
+        assert self.ld["volumeNumber"] == "10"
+        assert self.ld["issueNumber"] == "6"
+        assert self.ld["pagination"] == "12-14"
 
 
 class TestConferencePaper:
-    """paper-conference → ScholarlyArticle
+    """paper-conference → ScholarlyArticle.  Fixture: ZTEST-CONFERENCE.md
 
-    Mock fixture: ZTEST-CONFERENCE.md
-    Uses proceedings_title (isPartOf Book), publisher, and place
-    (locationCreated Place).
+    Exercises proceedings isPartOf (Book), publisher, and locationCreated
+    (place field → Schema.org Place).
     """
 
-    def test_schema_type(self):
-        assert _load_jsonld("ztest-conference")["@type"] == "ScholarlyArticle"
+    @pytest.fixture(autouse=True)
+    def ld(self):
+        self.ld = _load_jsonld("ztest-conference")
 
     def test_base_fields(self):
-        _assert_base(_load_jsonld("ztest-conference"), "ScholarlyArticle", "Test Conference Paper")
+        _assert_base(self.ld, "ScholarlyArticle", "Test Conference Paper")
 
     def test_proceedings_is_part_of(self):
-        is_part_of = _load_jsonld("ztest-conference")["isPartOf"]
+        is_part_of = self.ld["isPartOf"]
         assert is_part_of["@type"] == "Book"
         assert is_part_of["name"] == "Proceedings of the Test Conference 2019"
 
     def test_publisher(self):
-        _assert_org(_load_jsonld("ztest-conference")["publisher"], "ACM")
+        _assert_org(self.ld["publisher"], "ACM")
 
     def test_location_created(self):
-        """place front-matter field maps to locationCreated Place."""
-        location = _load_jsonld("ztest-conference")["locationCreated"]
+        """place front-matter maps to a Schema.org Place via locationCreated."""
+        location = self.ld["locationCreated"]
         assert location["@type"] == "Place"
         assert location["name"] == "San Francisco, CA"
 
     def test_authors_with_compound_given_name(self):
         """'Brown, Carol K.' splits to givenName='Carol K.', familyName='Brown'."""
-        authors = _load_jsonld("ztest-conference")["author"]
+        authors = self.ld["author"]
         assert len(authors) == 2
         _assert_person(authors[0], "Carol K. Brown", family="Brown", given="Carol K.")
         _assert_person(authors[1], "David White", family="White", given="David")
 
 
 class TestBook:
-    """book → Book
-
-    Mock fixture: ZTEST-BOOK.md
-    """
+    """book → Book.  Fixture: ZTEST-BOOK.md"""
 
-    def test_schema_type(self):
-        assert _load_jsonld("ztest-book")["@type"] == "Book"
+    @pytest.fixture(autouse=True)
+    def ld(self):
+        self.ld = _load_jsonld("ztest-book")
 
     def test_base_fields(self):
-        _assert_base(_load_jsonld("ztest-book"), "Book", "Test Book Title")
+        _assert_base(self.ld, "Book", "Test Book Title")
 
     def test_publisher(self):
-        _assert_org(_load_jsonld("ztest-book")["publisher"], "Test Publisher")
+        _assert_org(self.ld["publisher"], "Test Publisher")
 
     def test_author(self):
-        authors = _load_jsonld("ztest-book")["author"]
+        authors = self.ld["author"]
         assert len(authors) == 1
         _assert_person(authors[0], "Test Author", family="Author", given="Test")
 
     def test_same_as_order(self):
-        """url_source must be the first element; zotero_url must be the second."""
-        same_as = _load_jsonld("ztest-book")["sameAs"]
+        """url_source must be the first element; zotero_url the second."""
+        same_as = self.ld["sameAs"]
         assert same_as[0] == "https://example.com/book"
         assert same_as[1] == "https://www.zotero.org/groups/test/items/ZTESTBOOK"
 
 
 class TestChapter:
-    """chapter → Chapter
+    """chapter → Chapter.  Fixture: ZTEST-CHAPTER.md
 
-    Mock fixture: ZTEST-CHAPTER.md
     isPartOf is a Book that also carries a nested publisher Organization.
     """
 
-    def test_schema_type(self):
-        assert _load_jsonld("ztest-chapter")["@type"] == "Chapter"
+    @pytest.fixture(autouse=True)
+    def ld(self):
+        self.ld = _load_jsonld("ztest-chapter")
+
+    def test_base_fields(self):
+        _assert_base(self.ld, "Chapter", "Test Chapter Title")
 
     def test_is_part_of_book(self):
-        parent = _load_jsonld("ztest-chapter")["isPartOf"]
+        parent = self.ld["isPartOf"]
         assert parent["@type"] == "Book"
         assert parent["name"] == "Test Book of Chapters"
 
     def test_parent_book_publisher(self):
-        """Publisher is nested inside the isPartOf Book object."""
-        parent = _load_jsonld("ztest-chapter")["isPartOf"]
-        _assert_org(parent["publisher"], "Chapter Publisher")
+        """publisher is nested inside the isPartOf Book, not at the top level."""
+        _assert_org(self.ld["isPartOf"]["publisher"], "Chapter Publisher")
 
     def test_pagination(self):
-        assert _load_jsonld("ztest-chapter")["pagination"] == "100-120"
+        assert self.ld["pagination"] == "100-120"
 
     def test_editor(self):
-        editors = _load_jsonld("ztest-chapter")["editor"]
+        editors = self.ld["editor"]
         assert len(editors) == 1
         _assert_person(editors[0], "Test Editor", family="Editor", given="Test")
 
     def test_author(self):
-        authors = _load_jsonld("ztest-chapter")["author"]
+        authors = self.ld["author"]
         assert len(authors) == 1
         _assert_person(authors[0], "Test Writer", family="Writer", given="Test")
 
 
 class TestReport:
-    """report → Report
-
-    Mock fixture: ZTEST-REPORT.md
-    """
+    """report → Report.  Fixture: ZTEST-REPORT.md"""
 
-    def test_schema_type(self):
-        assert _load_jsonld("ztest-report")["@type"] == "Report"
+    @pytest.fixture(autouse=True)
+    def ld(self):
+        self.ld = _load_jsonld("ztest-report")
 
     def test_base_fields(self):
-        _assert_base(_load_jsonld("ztest-report"), "Report", "Test Technical Report")
+        _assert_base(self.ld, "Report", "Test Technical Report")
 
     def test_publisher(self):
-        _assert_org(_load_jsonld("ztest-report")["publisher"], "Test Research Lab")
+        _assert_org(self.ld["publisher"], "Test Research Lab")
 
     def test_author(self):
-        authors = _load_jsonld("ztest-report")["author"]
+        authors = self.ld["author"]
         assert len(authors) == 1
         _assert_person(authors[0], "Test Researcher", family="Researcher", given="Test")
 
 
 class TestThesis:
-    """thesis → Thesis
+    """thesis → Thesis.  Fixture: ZTEST-THESIS.md"""
 
-    Mock fixture: ZTEST-THESIS.md
-    """
-
-    def test_schema_type(self):
-        assert _load_jsonld("ztest-thesis")["@type"] == "Thesis"
+    @pytest.fixture(autouse=True)
+    def ld(self):
+        self.ld = _load_jsonld("ztest-thesis")
 
     def test_base_fields(self):
-        _assert_base(_load_jsonld("ztest-thesis"), "Thesis", "Test Doctoral Thesis")
+        _assert_base(self.ld, "Thesis", "Test Doctoral Thesis")
 
     def test_source_organization(self):
-        org = _load_jsonld("ztest-thesis")["sourceOrganization"]
+        org = self.ld["sourceOrganization"]
         assert org["@type"] == "CollegeOrUniversity"
         assert org["name"] == "Test University"
 
     def test_author(self):
-        authors = _load_jsonld("ztest-thesis")["author"]
+        authors = self.ld["author"]
         assert len(authors) == 1
         _assert_person(authors[0], "Test Student", family="Student", given="Test")
 
     def test_no_publisher_key(self):
-        """Theses use sourceOrganization, not publisher."""
-        assert "publisher" not in _load_jsonld("ztest-thesis"), (
-            "Thesis should use sourceOrganization, not publisher"
-        )
+        """Theses must use sourceOrganization, not publisher."""
+        assert "publisher" not in self.ld
 
 
 class TestPatent:
-    """patent → CreativeWork + additionalType "Patent"
+    """patent → CreativeWork + additionalType "Patent".  Fixture: ZTEST-PATENT.md
 
-    Mock fixture: ZTEST-PATENT.md
-    Verifies both PropertyValue identifier objects, copyrightHolder (assignee),
+    Verifies identifier PropertyValue objects, copyrightHolder (assignee),
     and validIn DefinedRegion (issuing authority).
     """
 
-    def test_schema_type_is_creative_work(self):
-        assert _load_jsonld("ztest-patent")["@type"] == "CreativeWork"
+    @pytest.fixture(autouse=True)
+    def ld(self):
+        self.ld = _load_jsonld("ztest-patent")
+
+    def test_base_fields(self):
+        """Patent @type is CreativeWork; Patent identity comes from additionalType."""
+        _assert_base(self.ld, "CreativeWork", "Test Patent for Widget")
 
     def test_additional_type_is_patent(self):
-        assert _load_jsonld("ztest-patent")["additionalType"] == "Patent"
+        assert self.ld["additionalType"] == "Patent"
 
     def test_patent_number_identifier(self):
-        identifiers = _load_jsonld("ztest-patent")["identifier"]
         match = next(
-            (i for i in identifiers if i.get("propertyID") == "patent-number"), None
+            (i for i in self.ld["identifier"] if i.get("propertyID") == "patent-number"),
+            None,
         )
         assert match is not None, "No 'patent-number' identifier found"
         assert match["@type"] == "PropertyValue"
         assert match["value"] == "US9876543B2"
 
     def test_application_number_identifier(self):
-        identifiers = _load_jsonld("ztest-patent")["identifier"]
         match = next(
-            (i for i in identifiers if i.get("propertyID") == "application-number"), None
+            (i for i in self.ld["identifier"] if i.get("propertyID") == "application-number"),
+            None,
         )
         assert match is not None, "No 'application-number' identifier found"
         assert match["@type"] == "PropertyValue"
         assert match["value"] == "US12345678"
 
     def test_assignee_maps_to_copyright_holder(self):
-        """Patent assignee (rights owner) maps to copyrightHolder, not funder."""
-        holder = _load_jsonld("ztest-patent")["copyrightHolder"]
-        _assert_org(holder, "Test Corporation")
+        """Assignee (rights owner) maps to copyrightHolder, not funder."""
+        _assert_org(self.ld["copyrightHolder"], "Test Corporation")
 
     def test_issuing_authority_maps_to_valid_in(self):
         """Issuing authority (jurisdiction) maps to validIn DefinedRegion."""
-        region = _load_jsonld("ztest-patent")["validIn"]
+        region = self.ld["validIn"]
         assert region["@type"] == "DefinedRegion"
         assert region["name"] == "United States"
 
     def test_author(self):
-        authors = _load_jsonld("ztest-patent")["author"]
+        authors = self.ld["author"]
         assert len(authors) == 1
         _assert_person(authors[0], "Test Inventor", family="Inventor", given="Test")
 
 
 class TestWebPage:
-    """webpage → WebPage
+    """webpage → WebPage.  Fixture: ZTEST-WEBPAGE.md"""
 
-    Mock fixture: ZTEST-WEBPAGE.md
-    """
-
-    def test_schema_type(self):
-        assert _load_jsonld("ztest-webpage")["@type"] == "WebPage"
+    @pytest.fixture(autouse=True)
+    def ld(self):
+        self.ld = _load_jsonld("ztest-webpage")
 
     def test_base_fields(self):
-        _assert_base(_load_jsonld("ztest-webpage"), "WebPage", "Test Web Page")
+        _assert_base(self.ld, "WebPage", "Test Web Page")
 
     def test_is_part_of_website(self):
-        parent = _load_jsonld("ztest-webpage")["isPartOf"]
+        parent = self.ld["isPartOf"]
         assert parent["@type"] == "WebSite"
         assert parent["name"] == "Test Website"
 
 
 class TestBlogPosting:
-    """post-weblog → BlogPosting
+    """post-weblog → BlogPosting.  Fixture: ZTEST-BLOG.md"""
 
-    Mock fixture: ZTEST-BLOG.md
-    """
-
-    def test_schema_type(self):
-        assert _load_jsonld("ztest-blog")["@type"] == "BlogPosting"
+    @pytest.fixture(autouse=True)
+    def ld(self):
+        self.ld = _load_jsonld("ztest-blog")
 
     def test_base_fields(self):
-        _assert_base(_load_jsonld("ztest-blog"), "BlogPosting", "Test Blog Post")
+        _assert_base(self.ld, "BlogPosting", "Test Blog Post")
 
     def test_is_part_of_blog(self):
-        parent = _load_jsonld("ztest-blog")["isPartOf"]
+        parent = self.ld["isPartOf"]
         assert parent["@type"] == "Blog"
         assert parent["name"] == "Test Tech Blog"
 
 
 class TestVideoObject:
-    """motion_picture → VideoObject
-
-    Mock fixture: ZTEST-VIDEO.md
-    """
+    """motion_picture → VideoObject.  Fixture: ZTEST-VIDEO.md"""
 
-    def test_schema_type(self):
-        assert _load_jsonld("ztest-video")["@type"] == "VideoObject"
+    @pytest.fixture(autouse=True)
+    def ld(self):
+        self.ld = _load_jsonld("ztest-video")
 
     def test_base_fields(self):
-        _assert_base(_load_jsonld("ztest-video"), "VideoObject", "Test Motion Picture")
+        _assert_base(self.ld, "VideoObject", "Test Motion Picture")
 
     def test_production_company(self):
-        _assert_org(_load_jsonld("ztest-video")["productionCompany"], "Test Film Studio")
+        _assert_org(self.ld["productionCompany"], "Test Film Studio")
 
     def test_encoding_format(self):
-        assert _load_jsonld("ztest-video")["encodingFormat"] == "MP4"
+        assert self.ld["encodingFormat"] == "MP4"
 
     def test_part_of_series(self):
-        series = _load_jsonld("ztest-video")["partOfSeries"]
+        series = self.ld["partOfSeries"]
         assert series["@type"] == "CreativeWorkSeries"
         assert series["name"] == "Test Film Series"
 
 
 class TestSoftwareSourceCode:
-    """software → SoftwareSourceCode
+    """software → SoftwareSourceCode.  Fixture: ZTEST-SOFTWARE.md
 
-    Mock fixture: ZTEST-SOFTWARE.md
-    Also validates the single-name (no comma) author edge case via the
-    "Singularity" author entry, which has no family/given split.
+    Also exercises the single-name (no comma) author edge case via the
+    "Singularity" entry, which must produce only a ``name`` key.
     """
 
-    def test_schema_type(self):
-        assert _load_jsonld("ztest-software")["@type"] == "SoftwareSourceCode"
+    @pytest.fixture(autouse=True)
+    def ld(self):
+        self.ld = _load_jsonld("ztest-software")
 
     def test_base_fields(self):
-        _assert_base(_load_jsonld("ztest-software"), "SoftwareSourceCode", "Test Software")
+        _assert_base(self.ld, "SoftwareSourceCode", "Test Software")
 
-    def test_two_author_objects_present(self):
-        assert len(_load_jsonld("ztest-software")["author"]) == 2
+    def test_author_count(self):
+        assert len(self.ld["author"]) == 2
 
     def test_author_with_comma_split(self):
-        """'Developer, Test' → givenName='Test', familyName='Developer'."""
-        authors = _load_jsonld("ztest-software")["author"]
-        _assert_person(authors[0], "Test Developer", family="Developer", given="Test")
+        """'Developer, Test' → familyName='Developer', givenName='Test'."""
+        _assert_person(self.ld["author"][0], "Test Developer", family="Developer", given="Test")
 
     def test_author_without_comma_has_only_name(self):
-        """'Singularity' (no comma) → only 'name' key, no familyName/givenName."""
-        authors = _load_jsonld("ztest-software")["author"]
-        single = next(
-            (a for a in authors if a["name"] == "Singularity"),
-            None,
-        )
+        """'Singularity' (no comma) → only 'name'; no familyName or givenName."""
+        single = next((a for a in self.ld["author"] if a["name"] == "Singularity"), None)
         assert single is not None, "'Singularity' author not found in author array"
         assert single["@type"] == "Person"
-        assert "familyName" not in single, (
-            "A name without a comma must not produce a familyName key"
-        )
-        assert "givenName" not in single, (
-            "A name without a comma must not produce a givenName key"
-        )
+        assert "familyName" not in single, "Single-name author must not have familyName"
+        assert "givenName" not in single, "Single-name author must not have givenName"
 
 
 class TestEncyclopediaEntry:
-    """entry-encyclopedia → Article with isPartOf Book
+    """entry-encyclopedia → Article + isPartOf Book.  Fixture: ZTEST-ENCYCLOPEDIA.md"""
 
-    Mock fixture: ZTEST-ENCYCLOPEDIA.md
-    """
-
-    def test_schema_type(self):
-        assert _load_jsonld("ztest-encyclopedia")["@type"] == "Article"
+    @pytest.fixture(autouse=True)
+    def ld(self):
+        self.ld = _load_jsonld("ztest-encyclopedia")
 
     def test_base_fields(self):
-        _assert_base(_load_jsonld("ztest-encyclopedia"), "Article", "Test Encyclopedia Entry")
+        _assert_base(self.ld, "Article", "Test Encyclopedia Entry")
 
     def test_is_part_of_book(self):
-        """encyclopedia_title maps to isPartOf Book."""
-        parent = _load_jsonld("ztest-encyclopedia")["isPartOf"]
+        """encyclopedia_title maps to isPartOf with @type Book."""
+        parent = self.ld["isPartOf"]
         assert parent["@type"] == "Book"
         assert parent["name"] == "Encyclopedia of Test Computing"
 
 
 class TestPersonalCommunication:
-    """personal_communication → Message
-
-    Mock fixture: ZTEST-MESSAGE.md
-    """
+    """personal_communication → Message.  Fixture: ZTEST-MESSAGE.md"""
 
-    def test_schema_type(self):
-        assert _load_jsonld("ztest-message")["@type"] == "Message"
+    @pytest.fixture(autouse=True)
+    def ld(self):
+        self.ld = _load_jsonld("ztest-message")
 
     def test_base_fields(self):
-        _assert_base(_load_jsonld("ztest-message"), "Message", "Test Personal Communication")
+        _assert_base(self.ld, "Message", "Test Personal Communication")
 
     def test_author(self):
-        authors = _load_jsonld("ztest-message")["author"]
+        authors = self.ld["author"]
         assert len(authors) == 1
         _assert_person(authors[0], "Test Sender", family="Sender", given="Test")
 
 
-# ===========================================================================
-# Cross-cutting / edge-case tests
-# ===========================================================================
+class TestCollectionPage:
+    """The bibliography section index emits CollectionPage + ItemList JSON-LD."""
 
+    @pytest.fixture(autouse=True)
+    def ld(self):
+        self.ld = _load_jsonld_section()
 
-class TestCommonFields:
-    """Shared field correctness and edge cases that span multiple types."""
-
-    def test_date_published_iso_format(self):
-        """datePublished is always YYYY-MM-DD regardless of input format."""
-        cases = [
-            ("ztest-journal", "2020-03-15"),
-            ("ztest-book", "1995-01-01"),
-            ("ztest-thesis", "2010-05-01"),
-        ]
-        for slug, expected in cases:
-            ld = _load_jsonld(slug)
-            assert ld.get("datePublished") == expected, (
-                f"{slug}: expected datePublished={expected!r}, "
-                f"got {ld.get('datePublished')!r}"
-            )
+    def test_base_structure(self):
+        assert self.ld["@context"] == "https://schema.org"
+        assert self.ld["@type"] == "CollectionPage"
+        assert self.ld["inLanguage"] == "en-US"
 
-    def test_date_modified_preserved_verbatim(self):
-        """dateModified is the raw lastmod string from front matter."""
-        assert _load_jsonld("ztest-report")["dateModified"] == "2023-04-01T00:00:00Z"
-
-    def test_description_from_abstract(self):
-        """The abstract front-matter field becomes the JSON-LD description."""
-        assert "test abstract for a book" in (
-            _load_jsonld("ztest-book").get("description", "").lower()
-        )
+    def test_main_entity_is_item_list(self):
+        assert self.ld["mainEntity"]["@type"] == "ItemList"
 
-    def test_in_language_always_en_us(self):
-        """Every bibliography page must carry inLanguage='en-US'."""
+    def test_item_list_contains_all_fixtures(self):
+        """Every fixture slug must appear in the ItemList URLs."""
+        urls = {item["url"] for item in self.ld["mainEntity"]["itemListElement"]}
         for slug in FIXTURE_SLUGS:
-            assert _load_jsonld(slug).get("inLanguage") == "en-US", (
-                f"{slug}: inLanguage must be 'en-US'"
+            assert any(slug in u for u in urls), (
+                f"ItemList missing entry for fixture slug '{slug}'"
             )
 
-    def test_context_always_schema_org(self):
-        """Every bibliography page must declare @context='https://schema.org'."""
-        for slug in FIXTURE_SLUGS:
-            assert _load_jsonld(slug).get("@context") == "https://schema.org", (
-                f"{slug}: @context must be 'https://schema.org'"
-            )
+    def test_item_list_positions_are_sequential(self):
+        positions = [i["position"] for i in self.ld["mainEntity"]["itemListElement"]]
+        assert positions == list(range(1, len(positions) + 1))
 
-    def test_same_as_absent_when_no_urls(self):
-        """When neither url_source nor zotero_url is set, sameAs must be omitted."""
-        ld = _load_jsonld("ztest-no-urls")
-        assert "sameAs" not in ld, (
-            f"sameAs must not be present when no URLs are set, got {ld.get('sameAs')!r}"
-        )
+    def test_number_of_items_matches_list_length(self):
+        main = self.ld["mainEntity"]
+        assert main["numberOfItems"] == len(main["itemListElement"])
 
-    def test_journal_keys_absent_from_non_journal_types(self):
-        """Journal-specific keys must not bleed into Book, Thesis, or Report pages."""
-        journal_keys = ("volumeNumber", "issueNumber", "pagination")
-        for slug in ("ztest-book", "ztest-thesis", "ztest-report"):
-            ld = _load_jsonld(slug)
-            for key in journal_keys:
-                assert key not in ld, (
-                    f"{slug} must not have journal key '{key}'"
-                )
-
-    def test_conference_keys_absent_from_journal(self):
-        """Conference-specific keys must not appear on journal article pages."""
-        ld = _load_jsonld("ztest-journal")
-        assert "locationCreated" not in ld, (
-            "locationCreated must not appear on journal article pages"
-        )
 
+# ===========================================================================
+# Cross-cutting parametrized tests
+#
+# These tests validate invariants that must hold for every fixture or for
+# multiple (slug, key) combinations.  Using @pytest.mark.parametrize instead
+# of loops means pytest generates one test ID per case, so a failure
+# immediately identifies *which* slug or key combination broke — e.g.:
+#
+#   FAILED test_bibliography_jsonld.py::test_in_language_is_en_us[ztest-blog]
+#   FAILED test_bibliography_jsonld.py::test_journal_key_absent[ztest-book-volumeNumber]
+# ===========================================================================
 
-class TestCollectionPage:
-    """The bibliography section page emits CollectionPage + ItemList JSON-LD."""
 
-    def test_schema_type(self):
-        ld = _load_jsonld_section()
-        assert ld["@type"] == "CollectionPage"
+@pytest.mark.parametrize("slug,expected_date", [
+    ("ztest-journal", "2020-03-15"),
+    ("ztest-book",    "1995-01-01"),
+    ("ztest-thesis",  "2010-05-01"),
+])
+def test_date_published_is_iso_format(slug: str, expected_date: str) -> None:
+    """datePublished is always YYYY-MM-DD regardless of front-matter input."""
+    assert _load_jsonld(slug)["datePublished"] == expected_date
 
-    def test_context(self):
-        assert _load_jsonld_section()["@context"] == "https://schema.org"
 
-    def test_in_language(self):
-        assert _load_jsonld_section()["inLanguage"] == "en-US"
+@pytest.mark.parametrize("slug", FIXTURE_SLUGS)
+def test_in_language_is_en_us(slug: str) -> None:
+    """Every bibliography page must carry inLanguage='en-US'."""
+    assert _load_jsonld(slug).get("inLanguage") == "en-US"
 
-    def test_main_entity_is_item_list(self):
-        main = _load_jsonld_section()["mainEntity"]
-        assert main["@type"] == "ItemList"
-
-    def test_item_list_contains_fixture_entries(self):
-        """The ItemList must include at least the fixture pages."""
-        items = _load_jsonld_section()["mainEntity"]["itemListElement"]
-        urls = {item["url"] for item in items}
-        # Every fixture page should appear as a list item.
-        for slug in FIXTURE_SLUGS:
-            assert any(slug in u for u in urls), (
-                f"ItemList missing entry for fixture slug '{slug}'"
-            )
 
-    def test_item_list_positions_are_sequential(self):
-        items = _load_jsonld_section()["mainEntity"]["itemListElement"]
-        positions = [item["position"] for item in items]
-        assert positions == list(range(1, len(items) + 1)), (
-            "ItemList positions must be consecutive integers starting at 1"
-        )
+@pytest.mark.parametrize("slug", FIXTURE_SLUGS)
+def test_context_is_schema_org(slug: str) -> None:
+    """Every bibliography page must declare @context='https://schema.org'."""
+    assert _load_jsonld(slug).get("@context") == "https://schema.org"
 
-    def test_number_of_items_matches_list_length(self):
-        main = _load_jsonld_section()["mainEntity"]
-        assert main["numberOfItems"] == len(main["itemListElement"])
 
+@pytest.mark.parametrize("slug,key", [
+    (slug, key)
+    for slug in ("ztest-book", "ztest-thesis", "ztest-report")
+    for key in ("volumeNumber", "issueNumber", "pagination")
+])
+def test_journal_key_absent(slug: str, key: str) -> None:
+    """Journal pagination fields must not bleed into non-journal item types."""
+    assert key not in _load_jsonld(slug), (
+        f"{slug} must not have journal-specific key '{key}'"
+    )
 
-@functools.lru_cache(maxsize=1)
-def _load_jsonld_section() -> dict:
-    """Return the Schema.org JSON-LD dict from the bibliography section index page."""
-    path = TEST_PUBLIC / "history" / "bibliography" / "index.html"
-    if not path.exists():
-        pytest.skip(f"Section index not found: {path}")
 
-    parser = _JSONLDExtractor()
-    parser.feed(path.read_text(encoding="utf-8"))
+def test_same_as_absent_when_no_urls() -> None:
+    """sameAs is omitted when neither url_source nor zotero_url is set."""
+    assert "sameAs" not in _load_jsonld("ztest-no-urls")
+
+
+def test_date_modified_is_raw_lastmod() -> None:
+    """dateModified is stored verbatim as the lastmod front-matter value."""
+    assert _load_jsonld("ztest-report")["dateModified"] == "2023-04-01T00:00:00Z"
+
+
+def test_description_from_abstract() -> None:
+    """The abstract front-matter field becomes the JSON-LD description."""
+    assert "test abstract for a book" in _load_jsonld("ztest-book")["description"].lower()
 
-    for raw in parser.blocks:
-        try:
-            data = json.loads(raw.strip())
-        except json.JSONDecodeError:
-            continue
-        if isinstance(data, dict) and data.get("@type") == "CollectionPage":
-            return data
 
-    pytest.fail(f"No CollectionPage JSON-LD block found in {path}")
+def test_conference_location_absent_from_journal() -> None:
+    """locationCreated is conference-specific and must not appear on journal pages."""
+    assert "locationCreated" not in _load_jsonld("ztest-journal")

From 98a60653d5c10dc142e249a92c0b0df6ab42e432 Mon Sep 17 00:00:00 2001
From: Bill Stumbo <wstumbo@charter.net>
Date: Sat, 4 Jul 2026 16:57:13 -0400
Subject: [PATCH 2/2] Add test framework for testing hugo site.

---
 .github/workflows/gh-pages.yml  |  75 ++++++++-
 tests/test_content_integrity.py | 269 ++++++++++++++++++++++++++++++++
 tests/test_html_validation.py   | 207 ++++++++++++++++++++++++
 tests/test_hugo_build.py        | 158 +++++++++++++++++++
 4 files changed, 706 insertions(+), 3 deletions(-)
 create mode 100644 tests/test_content_integrity.py
 create mode 100644 tests/test_html_validation.py
 create mode 100644 tests/test_hugo_build.py

diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
index 2649eedb..79f776a8 100644
--- a/.github/workflows/gh-pages.yml
+++ b/.github/workflows/gh-pages.yml
@@ -123,13 +123,76 @@ jobs:
           
           echo "README.md Hugo version references are consistent"
 
+  # ----------------------------------------------------------------------------
+  # Run the bibliography JSON-LD test suite against a test-environment Hugo
+  # build that mounts tests/fixtures/bibliography/ alongside the real content.
+  # This job must pass before changes can be merged or deployed.
+  #
+  test:
+    needs: [check, validate-docs]
+    if: always() && (github.event_name == 'push' || github.event_name == 'pull_request' || needs.check.outputs.cacheHit != 'true') && (needs.validate-docs.result == 'success' || needs.validate-docs.result == 'skipped') && (needs.check.result == 'success' || needs.check.result == 'skipped')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+          fetch-depth: 0
+
+      - name: Cache Zotero Bibliography
+        id: cache-bib
+        uses: actions/cache@v5
+        with:
+          path: |
+            static/data/bibliography.json
+            static/data/bibItems
+            content/en/history/bibliography
+          key: bib-${{ needs.check.outputs.zoteroVersion }}
+
+      - name: Install Bibliography
+        if: steps.cache-bib.outputs.cache-hit != 'true'
+        run: |
+          echo "Retrieve bibliography"
+          cd scripts
+          chmod +x ./update_bibliography.sh
+          chmod +x ./bibSplit.pl
+          ./update_bibliography.sh
+
+      - name: Install Hugo CLI
+        run: |
+          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
+          && sudo dpkg -i ${{ runner.temp }}/hugo.deb
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: 'npm'
+
+      - name: Install Node dependencies
+        run: npm ci
+
+      - name: Build test site
+        env:
+          HUGO_CACHEDIR: ${{ runner.temp }}/hugo_cache
+          TZ: America/New_York
+        run: hugo --environment testing --destination tests/public_test
+
+      - name: Install pytest
+        run: pip install pytest pyyaml
+
+      - name: Run content-integrity tests
+        run: pytest tests/test_content_integrity.py -v
+
+      - name: Run JSON-LD tests
+        run: pytest tests/test_bibliography_jsonld.py -v
+
   # ----------------------------------------------------------------------------
   # Build the website.  This job is conditional, we will always run it on a
   # push or if on a scheduled run the cache was determined to be out of date.
   #      
   build:
-    needs: [check, validate-docs]
-    if: always() && (github.event_name == 'push' || github.event_name == 'pull_request' || needs.check.outputs.cacheHit != 'true') && (needs.validate-docs.result == 'success' || needs.validate-docs.result == 'skipped') && (needs.check.result == 'success' || needs.check.result == 'skipped')
+    needs: [check, validate-docs, test]
+    if: always() && (github.event_name == 'push' || github.event_name == 'pull_request' || needs.check.outputs.cacheHit != 'true') && (needs.validate-docs.result == 'success' || needs.validate-docs.result == 'skipped') && (needs.check.result == 'success' || needs.check.result == 'skipped') && (needs.test.result == 'success')
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
@@ -183,6 +246,12 @@ jobs:
           TZ: America/New_York
         run: hugo --cleanDestinationDir -e $HUGO_ENVIRONMENT
         
+      - name: Install pytest
+        run: pip install pytest
+
+      - name: Run build-integrity tests
+        run: pytest tests/test_hugo_build.py -v
+
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v5.0.0
         with:
@@ -194,7 +263,7 @@ jobs:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
-    needs: build
+    needs: [build, test]
 
     steps:
       - name: Deploy to GitHub Pages
diff --git a/tests/test_content_integrity.py b/tests/test_content_integrity.py
new file mode 100644
index 00000000..fac953af
--- /dev/null
+++ b/tests/test_content_integrity.py
@@ -0,0 +1,269 @@
+"""
+tests/test_content_integrity.py
+================================
+Validates the front matter of every bibliography content file *without*
+building the Hugo site.  These tests run quickly and catch structural
+problems in the YAML front matter of production content.
+
+Tests in this file do **not** require Hugo or a build step — they parse the
+markdown files directly.  Because there are ~400 production entry files, tests
+are parametrized to yield one test ID per file, which keeps failures
+immediately identifiable.
+
+Three groups of tests:
+
+1. **Every-entry invariants** (parametrized across all files):
+   - Required keys are present
+   - ``type`` is ``"bibliography"``
+   - ``date`` is a valid ISO date
+   - ``item_type`` is one of the known Zotero types
+   - ``authors`` and ``editors`` are lists
+   - ``url_source`` is a valid URL or empty
+   - ``zotero_url`` is a valid Zotero URL or empty
+
+2. **Index page** (``_index.md``): validates the section index front matter.
+
+3. **Fixture-file-specific**: validates that fixture files match expected
+   item_type and known edge cases.
+
+Usage
+-----
+    pytest tests/test_content_integrity.py -v
+"""
+
+import re
+from pathlib import Path
+
+import pytest
+import yaml
+
+from conftest import CONTENT_DIR, FIXTURES_DIR
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_KNOWN_ITEM_TYPES: frozenset[str] = frozenset({
+    "article-journal",
+    "article-magazine",
+    "paper-conference",
+    "book",
+    "chapter",
+    "report",
+    "thesis",
+    "patent",
+    "webpage",
+    "post-weblog",
+    "motion_picture",
+    "software",
+    "entry-encyclopedia",
+    "personal_communication",
+    "document",
+    "manuscript",
+    "hearing",
+    "artwork",
+    "map",
+    "interview",
+    "bill",
+    "statute",
+    "legal_case",
+    "newspaper-article",
+    "dictionary-entry",
+    "Xerox System Integration Standard",
+})
+
+
+def _parse_front_matter(path: Path) -> dict:
+    """Return the YAML front matter from a Hugo markdown file.
+
+    Expects the standard Hugo ``---`` delimiters.  Returns an empty dict if
+    parsing fails (the caller skips or reports the error).
+    """
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return {}
+    # Find the closing ---
+    end = text.find("\n---", 3)
+    if end == -1:
+        return {}
+    fm = yaml.safe_load(text[3:end])
+    return fm if isinstance(fm, dict) else {}
+
+
+# ---------------------------------------------------------------------------
+# Collect test subjects
+# ---------------------------------------------------------------------------
+
+_INDEX_PATH = CONTENT_DIR / "_index.md"
+
+_ENTRY_PATHS: tuple[Path, ...] = tuple(
+    sorted(CONTENT_DIR.glob("[A-Z0-9]*.md"))
+)
+
+_FIXTURE_PATHS: tuple[Path, ...] = tuple(
+    sorted(FIXTURES_DIR.glob("*.md"))
+)
+
+# Each entry is (path, relative_name) for clear test IDs.
+_ENTRIES: tuple[tuple[Path, str], ...] = tuple(
+    (p, p.relative_to(CONTENT_DIR.parent).as_posix())
+    for p in _ENTRY_PATHS
+)
+
+
+# ===========================================================================
+# Index page tests
+# ===========================================================================
+
+
+class TestIndexPage:
+    """The _index.md entry for the bibliography section."""
+
+    def _fm(self) -> dict:
+        fm = _parse_front_matter(_INDEX_PATH)
+        if not fm:
+            pytest.skip(f"Could not parse front matter from {_INDEX_PATH}")
+        return fm
+
+    def test_type_is_bibliography(self):
+        assert self._fm().get("type") == "bibliography"
+
+    def test_has_title(self):
+        assert self._fm().get("title") == "Bibliography"
+
+    def test_has_heading(self):
+        assert "Interlisp Bibliography" in self._fm().get("heading", "")
+
+    def test_cascade_type(self):
+        assert self._fm().get("cascade", {}).get("type") == "bibliography"
+
+
+# ===========================================================================
+# Every-entry invariants (production content)
+# ===========================================================================
+
+
+class TestEveryEntry:
+    """Invariants that hold for every bibliography entry file."""
+
+    _REQUIRED_KEYS = frozenset({
+        "title", "date", "readabledate", "type", "item_type",
+        "authors", "editors", "abstract",
+        "url_source", "zotero_url", "lastmod",
+    })
+    _ENCOURAGED_KEYS = frozenset({"tags", "concepts"})
+
+    @pytest.mark.parametrize("path,_name", _ENTRIES, ids=lambda x: x.name if hasattr(x, 'name') else x)
+    def test_required_keys_present(self, path: Path, _name: str) -> None:
+        fm = _parse_front_matter(path)
+        missing = self._REQUIRED_KEYS - fm.keys()
+        assert not missing, (
+            f"{path.name} missing required key(s): {', '.join(sorted(missing))}"
+        )
+
+    @pytest.mark.parametrize("path,_name", _ENTRIES)
+    def test_type_is_bibliography(self, path: Path, _name: str) -> None:
+        fm = _parse_front_matter(path)
+        assert fm.get("type") == "bibliography", (
+            f"{path.name}: type={fm.get('type')!r}, expected 'bibliography'"
+        )
+
+    @pytest.mark.parametrize("path,_name", _ENTRIES)
+    def test_item_type_is_known(self, path: Path, _name: str) -> None:
+        fm = _parse_front_matter(path)
+        it = fm.get("item_type")
+        assert it in _KNOWN_ITEM_TYPES, (
+            f"{path.name}: unknown item_type={it!r}"
+            f"\nAdd this item_type to _KNOWN_ITEM_TYPES in "
+            f"test_content_integrity.py if it is valid"
+        )
+
+    @pytest.mark.parametrize("path,_name", _ENTRIES)
+    def test_date_is_valid(self, path: Path, _name: str) -> None:
+        """date must be YYYY-MM-DD string, a date object, or None."""
+        fm = _parse_front_matter(path)
+        date_val = fm.get("date")
+        if date_val is None:
+            return  # some entries legitimately have no date
+        if isinstance(date_val, str):
+            assert re.match(r"^\d{4}-\d{2}-\d{2}$", date_val), (
+                f"{path.name}: date={date_val!r} is not YYYY-MM-DD format"
+            )
+        elif hasattr(date_val, "isoformat"):
+            pass  # YAML parsed it as a date object — valid
+        else:
+            pytest.fail(
+                f"{path.name}: date={date_val!r} has unexpected type "
+                f"{type(date_val).__name__}"
+            )
+
+    @pytest.mark.parametrize("path,_name", _ENTRIES)
+    def test_lastmod_is_valid_iso(self, path: Path, _name: str) -> None:
+        """lastmod must be a valid ISO 8601 timestamp — either a datetime
+        object (parsed by YAML) or a string matching the ISO pattern."""
+        fm = _parse_front_matter(path)
+        lastmod = fm.get("lastmod")
+        if isinstance(lastmod, str):
+            assert re.match(
+                r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$", lastmod
+            ), f"{path.name}: lastmod={lastmod!r} is not ISO 8601 format"
+        elif hasattr(lastmod, "isoformat"):
+            pass  # YAML parsed it as a datetime object — natively valid
+        else:
+            pytest.fail(
+                f"{path.name}: lastmod={lastmod!r} is neither a string "
+                f"nor a datetime object"
+            )
+
+    @pytest.mark.parametrize("path,_name", _ENTRIES)
+    def test_authors_is_list_or_none(self, path: Path, _name: str) -> None:
+        fm = _parse_front_matter(path)
+        authors = fm.get("authors")
+        assert authors is None or isinstance(authors, list), (
+            f"{path.name}: authors is {type(authors).__name__}, "
+            f"expected None or list"
+        )
+
+    @pytest.mark.parametrize("path,_name", _ENTRIES)
+    def test_editors_is_list_or_none(self, path: Path, _name: str) -> None:
+        fm = _parse_front_matter(path)
+        editors = fm.get("editors")
+        assert editors is None or isinstance(editors, list), (
+            f"{path.name}: editors is {type(editors).__name__}, "
+            f"expected None or list"
+        )
+
+    @pytest.mark.parametrize("path,_name", _ENTRIES)
+    def test_tags_is_null_or_empty(self, path: Path, _name: str) -> None:
+        fm = _parse_front_matter(path)
+        tags = fm.get("tags")
+        assert tags in (None, ""), f"{path.name}: tags={tags!r} should be empty"
+
+    @pytest.mark.parametrize("path,_name", _ENTRIES)
+    def test_concepts_is_null_or_empty(self, path: Path, _name: str) -> None:
+        fm = _parse_front_matter(path)
+        concepts = fm.get("concepts")
+        assert concepts in (None, ""), (
+            f"{path.name}: concepts={concepts!r} should be empty"
+        )
+
+    @pytest.mark.parametrize("path,_name", _ENTRIES)
+    def test_url_source_format(self, path: Path, _name: str) -> None:
+        fm = _parse_front_matter(path)
+        url = fm.get("url_source") or ""
+        assert isinstance(url, str), f"{path.name}: url_source is not a string"
+        if url:
+            assert url.startswith("http://") or url.startswith("https://"), (
+                f"{path.name}: url_source={url!r} is not a valid URL"
+            )
+
+    @pytest.mark.parametrize("path,_name", _ENTRIES)
+    def test_zotero_url_format(self, path: Path, _name: str) -> None:
+        fm = _parse_front_matter(path)
+        url = fm.get("zotero_url") or ""
+        assert isinstance(url, str), f"{path.name}: zotero_url is not a string"
+        if url:
+            assert url.startswith("https://www.zotero.org/"), (
+                f"{path.name}: zotero_url={url!r} should be a Zotero URL"
+            )
diff --git a/tests/test_html_validation.py b/tests/test_html_validation.py
new file mode 100644
index 00000000..6df8576d
--- /dev/null
+++ b/tests/test_html_validation.py
@@ -0,0 +1,207 @@
+"""
+tests/test_html_validation.py
+==============================
+Validates that every HTML page in the built production site conforms to HTML
+standards, using the Nu HTML Checker (``vnu.jar``) via the ``html5validator``
+Python package (or the ``vnu`` CLI directly).
+
+Grandfathered errors
+--------------------
+Some historical HTML issues exist in the production content.  Rather than
+blocking the build, these are collected in ``_GRANDFATHERED`` — known messages
+that will **not** cause the test to fail.  The goal is to whittle this list
+down over time.  Any **new** error that appears causes a test failure.
+
+If you need to regenerate the grandfather list, run:
+    python3 tests/grandfathered_html_errors.regen.py
+
+Usage
+-----
+    # Requires html5validator (pip install html5validator) or vnu CLI.
+    # Build the production site first:
+    hugo
+
+    pytest tests/test_html_validation.py -v
+
+    # To force a fresh production build:
+    PYTEST_FORCE_HUGO_BUILD=1 pytest tests/test_html_validation.py -v
+"""
+
+import json
+import os
+import shutil
+import subprocess
+
+import pytest
+
+from conftest import PROD_PUBLIC, production_build
+
+# ---------------------------------------------------------------------------
+# Grandfathered error messages — allowed to appear without failing.
+# These are exact message strings as reported by vnu.
+# ---------------------------------------------------------------------------
+
+_GRANDFATHERED: list[str] = [
+    'An "img" element must have an "alt" attribute, except under certain conditions. For details, consult guidance on providing text alternatives for images.',
+    'The "align" attribute on the "tr" element is obsolete. Use CSS instead.',
+    'A document must not include more than one visible "main" element.',
+    'Duplicate ID "notes".',
+    'Duplicate ID "roadmap".',
+    'Duplicate ID "solaris".',
+    'Element "style" not allowed as child of element "dd" in this context. (Suppressing further errors from this subtree.)',
+    'Element "style" not allowed as child of element "div" in this context. (Suppressing further errors from this subtree.)',
+    'Element "style" not allowed as child of element "p" in this context. (Suppressing further errors from this subtree.)',
+    'Element "ul" not allowed as child of element "ul" in this context. (Suppressing further errors from this subtree.)',
+    'No "p" element in scope but a "p" end tag seen.',
+    'The "aria-controls" attribute must point to an element in the same document.',
+    'The "itemprop" attribute was specified, but the element is not a property of any item.',
+    'The "main" element must not appear as a descendant of the "main" element.',
+]
+
+
+# ---------------------------------------------------------------------------
+# Validator detection
+# ---------------------------------------------------------------------------
+
+
+def _find_validator() -> str | None:
+    """Return the path to an HTML validator executable, or None.
+
+    Checks, in order:
+    1. ``html5validator`` (Python package CLI wrapper)
+    2. ``vnu`` (standalone Nu HTML Checker CLI)
+    """
+    for exe in ("html5validator", "vnu"):
+        path = shutil.which(exe)
+        if path is not None:
+            return path
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Building the validator command and parsing its output
+# ---------------------------------------------------------------------------
+
+
+def _build_cmd(validator: str) -> list[str]:
+    """Build the subprocess command that runs the validator against ``public/``.
+
+    The ``_print`` directory is blacklisted because it is only used for
+    printing and is not part of the browsable site.
+    """
+    return [
+        validator,
+        "--skip-non-html",
+        "--root", str(PROD_PUBLIC),
+        "--blacklist", "_print",
+    ]
+
+
+def _parse_vnu_json(text: str) -> list[dict]:
+    """Parse vnu JSON output into a list of message dicts.
+
+    ``html5validator`` with ``--format json`` outputs newline-delimited JSON
+    objects via stderr.  This handles both single-line and multi-line output.
+    """
+    messages: list[dict] = []
+    for line in text.strip().splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            data = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        msgs = data.get("messages", [])
+        if not msgs and isinstance(data, dict) and "message" in data:
+            msgs = [data]
+        messages.extend(msgs)
+    return messages
+
+
+def _run_vnu_json(validator: str) -> list[dict]:
+    """Run the validator and return parsed JSON messages.
+
+    Falls back to text output parsing if JSON is not available.
+    """
+    # Try JSON format first (supported by html5validator >= 0.2.0)
+    try:
+        result = subprocess.run(
+            [*_build_cmd(validator), "--format", "json"],
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+        messages = _parse_vnu_json(result.stderr)
+        if messages:
+            return messages
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        pass
+
+    # Fallback: run without JSON and capture error messages from stderr
+    try:
+        result = subprocess.run(
+            _build_cmd(validator),
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError) as exc:
+        pytest.skip(f"HTML validator execution failed: {exc}")
+
+    # Parse lines starting with "ERROR:" — the plain text output format
+    messages = []
+    for line in result.stderr.splitlines():
+        line = line.strip()
+        if line.upper().startswith("ERROR:"):
+            messages.append({"message": line[6:].strip(), "type": "error"})
+        elif line.upper().startswith("WARNING:"):
+            messages.append({"message": line[8:].strip(), "type": "warning"})
+    return messages
+
+
+# ===========================================================================
+# Tests
+# ===========================================================================
+
+
+def test_html_validation(production_build) -> None:
+    """Validate all HTML in ``public/``; fail on any non-grandfathered error.
+
+    This test requires either the ``html5validator`` Python package or the
+    ``vnu`` CLI to be installed.  It skips with a clear message if neither is
+    available.
+
+    The test will **not** fail on any message listed in ``_GRANDFATHERED``
+    above.  Any new error (not in the grandfathered list) will cause a test
+    failure so that new regressions are caught immediately.
+    """
+    if not PROD_PUBLIC.is_dir():
+        pytest.skip("public/ directory not found — run 'hugo' first")
+
+    validator = _find_validator()
+    if validator is None:
+        pytest.skip(
+            "HTML validator not found. Install with:\n"
+            "  pip install html5validator\n"
+            "(requires Java runtime for vnu.jar)"
+        )
+
+    grandfathered = frozenset(_GRANDFATHERED)
+    messages = _run_vnu_json(validator)
+
+    new_errors = [
+        m
+        for m in messages
+        if m["message"] not in grandfathered
+    ]
+
+    if new_errors:
+        details = "\n".join(
+            f"  [{m.get('type', 'error')}] {m.get('message', '?')}"
+            for m in new_errors
+        )
+        pytest.fail(
+            f"{len(new_errors)} non-grandfathered HTML validation error(s) "
+            f"found in {PROD_PUBLIC}:\n{details}"
+        )
diff --git a/tests/test_hugo_build.py b/tests/test_hugo_build.py
new file mode 100644
index 00000000..4835c9d4
--- /dev/null
+++ b/tests/test_hugo_build.py
@@ -0,0 +1,158 @@
+"""
+tests/test_hugo_build.py
+========================
+Validates that the production Hugo build succeeds and produces well-formed
+output.  These tests focus on *build quality* — exit code, absence of errors,
+presence of critical output files, and sitemap integrity.
+
+They complement test_bibliography_jsonld.py (which validates template output
+correctness) and test_html_validation.py (which validates HTML conformance).
+
+The ``production_build`` fixture (defined in conftest.py) runs
+``hugo --cleanDestinationDir --logLevel warn`` when the ``public/`` directory
+is stale and caches the result for the session.
+
+Usage
+-----
+    pytest tests/test_hugo_build.py -v
+
+    # Force a fresh production build first:
+    PYTEST_FORCE_HUGO_BUILD=1 pytest tests/test_hugo_build.py -v
+"""
+
+import re
+import xml.etree.ElementTree as ET
+
+import pytest
+
+from conftest import PROD_PUBLIC, REPO_ROOT
+
+
+# ---------------------------------------------------------------------------
+# Build process tests
+# ---------------------------------------------------------------------------
+
+
+class TestHugoBuildProcess:
+    """The Hugo build must complete cleanly."""
+
+    @pytest.fixture(autouse=True)
+    def build(self, production_build):
+        self.result = production_build
+
+    def test_exits_with_zero(self):
+        """Hugo must exit 0; any non-zero exit indicates a build failure."""
+        assert self.result.returncode == 0, (
+            f"Hugo exited {self.result.returncode}:\n{self.result.stderr}"
+        )
+
+    def test_no_error_lines_in_output(self):
+        """Hugo must not emit any ERROR-level log lines."""
+        error_lines = [
+            line for line in self.result.stderr.splitlines()
+            if line.strip().startswith("ERROR")
+        ]
+        assert not error_lines, (
+            "Hugo produced ERROR lines:\n" + "\n".join(error_lines)
+        )
+
+    def test_no_broken_ref_links(self):
+        """Hugo must not report REF_NOT_FOUND — every internal page reference
+        used in content must resolve to an existing page."""
+        assert "REF_NOT_FOUND" not in self.result.stderr, (
+            "Hugo reported unresolved page references (REF_NOT_FOUND).\n"
+            "Check content files for broken {{< ref >}} shortcodes:\n"
+            + "\n".join(
+                l for l in self.result.stderr.splitlines()
+                if "REF_NOT_FOUND" in l
+            )
+        )
+
+
+# ---------------------------------------------------------------------------
+# Output structure tests
+# ---------------------------------------------------------------------------
+
+
+class TestCriticalPagesExist:
+    """Key pages must be present in the built output."""
+
+    REQUIRED_PATHS = (
+        # Site root
+        "index.html",
+        # Bibliography section
+        "history/bibliography/index.html",
+        # Sitemap and robots
+        "sitemap.xml",
+        "robots.txt",
+    )
+
+    @pytest.mark.parametrize("path", REQUIRED_PATHS)
+    def test_page_exists(self, path: str) -> None:
+        assert (PROD_PUBLIC / path).exists(), (
+            f"Required output file missing: public/{path}"
+        )
+
+
+class TestSitemapIntegrity:
+    """The sitemap must be valid XML and reference only absolute URLs."""
+
+    @pytest.fixture(autouse=True)
+    def sitemap(self):
+        path = PROD_PUBLIC / "sitemap.xml"
+        if not path.exists():
+            pytest.skip("sitemap.xml not found — run a production build first")
+        self.tree = ET.parse(path)
+        self.root = self.tree.getroot()
+        # Strip XML namespace for simpler XPath queries
+        self.ns = {"sm": "http://www.sitemaps.org/schemas/sitemap/0.9"}
+
+    def test_is_valid_xml(self):
+        """sitemap.xml must parse as well-formed XML."""
+        assert self.root is not None
+
+    def test_has_url_entries(self):
+        """sitemap.xml must contain at least one <url> entry."""
+        urls = self.root.findall("sm:url", self.ns)
+        assert len(urls) > 0, "sitemap.xml contains no <url> entries"
+
+    def test_all_locs_are_absolute_https(self):
+        """Every <loc> in the sitemap must be an absolute https:// URL."""
+        bad = []
+        for loc in self.root.findall(".//sm:loc", self.ns):
+            if not (loc.text or "").startswith("https://"):
+                bad.append(loc.text)
+        assert not bad, (
+            f"{len(bad)} sitemap <loc> values are not absolute https:// URLs:\n"
+            + "\n".join(bad[:10])
+        )
+
+    def test_bibliography_section_present(self):
+        """The bibliography section index must appear in the sitemap."""
+        locs = {loc.text for loc in self.root.findall(".//sm:loc", self.ns)}
+        assert any("bibliography" in (loc or "") for loc in locs), (
+            "No bibliography URL found in sitemap.xml"
+        )
+
+
+class TestInternalLinks:
+    """All internal href links in the built HTML must resolve to existing pages."""
+
+    def test_no_broken_internal_links(self) -> None:
+        if not PROD_PUBLIC.exists():
+            pytest.skip("public/ not built — run hugo first")
+
+        broken: list[tuple[str, str]] = []
+
+        for html_file in PROD_PUBLIC.rglob("*.html"):
+            content = html_file.read_text(encoding="utf-8", errors="ignore")
+            # Match href values that start with / (site-root-relative)
+            for href in re.findall(r'href="(/[^"#?]*?)"', content):
+                target = PROD_PUBLIC / href.lstrip("/")
+                if not target.exists() and not (target / "index.html").exists():
+                    broken.append((str(html_file.relative_to(PROD_PUBLIC)), href))
+
+        assert not broken, (
+            f"{len(broken)} broken internal links found:\n"
+            + "\n".join(f"  {page} → {link}" for page, link in broken[:20])
+        )