Testing Framework

The HoloPrint testing framework is designed to automate the validation of resource pack generation, 3D preview rendering, and translation coverage. It utilizes a headless browser environment powered by Puppeteer to simulate user interactions and verify the integrity of the generated Minecraft Bedrock Edition resource packs. The framework supports testing both the raw source code and the minified distribution builds.

The system is integrated with GitHub Actions, allowing for automated quality control during the development pipeline. It primarily focuses on ensuring that various .mcstructure files can be processed without errors and that the resulting holograms render correctly within the browser context.

Core Test Runner Architecture

The foundation of the testing framework is a headless browser runner that abstracts the complexities of setting up a local web server and managing browser instances.

Headless Browser Runner

The runner initializes a local HTTP server using the Node.js http module to serve project files, which is necessary to bypass browser security restrictions when loading ES modules. It supports two primary modes: testing the production build (defaulting to the dist directory) or testing the raw source code (src directory).

This diagram shows the lifecycle of a single test execution within the framework.
Sources: tests/headlessBrowserTestRunner.js:18-77

Component Details

Sources: tests/headlessBrowserTestRunner.js:18-24, tests/headlessBrowserTestRunner.js:74-76, tests/headlessBrowserTestRunner.js:92-138

Automated Structure Testing

The framework includes a specialized suite for testing a collection of sample Minecraft structures. This ensures the HoloPrint.makePack logic remains compatible with various block configurations and NBT structures.

Sample Structure Pipeline

1. File Discovery: The runner reads all .mcstructure files from the tests/sampleStructures directory.
2. Pack Generation: For each structure, the test body invokes HoloPrint.makePack within the browser environment.
3. Performance Tracking: The system records the time taken to generate each pack to monitor for performance regressions.
4. Visual Verification: In Chrome-based runners, the framework waits for the canvas element in the preview container and takes a screenshot of the rendered hologram.
5. Artifact Handling: Completed packs are "uploaded" via a POST request to the local test server and saved to tests/completedPacks.

The sequence above illustrates the process of generating a pack and capturing visual artifacts during a test run.
Sources: tests/testSampleStructures/index.js:21-65, tests/testSampleStructures/index.js:80-112

Data and Translation Validation

The testing framework extends beyond functional UI tests to include data integrity checks, specifically focusing on block metadata and translation coverage.

Block Translation Coverage

This test validates that the MaterialList component correctly handles all blocks defined in the vanilla Minecraft metadata.

• Metadata Integration: It fetches mojang-blocks.json and mojang-items.json to identify the current set of vanilla blocks.
• Filtering Logic: It excludes chemistry features (e.g., element_, colored_torch_) and specifically ignored blocks defined in HoloPrint.IGNORED_BLOCKS.
• Verification: It iterates through the block list and ensures the MaterialList can successfully add and map each block to a translation key.

Sources: tests/checkBlockTranslationCoverage/index.js:13-43, src/HoloPrint.js:24-25

Build Pipeline Integration

The testing framework is closely tied to the build pipeline. The pipeline/build.js script provides a testing version string by default if no version is specified, ensuring that test artifacts generated during CI are clearly identified.

const buildVersion = process.argv.find(arg => arg.startsWith(versionParamName))?.slice(versionParamName.length) ?? "testing";

Sources: pipeline/build.js:14

Summary of Framework Capabilities

The HoloPrint testing framework provides a robust environment for regression testing. By combining headless browser automation with Minecraft-specific data validation, it ensures that:

• Pack generation is fast and error-free across various structure types.
• The 3D preview renderer functions correctly in modern browser engines.
• Translations and material lists remain up-to-date with Minecraft's evolving block metadata.