How to Run Tests in Hallmark: A Complete Guide to Manual Validation

Hallmark does not include an automated test suite; instead, you validate the skill by running npm run serve and manually verifying the UI against the Slop Test reference scenarios.

This guide walks you through the testing workflow for Hallmark, a design skill for AI coding assistants maintained at Nutlope/hallmark. Since the repository contains no traditional unit tests, understanding the intended validation process is essential for contributors and users who want to ensure the skill performs as designed.

The Testing Approach in Hallmark

Most open-source projects include a test script in package.json. Hallmark takes a different approach appropriate for its purpose as an AI coding assistant skill. Rather than automated unit tests, the repository provides a structured reference document that defines expected behaviors, which you verify through manual inspection of the rendered UI.

According to the source code, the only script defined in package.json is serve:

{
  "scripts": {
    "serve": "python3 -m http.server 4173 --directory site"
  }
}

This confirms there is no npm test command available. Testing relies on the Slop Test reference located at skills/hallmark/references/slop-test.md.

Step-by-Step Testing Workflow

1. Clone and Prepare the Repository

Start by obtaining the latest version of Hallmark:

git clone https://github.com/Nutlope/hallmark.git
cd hallmark

Hallmark has no external npm dependencies, so npm install is optional and essentially a no-op.

2. Start the Development Server

Launch the local server using the only available npm script:

npm run serve

This executes python3 -m http.server 4173 --directory site, making the skill available at http://localhost:4173. The server hosts all files from the site/ directory, including index.html and supporting assets.

3. Access the Slop Test Reference

Open the authoritative test specification:

• File path: skills/hallmark/references/slop-test.md

This markdown document contains concrete scenarios with expected outputs. Review each test case to understand what visual and behavioral criteria define a successful implementation.

4. Perform Manual Verification

With the server running and the reference document open:

1. Navigate to http://localhost:4173 in your browser
2. For each scenario in slop-test.md, trigger the corresponding UI state
3. Compare the rendered output against the expected results documented in the reference
4. Check typography, layout, component rendering, and interactive behavior

Mark each scenario as pass or fail based on visual match to the specification.

Key Files for Testing

File	Purpose
package.json	Confirms no test script exists; shows serve as the sole automation entry point
skills/hallmark/references/slop-test.md	The definitive test specification containing all validation scenarios
site/index.html	Main entry point rendered by the development server
site/js/main.js	Core JavaScript driving UI interactions; inspect this when debugging test failures

Creating an Automated Test Harness

If your workflow requires automated validation, you can build a custom test harness around Hallmark's structure. Since the source exposes a standard HTTP server, tools like Playwright or Puppeteer can load http://localhost:4173 and assert against DOM state.

Example outline for a Playwright-based harness:

// tests/hallmark.spec.js
const { test, expect } = require('@playwright/test');

test('hallmark renders correctly', async ({ page }) => {
  await page.goto('http://localhost:4173');
  // Assertions based on slop-test.md criteria
  await expect(page.locator('h1')).toContainText('Hallmark');
});

Note that any automated harness requires you to implement assertions that mirror the criteria in skills/hallmark/references/slop-test.md. The Hallmark repository does not provide such infrastructure.

Summary

• Hallmark has no built-in automated test suite — the package.json contains only a serve script
• Testing is manual — validate against the Slop Test reference at skills/hallmark/references/slop-test.md
• Run npm run serve to start the local server on port 4173
• Inspect site/index.html and site/js/main.js for the implementation details you'll verify

Frequently Asked Questions

Why doesn't Hallmark have unit tests?

Hallmark is a design skill for AI coding assistants, not a conventional software library. Its purpose is to demonstrate visual and interactive patterns that AI systems should reproduce. The Slop Test reference provides human-verifiable criteria that match how AI evaluators assess skill performance, making traditional unit tests less relevant.

Can I add Jest or Mocha tests to Hallmark?

You can extend the repository with any testing framework. However, you'll need to write assertions that validate rendered output against the scenarios in skills/hallmark/references/slop-test.md. The core maintainers have not prioritized this because the skill's primary validation happens through AI-assisted evaluation rather than automated test suites.

What port does Hallmark's test server use?

The server runs on port 4173 as configured in package.json via python3 -m http.server 4173 --directory site. You can modify this by editing the script directly or passing a different port to your own HTTP server command.

Where are the test scenarios documented?

All test scenarios live in skills/hallmark/references/slop-test.md. This file is the authoritative source for what constitutes correct Hallmark behavior and should be your primary reference during any validation workflow.

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