Acceptance Testing Suite

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• build_story_artifact.py
• diagram_inventory.json
• story_template.html
• tests/test_story_artifact.py

The Acceptance Testing Suite ensures the structural integrity, content coverage, and offline availability of the GestaltView visual story artifact. It validates that the index.html entry point remains self-contained and accurately reflects the source material defined in the project inventory. The suite primarily focuses on verifying the transformation of the 116-page wiki PDF into a curated visual experience.

Sources: README.md:58-62, tests/test_story_artifact.py:10-13

Architecture and Test Flow

The testing suite operates as a post-build validation layer. It executes against the index.html artifact and the diagram_inventory.json metadata file generated by the build system.

Validation Sequence

The following diagram illustrates the relationship between the builder, the generated artifacts, and the testing suite.

The testing suite verifies that all outputs from the builder are present, correctly formatted, and free of processing artifacts like broken ligatures.
Sources: build_story_artifact.py:270-285, tests/test_story_artifact.py:11-65

Core Validation Categories

1. Inventory Integrity

The suite validates that the diagram_inventory.json contains the expected number of visual items categorized by their source form. It enforces a strict count to ensure no diagrams are lost during the PDF extraction process.

Visual Category	Expected Count	Description
Curated Diagrams	13	Opening diagrams preserved as PDF page crops.
Captioned Figures	39	Later figure-caption entries preserved as crops.
Mermaid Snippets	2	Flowcharts rendered from raw Mermaid source text.
Total	54	Total visual assets across 116 pages.

Sources: diagram_inventory.json:3-8, tests/test_story_artifact.py:17-21

2. Content Quality and Normalization

The tests inspect extracted text fields for "broken" text patterns, which often occur during PDF text extraction due to ligature issues. It specifically scans for and forbids patterns such as "De fi nitions", "fl ow", and "pro fi ".

Sources: build_story_artifact.py:157-164, tests/test_story_artifact.py:46-48

3. Artifact Self-Containment

A critical requirement for the index.html artifact is that it must be host-ready with no external dependencies. The suite performs a string search to ensure no remote assets (starting with src="http) are required at runtime. All images are embedded as Base64 data URIs within the final HTML.

Sources: README.md:7-10, tests/test_story_artifact.py:64

Key Test Functions and Logic

The StoryArtifactAcceptanceTests class in tests/test_story_artifact.py implements the following logic:

• Existence Verification: Confirms that diagram_inventory.json and index.html exist in the repository root.
• Confidence Scoring: Every item in the inventory must have a confidence level of "high" and an associated confidence_note.
• Explanation Depth: Validates that each curated diagram provides three levels of explanation: orientation, system, and architecture.
• Asset Linkage: Checks that every asset_path defined in the inventory points to a valid file on the disk within story_assets/.
• Mermaid Verification: Ensures that items marked as mermaid_source actually contain valid Mermaid syntax starting with graph TD.

Sources: tests/test_story_artifact.py:25-44, tests/test_story_artifact.py:50-54

Automated Execution

You run the acceptance tests using the Python unittest module from the repository root. This should be performed after any rebuild of the site from the source PDF.

python3 -m unittest discover -s tests -v

The test runner discovers the suite in the tests/ directory and provides a verbose output of the validation results.

Sources: README.md:60, README.md:67-69

Summary

The Acceptance Testing Suite acts as the final gate in the GestaltView publication pipeline. By enforcing strict counts for curated diagrams and captioned figures, validating offline asset embedding, and scrubbing text for extraction artifacts, it guarantees that the visual story remains a reliable, high-fidelity reference for the underlying system architecture.