# How to Run Tests for vorssaint-utils: Complete Guide

> Learn how to run tests for vorssaint-utils by executing ./build.sh --test and ./ .build/debug/VorssaintTests. Discover why swift test is not supported due to macOS framework dependencies.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: how-to-guide
- Published: 2026-09-05

---

**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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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

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

```bash
./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

```bash
./.build/debug/VorssaintTests

```

The `@main` harness in [`Tests/MetricsTests.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/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

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

```

## Key Source Files for Test Execution

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

## Working with Test Results

### Check Exit Status Programmatically

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

```

### Capture Exit Code Directly

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

```

## CI Integration

The **GitHub Actions workflow** at [`.github/workflows/ci.yml`](https://github.com/vorssaint/vorssaint-utils/blob/main/.github/workflows/ci.yml) uses the same commands documented above. You can replicate this in any CI system:

```bash
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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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.