How to Run Tests for vorssaint-utils: Complete Guide

Build and execute the test suite using ./build.sh --test followed by ./.build/debug/VorssaintTests — the project does not support standard swift test due to macOS framework dependencies.

The vorssaint-utils repository provides a lightweight Swift utility library for metric formatting, disk helpers, and clipboard search operations. Because the codebase relies on macOS-only frameworks like IOKit and AppKit, it uses a custom test harness rather than Xcode's XCTest runner. This guide explains how to run tests for vorssaint-utils using the project's custom build system.

Why vorssaint-utils Uses a Custom Test Harness

Standard swift test cannot execute vorssaint-utils tests because the command-line tools bundled with Xcode cannot launch a full XCTest environment without a GUI. The project solves this limitation with a custom @main harness defined in Tests/MetricsTests.swift that runs as a standalone command-line executable with full assertion capabilities.

The test binary is intentionally stripped of heavy system extensions, producing a fast, deterministic test run that verifies core logic without launching the full application.

Prerequisites

Before running tests, ensure you have:

• macOS with Xcode Command Line Tools installed
• Git to clone the repository
• A terminal with access to swift and sh

Step-by-Step: Running Tests for vorssaint-utils

1. Clone the Repository

git clone https://github.com/vorssaint/vorssaint-utils.git
cd vorssaint-utils

2. Build the Test Binary

Execute the custom build script with the --test flag:

./build.sh --test

This script compiles a minimal, UI-free version of the app with optimized flags (-c, -O, -enable-testing) and outputs ./.build/debug/VorssaintTests.

3. Run the Test Binary

./.build/debug/VorssaintTests

The @main harness in Tests/MetricsTests.swift executes and reports results:

✔️ 56 checks passed, 0 failures

A non-zero exit status indicates assertion failures.

4. One-Line Command for CI

./build.sh --test && ./.build/debug/VorssaintTests

Key Source Files for Test Execution

File	Purpose
build.sh	Custom build script; --test flag creates the lightweight test executable
Tests/MetricsTests.swift	Contains the @main test harness and all unit-test functions
Package.swift	Swift package manifest defining targets used by build.sh
.github/workflows/ci.yml	CI workflow that runs identical test commands on every push

Working with Test Results

Check Exit Status Programmatically

if ./.build/debug/VorssaintTests; then
    echo "All tests passed ✅"
else
    echo "Some tests failed ❌"
fi

Capture Exit Code Directly

./.build/debug/VorssaintTests
echo $?  # 0 indicates success

CI Integration

The GitHub Actions workflow at .github/workflows/ci.yml uses the same commands documented above. You can replicate this in any CI system:

git clone https://github.com/vorssaint/vorssaint-utils.git
cd vorssaint-utils
./build.sh --test
./.build/debug/VorssaintTests

Summary

• vorssaint-utils cannot use swift test due to macOS framework dependencies (IOKit, AppKit)
• Use ./build.sh --test to compile the dedicated test binary at ./.build/debug/VorssaintTests
• The test harness in Tests/MetricsTests.swift runs as a @main executable with standard assertion output
• Exit code 0 indicates all tests passed; non-zero indicates failures
• The same workflow powers the project's GitHub Actions CI pipeline

Frequently Asked Questions

Why does swift test fail for vorssaint-utils?

The project depends on macOS-only frameworks that require a GUI environment. Xcode's command-line tools cannot launch XCTest without a graphical session. The custom @main harness in Tests/MetricsTests.swift bypasses this restriction while maintaining full test coverage.

What does the test binary actually verify?

The compiled test executable validates metric-formatting logic, disk-helper utilities, and clipboard-search operations. These are pure Swift implementations isolated from system framework dependencies to ensure deterministic, fast execution.

How do I add new tests to the harness?

Open Tests/MetricsTests.swift and add assertions to the existing @main structure. The file uses standard Swift assertion functions (assert(), precondition()) rather than XCTest APIs. Rebuild with ./build.sh --test to include your changes.

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