# What Kind of Tests Are Included in the Archify Project? A Complete Guide to the 150+ Test Suite

> Explore the Archify project's extensive test suite, featuring over 150 Node.js tests covering CLI, rendering, zoom, layout validation, and backward compatibility for robust quality assurance.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: testing
- Published: 2026-08-13

---

**Archify includes a comprehensive, self-contained test suite of over 150 test files written with Node.js's built-in `node:test` framework, covering CLI commands, visual rendering, semantic zoom, layout validation, and backward compatibility.**

The **archify** project by `tt-a1i` ships with an extensive testing infrastructure designed to validate every public surface of its architecture-as-code toolchain. According to the source repository, tests are organized into logical groups targeting specific subsystems—from headless browser simulation to CLI end-to-end flows—and are executed via `scripts/run-tests.mjs` using parallel execution when the Node version supports `--test-concurrency`.

## Test Runner Architecture

The entry point for all testing is `scripts/run-tests.mjs`, a custom harness that discovers and executes test files.

### How the Test Runner Works

```bash
node scripts/run-tests.mjs

```

This script performs three operations:

1. **Discovers** all `*.test.mjs` files in the `archify/test` directory
2. **Sorts** them deterministically for consistent execution order
3. **Executes** with `node --test`, using `--test-concurrency` when available

The runner provides parallel execution on supported Node versions, reducing suite runtime for the 150+ test files.

## Visual-Check Integration Tests

The `visual-check.test.mjs` module validates Archify's headless browser integration for screenshot capture and viewport verification.

### Test Coverage Areas

- Containment viewport detection (four viewports per artifact)
- Endpoint theme capture across multiple visual states
- Error handling when Chrome/Chromium is missing or misconfigured
- Side-car artifact generation and receipt validation

### Example: Visual Check Happy Path

```javascript
test('visual-check records four containment viewports and four endpoint theme captures', async () => {
  const input = artifact('passing.html');
  const browser = fakeBrowser();
  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => browser,
  });

  assert.equal(result.exitCode, 0);
  assert.equal(result.receipt.status, 'pass');
  // …additional assertions omitted for brevity…
});

```

This pattern creates temporary HTML fixtures, injects mock browser instances via `browserFactory`, and validates both the exit code and structured receipt output.

## CLI Command Test Suite

The `cli.test.mjs` file provides **end-to-end validation** of every CLI entry point in the Archify toolchain.

### Commands Under Test

| Command | Validation Focus |
|---------|----------------|
| `archify` | Core invocation, help output, error paths |
| `render` | SVG generation, JSON receipt contracts |
| `deliver` | Artifact packaging, output validation |
| `preview` | Server lifecycle, port handling |
| `validate` | Schema enforcement, error formatting |
| `inspect` | Internal state introspection |
| `guide` | Documentation generation paths |
| `doctor` | Installation diagnostics |

### Platform Handling and Edge Cases

Tests cover platform-specific skips (e.g., Windows path behaviors) and optional external tool integration such as automatic browser opening via `opener`.

### Example: Doctor Command Detects Broken Installations

```javascript
test('cli: doctor identifies an incomplete installation', () => {
  const incompleteRoot = path.join(tmp, 'incomplete-skill');
  // …setup omitted…
  const result = spawnSync(process.execPath, [path.join(incompleteBin, 'archify.mjs'), 'doctor'], {
    cwd: incompleteRoot,
    encoding: 'utf8',
  });

  assert.equal(result.status, 1);
  assert.match(result.stdout, /\[missing\] Core template/);
});

```

This test constructs a deliberately broken skill directory, invokes `archify doctor`, and asserts both the non-zero exit status and diagnostic output format.

## Renderer and Semantic-Zoom Tests

The `semantic-zoom.test.mjs` module guarantees deterministic behavior across zoom levels for all diagram types.

### Diagram Types Validated

- `architecture` — system component diagrams
- `workflow` — process flow visualizations
- `sequence` — interaction diagrams
- `dataflow` — data movement patterns
- `lifecycle` — state transition diagrams

### Zoom Level Thresholds

| Level | Scale Threshold | Purpose |
|-------|---------------|---------|
| `MAP` | `< 1.0` | Overview, minimal detail |
| `READ` | `>= 1.0` | Readable labels, key relationships |
| `FULL` | `>= 1.75` | Complete detail, all attributes |

