Impeccable Testing Approach: Unit Tests for the Build System and Transformers

Impeccable uses Bun’s built-in test runner to execute unit-style tests against its build pipeline and provider-specific transformers, validating filesystem outputs in dist/ and ensuring each transformation logic (Cursor, Claude-Code, Gemini, Codex) produces correctly formatted artifacts.

The pbakaus/impeccable repository employs a comprehensive testing approach that combines integration testing for the build orchestration with isolated unit tests for individual transformers. All tests reside in the tests/ directory and leverage Bun’s native assertion library to verify that the scripts/build.js pipeline correctly generates provider-specific bundles and that each transformer handles front-matter, placeholders, and output formatting according to specification.

Test Suite Architecture

Impeccable’s test suite is organized around unit-style tests that exercise both the holistic build process and individual transformation logic. The project uses Bun’s built-in test runner, invoked via bun test, which automatically discovers all *.test.js files and executes them in parallel.

Unlike external frameworks, the tests rely on Bun’s standard library assertions (assert.equal, assert.deepEqual, etc.), maintaining a minimal dependency footprint. The suite runs against the actual filesystem, validating path handling, file-write permissions, and edge cases such as empty front-matter or missing arguments.

Build System Integration Testing

The integration test located at tests/build.test.js orchestrates the full build pipeline by executing scripts/build.js directly. This test validates that:

• All source markdown files from source/commands and source/skills are read correctly
• Each provider transformer produces the expected output hierarchy inside dist/<provider>/
• No runtime exceptions occur during the build process

Because this test invokes the same script used in production builds, it guarantees that bun run build will always generate a ready-to-publish bundle. The test verifies the existence of output directories for all supported providers: Cursor, Claude-Code, Gemini, and Codex.

Transformer-Specific Unit Tests

Each provider transformer maintains its own isolated test suite under tests/lib/transformers/, ensuring that format-specific requirements are met.

Cursor Transformer Validation

The tests/lib/transformers/cursor.test.js file verifies that the Cursor transformer strips YAML front-matter from source files while preserving command formatting. It checks that the cursorTransformer function creates the expected skill directory layout under dist/cursor/ and maintains plain placeholders (e.g., {{placeholder}}) without modification.

Claude-Code Transformer Validation

In tests/lib/transformers/claude-code.test.js, the test suite ensures that the Claude-Code transformer retains full YAML front-matter as required by the Anthropic Skills specification. Tests validate that command arguments are preserved and that the output structure matches Anthropic’s expected format.

Gemini Transformer Validation

The Gemini transformer tests in tests/lib/transformers/gemini.test.js validate the conversion of commands to TOML format. The suite checks placeholder mapping logic (converting {{arg}} to {{args}}) and verifies the generation of modular GEMINI.*.md skill import files.

Codex Transformer Validation

Located at tests/lib/transformers/codex.test.js, these tests verify the Codex-specific prompt format including description and argument-hint fields. The suite confirms that variables are upper-cased ({{arg}} becomes $ARG) and that skill files are correctly placed under .codex/skills.

Utility and Helper Testing

Shared functionality used across all transformers is tested in tests/lib/utils.test.js. This suite exercises low-level functions such as front-matter parsing and filesystem helpers, ensuring that utilities like path resolution and metadata extraction work consistently regardless of the target provider.

Running the Test Suite

Execute the full test suite from the repository root using Bun’s test runner:

bun test

The runner automatically discovers all *.test.js files and provides a concise report of parallel test execution:

PASS tests/lib/utils.test.js
PASS tests/lib/transformers/cursor.test.js
PASS tests/lib/transformers/claude-code.test.js
PASS tests/lib/transformers/gemini.test.js
PASS tests/lib/transformers/codex.test.js
PASS tests/build.test.js

Example Unit Test Implementation

The following pattern from tests/lib/transformers/cursor.test.js demonstrates how transformer logic is validated:

import { readFileSync } from 'fs';
import { cursorTransformer } from '../../scripts/lib/transformers/cursor.js';
import assert from 'assert';

test('Cursor transformer strips front-matter and formats command', () => {
  const source = readFileSync('source/commands/example.md', 'utf8');
  const result = cursorTransformer(source);
  // Cursor output should contain only the body (no YAML) and use plain placeholders
  assert.ok(!result.includes('---'), 'No front-matter should remain');
  assert.ok(result.includes('{{placeholder}}'), 'Placeholder must stay unchanged');
});

Example Integration Test Pattern

The build integration test uses child process execution to validate the end-to-end pipeline:

import { execSync } from 'child_process';
import { existsSync } from 'fs';
import assert from 'assert';

test('Full build generates all provider bundles', () => {
  execSync('bun run build', { stdio: 'inherit' });

  // Verify that each provider directory exists after the build
  const providers = ['cursor', 'claude-code', 'gemini', 'codex'];
  for (const p of providers) {
    assert.ok(
      existsSync(`dist/${p}`),
      `dist/${p} should be created`
    );
  }
});

Summary

• Bun Native Runner: Impeccable uses bun test with built-in assertions, avoiding external testing dependencies.
• Integration Coverage: tests/build.test.js validates the entire build pipeline by executing scripts/build.js and verifying dist/ output.
• Transformer Isolation: Each provider (Cursor, Claude-Code, Gemini, Codex) has dedicated unit tests in tests/lib/transformers/ ensuring format compliance.
• Filesystem Validation: Tests run against actual files, verifying path handling, write permissions, and edge cases like empty front-matter.
• Utility Testing: Shared helpers in scripts/lib/utils.js are independently tested to ensure consistent behavior across transformers.

Frequently Asked Questions

What test runner does Impeccable use?

Impeccable uses Bun’s built-in test runner. You invoke it with bun test, which automatically discovers all *.test.js files in the repository and executes them in parallel using Bun’s standard library assertions.

How does Impeccable test its build system?

The build system is tested via integration tests in tests/build.test.js. This file executes the production build script (scripts/build.js) and validates that all provider-specific output directories are created in dist/ without runtime errors.

Are the transformer tests isolated from the filesystem?

No, the tests run against the actual filesystem. This approach validates real file I/O operations, path resolution, and permission handling, ensuring the transformers work correctly in real-world scenarios rather than mocked environments.

What assertions does Impeccable use for validation?

The test suite uses Bun’s native assertion library (assert.equal, assert.deepEqual, assert.ok, etc.) rather than external frameworks like Jest or Mocha. This keeps the dependency footprint minimal while providing robust validation capabilities.

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