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

> Discover Impeccable's testing approach. Learn how they use Bun for unit tests on their build system and transformers to validate filesystem outputs and ensure correct artifact generation.

- Repository: [Paul Bakaus/impeccable](https://github.com/pbakaus/impeccable)
- Tags: testing
- Published: 2026-03-09

---

**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`](https://github.com/pbakaus/impeccable/blob/main/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`](https://github.com/pbakaus/impeccable/blob/main/tests/build.test.js) orchestrates the full build pipeline by executing [`scripts/build.js`](https://github.com/pbakaus/impeccable/blob/main/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`](https://github.com/pbakaus/impeccable/blob/main/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`](https://github.com/pbakaus/impeccable/blob/main/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`](https://github.com/pbakaus/impeccable/blob/main/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`](https://github.com/pbakaus/impeccable/blob/main/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`](https://github.com/pbakaus/impeccable/blob/main/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:

```bash
bun test

```

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

```text
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`](https://github.com/pbakaus/impeccable/blob/main/tests/lib/transformers/cursor.test.js) demonstrates how transformer logic is validated:

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

```js
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`](https://github.com/pbakaus/impeccable/blob/main/tests/build.test.js) validates the entire build pipeline by executing [`scripts/build.js`](https://github.com/pbakaus/impeccable/blob/main/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`](https://github.com/pbakaus/impeccable/blob/main/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`](https://github.com/pbakaus/impeccable/blob/main/tests/build.test.js). This file executes the production build script ([`scripts/build.js`](https://github.com/pbakaus/impeccable/blob/main/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.