### Example: Deterministic Zoom Threshold Verification

```javascript
test('semantic zoom exposes MAP, READ, and FULL at deterministic thresholds', () => {
  const html = render('workflow', CASES.workflow);
  assert.match(html, /if \(state\.scale >= 1\.75\) return 'full'/);
  assert.match(html, /if \(state\.scale >= 1\) return 'read'/);
  assert.match(html, /return 'map'/);
});

```

Tests also verify **motion-reduction preferences** via CSS `prefers-reduced-motion` media query handling in generated output.

## Story and Relationship Flow Tests

Two dedicated modules handle narrative and relationship visualization:

- **`story-beat-navigator.test.mjs`** — Validates story-driven navigation patterns including `story-beat`, `story-moment`, and `story-horizon` constructs
- **`relationship-pulse.test.mjs`** — Tests relationship highlighting modes: `preview`, `pulse`, `lens`, and `direct-explorer`

These ensure that interactive presentation features behave correctly across different navigation modes and visual states.

## Layout and Geometry Validation

| Test File | Responsibility |
|-----------|--------------|
| `layout-rules.test.mjs` | Grid constraint enforcement, spatial arrangement rules |
| `geometry.test.mjs` | Low-level geometric utilities, coordinate calculations |

These modules verify that generated diagrams respect defined layout constraints and that geometry-related helper functions produce correct results across edge cases.

## Compatibility and Migration Tests

The `v1-compatibility.test.mjs` module ensures **backward compatibility** with version 1 artifacts. It confirms that:

- Archify can successfully parse legacy input formats
- Correct receipts are generated for v1 inputs
- No silent data loss occurs during processing

This provides upgrade confidence for existing deployments.

## Miscellaneous Unit Tests

Additional focused test modules cover:

| File | Coverage |
|------|----------|
| `generate-validators.test.mjs` | Schema-to-validator code generation |
| `preview.test.mjs` | Preview server startup, shutdown, and error handling |

These complement the integration-heavy CLI and visual-check suites with fast, isolated unit tests for utility functions.

## Running the Test Suite

Execute the full suite via npm:

```bash
npm run test

```

This invokes `scripts/run-tests.mjs`, which exercises the complete pipeline:

1. Input JSON parsing
2. HTML rendering
3. Verification receipt generation
4. Optional artifact opening

Both happy-path and failure-path behaviors are validated across all 150+ test files.

## Summary

Archify's test suite provides comprehensive coverage through:

- **Custom test runner** (`scripts/run-tests.mjs`) with parallel execution support
- **Visual-check tests** (`visual-check.test.mjs`) for headless browser simulation
- **CLI integration tests** (`cli.test.mjs`) covering all commands and error paths
- **Semantic-zoom tests** (`semantic-zoom.test.mjs`) validating zoom thresholds and motion preferences
- **Story and relationship tests** for interactive navigation features
- **Layout and geometry tests** for spatial constraint enforcement
- **Version compatibility tests** (`v1-compatibility.test.mjs`) ensuring backward compatibility
- **Focused unit tests** for validators, preview server, and utilities

## Frequently Asked Questions

### What testing framework does Archify use?

Archify uses **Node.js's built-in `node:test` framework**, introduced in Node 18. This eliminates external dependencies and ensures compatibility with current Node LTS versions. The `scripts/run-tests.mjs` harness provides test discovery and orchestration on top of this native framework.

### How many tests are in the Archify project?

The repository contains **over 150 test files**, with each file typically containing multiple test cases. These are distributed across functional areas: CLI commands, visual rendering, layout validation, compatibility, and unit-level utilities.

### Does Archify test its visual output?

Yes. The `visual-check.test.mjs` module simulates a headless browser environment using injectable browser mocks, validates screenshot capture pipelines, and verifies containment viewport detection without requiring actual Chrome installation in CI environments.

### How does Archify ensure backward compatibility?

The dedicated `v1-compatibility.test.mjs` module parses legacy version 1 artifacts and asserts correct receipt generation. This prevents regressions that would break existing user content during upgrades.

### Can tests run in parallel?

Yes. When running on Node versions that support `--test-concurrency`, `scripts/run-tests.mjs` executes tests in parallel to reduce total suite runtime. The discovery and sorting logic maintains deterministic execution order regardless of parallelism.