# How to Use the --selftest Flag in Vorssaint-Utils: A Complete Guide

> Master the --selftest flag in Vorssaint-Utils. Run a diagnostic health check for sensors, preferences, and UI assets after building. Learn success and failure exit codes.

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

---

**Run `./build/Vorssaint --selftest` after building the project with [`./build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/./build.sh) to execute a diagnostic health-check of sensor detection, preference handling, and core UI assets, exiting with code 0 on success or a non-zero code on failure.**

The `--selftest` flag provides a built-in diagnostic mechanism in the **vorssaint/vorssaint-utils** repository that validates critical subsystems before deployment. This command-line option executes the `SelfTest` routine to ensure your development build is healthy. Learning how to use the `--selftest` flag in Vorssaint-Utils helps developers catch configuration errors early in both local environments and continuous integration pipelines.

## What the --selftest Flag Does

When you append `--selftest` to the binary, the program invokes the **SelfTest** routine defined in [`Sources/Vorssaint/Support/SelfTest.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Support/SelfTest.swift). This routine probes four critical components:

- **Sensor detection** (`--sensors`) – Validates hardware interface availability
- **Preference handling** – Ensures user defaults and settings storage function correctly
- **Core UI assets consistency** – Verifies that bundled resources are intact and accessible
- **Internal configuration validation** – Confirms that internal plist and JSON configs parse without errors

According to the source code in [`Sources/Vorssaint/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift), the entry point checks for this flag at launch and immediately dispatches execution to the SelfTest module, bypassing normal application flow.

## Prerequisites: Development Builds Only

The `--selftest` flag is **deliberately excluded** from shipped production apps to keep the release bundle lean. It is only available in development builds produced by the repository's build script.

You must first compile the binary using the provided build pipeline:

```bash
./build.sh

```

This script generates the `Vorssaint` executable in the `build/` directory. Only this development artifact recognizes the `--selftest` argument.

## Running the Self-Test Locally

After building, execute the diagnostic routine by running the binary with the flag:

```bash
./build/Vorssaint --selftest

```

If all subsystems pass validation, the program prints a short confirmation message and terminates:

```text
SELFTEST OK

```

The process exits with status code **0**, indicating a healthy build. If any check fails—such as missing sensor permissions or corrupted asset catalogs—the routine reports the offending component to stderr and returns a **non-zero exit code**, enabling immediate detection of environment issues.

## Integrating with CI/CD Pipelines

The `--selftest` flag is designed for automated validation in GitHub Actions workflows. The repository includes pre-configured pipeline steps in [`.github/workflows/ci.yml`](https://github.com/vorssaint/vorssaint-utils/blob/main/.github/workflows/ci.yml) and [`.github/workflows/release.yml`](https://github.com/vorssaint/vorssaint-utils/blob/main/.github/workflows/release.yml).

A typical CI step looks like this:

```yaml
- name: Build & selftest
  run: |
    ./build.sh
    ./build/Vorssaint --selftest

```

Because the self-test returns a non-zero exit code on failure, the workflow automatically aborts if the build artifact is unhealthy. This prevents defective releases from reaching production, as the release workflow validates the binary with `--selftest` before publishing artifacts.

## Summary

- The `--selftest` flag runs comprehensive diagnostics via [`Sources/Vorssaint/Support/SelfTest.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Support/SelfTest.swift) to verify sensors, preferences, UI assets, and configuration files.
- It is available **only** in development builds created by [`./build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/./build.sh), not in production releases.
- Successful execution prints "SELFTEST OK" and exits with code 0; failures return non-zero codes suitable for CI failure detection.
- Integration with [`.github/workflows/ci.yml`](https://github.com/vorssaint/vorssaint-utils/blob/main/.github/workflows/ci.yml) ensures automated health checks block faulty deployments.

## Frequently Asked Questions

### Is the --selftest flag available in production builds?

No. According to the repository design, the flag is stripped from shipped applications to minimize bundle size. It exists only in binaries compiled via [`./build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/./build.sh) in development environments or CI systems.

### What specific checks does the self-test perform?

The routine validates **sensor detection**, **preference handling**, **core UI assets consistency**, and **internal configuration validation**. These checks ensure the binary can access hardware interfaces, read user settings, load graphical resources, and parse internal configuration files without errors.

### How do I integrate the self-test into my GitHub Actions workflow?

Add a step after your build command that runs `./build/Vorssaint --selftest`. The non-zero exit code on failure will automatically halt the workflow, preventing the deployment of defective builds. The repository provides working examples in [`.github/workflows/ci.yml`](https://github.com/vorssaint/vorssaint-utils/blob/main/.github/workflows/ci.yml) and [`.github/workflows/release.yml`](https://github.com/vorssaint/vorssaint-utils/blob/main/.github/workflows/release.yml).

### What does the exit code indicate?

An exit code of **0** indicates that all diagnostic checks passed successfully. Any **non-zero exit code** signals that one or more subsystems failed validation, with details about the specific component written to stderr.