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

Run ./build/Vorssaint --selftest after building the project with ./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. 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, 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:

./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:

./build/Vorssaint --selftest

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

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 and .github/workflows/release.yml.

A typical CI step looks like this:

- 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 to verify sensors, preferences, UI assets, and configuration files.
• It is available only in development builds created by ./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 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 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 and .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.

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