# What Is the Purpose of the Tests Directory in Nutlope Hallmark? > Discover the purpose of the tests directory in Nutlope Hallmark. This suite validates design generation, enforces diversification, and prevents markup regressions. - Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark) - Tags: how-to-guide - Published: 2026-08-10 --- **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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/brief.md)** – Records the original user prompt and the step-by-step design flow decisions - **[`index.html`](https://github.com/Nutlope/hallmark/blob/main/index.html)** – The fully rendered landing page generated by the skill - **[`style.css`](https://github.com/Nutlope/hallmark/blob/main/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: ```bash # 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/brief.md) describing the prompt and design flow steps 3. Run the Hallmark CLI to generate [`index.html`](https://github.com/Nutlope/hallmark/blob/main/index.html) and [`style.css`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/brief.md)**, **[`index.html`](https://github.com/Nutlope/hallmark/blob/main/index.html)**, and **[`style.css`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/index.html) and [`style.css`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.