Testing and Guardrails

Testing and Guardrails

Forsetti uses tests and scripts to keep runtime behavior and architecture boundaries stable.

Verification Stack

flowchart TD
    Change["Code or documentation change"] --> Unit["swift test"]
    Change --> Guardrails["Scripts/verify-forsetti-guardrails.sh"]
    Guardrails --> Package["Package dependency graph checks"]
    Guardrails --> Imports["Import boundary checks"]
    Guardrails --> Final["Final class checks"]
    Change --> Lint["SwiftLint when available"]
    Unit --> Result["Merge-ready signal"]
    Guardrails --> Result
    Lint --> Result

Loading

Test Targets

Target	Coverage
ForsettiCoreTests	SemVer, manifest loading, compatibility, activation lifecycle, entitlements, UI surface manager, module communication, and logging.
ForsettiPlatformTests	StoreKit provider behavior and entitlement provider factory behavior.
ForsettiHostTemplateTests	Host controller boot, module lists, locked modules, restore purchases, service toggles, UI selection, and toolbar routing.
ForsettiArchitectureTests	Package graph, import rules, internal layering, and final class expectations.

Core Commands

swift test
Scripts/verify-forsetti-guardrails.sh

Run both before pushing runtime or package-boundary changes.

CI Workflows

Workflow	Purpose
guardrails.yml	Runs package tests and repository guardrails.
lint-pr.yml	Validates pull request titles against conventional commit-style formats.
release-please.yml	Maintains release PRs, changelog, and version files.

Wiki publishing is now manual through the GitHub Wiki repository so the wiki cannot be overwritten by generated source pages.

Guardrail Logic

flowchart LR
    Files["Repository files"] --> Package["Package.swift graph"]
    Files --> Source["Sources imports"]
    Files --> Tests["Tests imports"]
    Package --> Rules{"Expected layering?"}
    Source --> Rules
    Tests --> Rules
    Rules -- yes --> Pass["Pass"]
    Rules -- no --> Fail["Fail with exact violation"]

Loading

Pre-Merge Quality Bar

• New runtime behavior has unit tests.
• New host controller behavior has host-template tests.
• New platform behavior has platform tests or a documented platform limitation.
• Architecture-affecting changes pass guardrail scripts.
• Manifests and module examples remain aligned with current schema.
• Documentation updates accompany behavior changes.