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

> Learn how to run tests in Hallmark by following our guide to manual validation. Use npm run serve and Slop Test scenarios to verify your skill's UI effectively.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-08-11

---

**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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/package.json) is `serve`:

```json
{
  "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`](https://github.com/Nutlope/hallmark/blob/main/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:

```bash
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:

```bash
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`](https://github.com/Nutlope/hallmark/blob/main/index.html) and supporting assets.

### 3. Access the Slop Test Reference

Open the authoritative test specification:

- **File path:** [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/package.json) | Confirms no test script exists; shows `serve` as the sole automation entry point |
| [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md) | The definitive test specification containing all validation scenarios |
| [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) | Main entry point rendered by the development server |
| [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/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:

```javascript
// 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/package.json) contains only a `serve` script
- **Testing is manual** — validate against the **Slop Test reference** at [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md)
- **Run `npm run serve`** to start the local server on port 4173
- **Inspect [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) and [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.