​

Quickstart Guide

​

Prerequisites

• Xcode 15.0+
• Swift 5.9+
• iOS 17+ or macOS 14+ project with SwiftData
• Git repository (for tracking fixtures)
• npm (for CLI installation)
• Apple Silicon Mac (Intel users must build from source)

​

Install CLI

npm install -g @trinsicventures/freezeray

freezeray --version

​

Initialize Your Project

cd YourProject
freezeray init

• Add FreezeRay package dependency to your Package.swift
• Create the FreezeRay/ directory structure
• Set up .gitignore rules (if needed)

​

Annotate Your Schema

import SwiftData
import FreezeRay

@FreezeSchema(version: "1.0.0")
enum AppSchemaV1: VersionedSchema {
    static var versionIdentifier = Schema.Version(1, 0, 0)

    static var models: [any PersistentModel.Type] {
        [User.self]
    }

    @Model
    final class User {
        var name: String
        var email: String

        init(name: String, email: String) {
            self.name = name
            self.email = email
        }
    }
}

​

Freeze Your Schema

freezeray freeze 1.0.0

1. Build your project
2. Run tests in iOS Simulator
3. Extract schema fixtures to FreezeRay/Fixtures/1.0.0/
4. Generate validation tests in FreezeRay/Tests/

​

Verify the Freeze

ls FreezeRay/Fixtures/1.0.0/

• App-1_0_0.sqlite - SQLite database with schema
• schema-1_0_0.json - JSON representation
• export_metadata.txt - Metadata about the freeze

​

Commit the Fixtures

git add FreezeRay/
git commit -m "Freeze schema v1.0.0"

​

Run Tests

xcodebuild test -scheme YourApp -destination 'platform=iOS Simulator,name=iPhone 15'

• Verify the schema hasn’t drifted from the frozen version
• Validate that all models match the fixtures

​

Next Steps