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

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

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

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

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

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:

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.

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