What Is the Purpose of the Tests Directory in Nutlope Hallmark?

The site/_tests directory serves as a comprehensive generation-test suite that validates Hallmark's design-generation pipeline, enforces diversification rules to prevent repetitive outputs, and provides automated slop-test gates to catch regressions in generated markup.

The site/_tests directory in the Nutlope/hallmark repository functions as the primary validation harness for this AI-powered design generation skill. Unlike traditional unit test folders, this directory houses real-world design outputs that verify the entire pipeline—from prompt ingestion to rendered HTML—while serving as a living gallery of the skill's capabilities. Understanding the purpose of the tests directory reveals how Hallmark maintains output quality and ensures design diversity across sessions.

Generation Tests and Real-World Test Cases

The core function of site/_tests is to hold generation-tests that mirror exactly what the Hallmark skill produces for user briefs. As documented in site/_tests/README.md, each numbered sub-folder (e.g., 01, 02, through 08) contains three artefacts that constitute a complete design output:

• brief.md – Records the original user prompt and the step-by-step design flow decisions
• index.html – The fully rendered landing page generated by the skill
• style.css – Page-specific design tokens and component styles

This structure ensures that every test case represents a reproducible snapshot of the generation pipeline, providing concrete examples of the skill's output for contributors and users.

Viewing Tests Locally

You can inspect any generated test case directly in your browser without running a build process:

# From the repository root

open site/_tests/02/index.html

For active development, these pages are automatically served when you start the dev server, allowing immediate visual verification of the generation output.

Diversity Enforcement and Rotation Rules

The tests enforce Hallmark's diversification system, which prevents the skill from repeating designs across a session. According to the specifications in site/_tests/README.md, the validation suite exercises strict "rotation" and "diversification" rules:

• No two test pages share the same macrostructure
• Each page uses distinct theme configurations
• Hero archetypes vary across all test cases

This enforcement ensures that the AI produces novel layouts rather than templated outputs, with the test suite serving as proof that these anti-repetition rules function correctly across multiple generations.

Automated Slop-Test Gates

The directory includes automated slop-test gates that catch low-quality markup before it reaches production. These gates automatically validate critical accessibility and usability criteria whenever the dev server initializes, with any failures appearing immediately in the console output.

Key validation checks defined in site/_tests/README.md include:

• Detection of unwanted horizontal scroll
• Verification of proper ARIA labels
• Confirmation of micro-interaction defaults

These gates run against the generated index.html files in each test folder, providing immediate feedback on markup quality without requiring manual code review.

Verb Examples and Minimal Test Cases

Beyond full design generations, the site/_tests/verbs/ directory contains minimal examples demonstrating each supported Hallmark verb. These lightweight test cases illustrate how the skill behaves on tiny inputs for specific operations:

• audit – Analyzes existing designs for improvements
• refine – Iterates on specific components
• redesign – Complete layout transformations
• study – Research and reference gathering

Each verb folder includes a dedicated README.md explaining the specific test parameters and expected outputs for that operation mode, serving as documentation for the skill's various capabilities.

Gallery Integration and Thumbnails

The test directory doubles as a content source for the public gallery on Hallmark's main landing page. The site/_tests/_thumbs/ sub-folder contains screenshot thumbnails of each test case, automatically referenced by the site generator to showcase the skill's output variety to visitors.

When adding new test cases, you can optionally generate thumbnails and place them in this directory to update the public-facing documentation and visual examples.

Extending the Test Suite

To add new generation scenarios to the validation harness:

1. Create a numbered folder under site/_tests/ (continuing the sequence, e.g., 09)
2. Add a brief.md describing the prompt and design flow steps
3. Run the Hallmark CLI to generate index.html and style.css
4. (Optional) Generate a thumbnail and place it in site/_tests/_thumbs/

This workflow ensures that new functionality is always accompanied by verifiable, self-contained examples that future contributors can inspect and validate.

Summary

• The site/_tests directory houses generation-tests that validate the complete Hallmark design pipeline from prompt to rendered output.
• Each test case folder contains brief.md, index.html, and style.css, mirroring production artefacts exactly as the skill generates them.
• Diversity enforcement rules ensure no two tests share macrostructures, themes, or hero archetypes, preventing repetitive AI outputs across sessions.
• Slop-test gates automatically check for horizontal scroll, ARIA compliance, and interaction defaults when the dev server starts.
• The _thumbs folder powers the public gallery, while the verbs subdirectory demonstrates minimal examples for each supported operation mode (audit, refine, redesign, study).

Frequently Asked Questions

Where are the test files located in the Hallmark repository?

The test files reside in site/_tests/, not a top-level tests directory. This location places the generation tests within the site build structure, allowing the dev server to serve them directly and reference them for the public gallery thumbnail display.

How do I run the Hallmark test suite locally?

You do not need a separate test runner. Start the development server and the slop-test gates automatically validate all test cases in site/_tests/ against quality criteria. Alternatively, open any test folder's index.html directly in a browser using open site/_tests/[number]/index.html from the repository root to view static outputs.

What is the purpose of the brief.md files in the tests?

Each brief.md serves as documentation and input specification for its test case. It records the original user prompt and the step-by-step design flow decisions made by the Hallmark skill, providing transparency into how the generated index.html and style.css were produced from the initial input.

Does Hallmark use traditional unit tests or only generation tests?

According to the repository structure and site/_tests/README.md, Hallmark relies primarily on generation-tests rather than traditional unit tests. These validate the end-to-end design generation pipeline, including output quality gates and diversification rules, ensuring the skill produces valid, varied HTML and CSS rather than testing individual functions in isolation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}