Fosmvvm Viewmodel Test Generator

FOSMVVM ViewModel Test Generator

Read shared/functional-discipline.md before proceeding. Every rule below derives from it.

Generate test files for ViewModels following FOSMVVM testing patterns.

Conceptual Foundation

For full architecture context, see FOSMVVMArchitecture.md | OpenClaw reference

API catalog: check ../shared/api-catalog/FOSTesting.md § FOSTesting before hand-writing helpers.

ViewModel testing in FOSMVVM verifies three critical aspects:

1. Codable round-trip - ViewModel encodes and decodes without data loss
2. Versioning stability - Structure hasn't changed unexpectedly
3. Multi-locale translations - All @LocalizedString properties have values in all supported locales

The LocalizableTestCase protocol provides infrastructure that tests all three in a single call.

The version baseline is a COMMITTED artifact (in a downstream app). Versioning stability works by comparing the ViewModel's current serialization against a stored baseline JSON ({Name}ViewModel_<version>.json, written beside the test under Tests/.../.VersionedTestJSON/). For an app that ships a versioned wire contract to real clients, commit that baseline to git — it is the canary that catches an accidental wire-shape change across builds. If it isn't committed, it regenerates fresh every clean build and silently protects nothing. (Different policy for FOSUtilities itself: its own baselines are regenerable fixtures with no shipped contract — the version tags are arbitrary — so FOS deliberately git-ignores them except one intentional serialization canary. Downstream apps are the opposite: commit real baselines.) The primary expectFullViewModelTests(_:) now forwards #filePath/#line, so the baseline lands beside your test (under Tests/.../.VersionedTestJSON/) automatically — commit that file.

When to Use This Skill

• Creating tests for new ViewModels
• Adding test coverage to existing ViewModels
• Verifying localization completeness across locales
• Testing ViewModels with embedded/nested child ViewModels
• Verifying @LocalizedSubs substitution behavior

What This Skill Generates

The Testing Pattern

Standard Pattern (Most Tests)

For most ViewModels, a single line provides complete coverage:

@Test func dashboardViewModel() throws {
    try expectFullViewModelTests(DashboardViewModel.self)
}

This verifies:

• Codable encoding/decoding
• Versioned ViewModel stability
• Translations exist for all locales (en, es by default)

This is sufficient for the vast majority of ViewModel tests.

Extended Pattern (Specific Formatting Verification)

When testing specific formatting behavior (substitutions, compound strings), add locale-specific assertions:

@Test func greetingWithSubstitution() throws {
    try expectFullViewModelTests(GreetingViewModel.self)

    // Verify specific substitution behavior
    let vm: GreetingViewModel = try .stub()
        .toJSON(encoder: encoder(locale: en))
        .fromJSON()

    #expect(try vm.welcomeMessage.localizedString == "Welcome, John!")
}

This is optional - use only when verifying specific formatting techniques.

Child ViewModels Need Their Own Tests

A parent's round-trip carries its children, so their Codable conformance is covered. Their translations are not.

expectTranslations walks a single level — Mirror(reflecting: model), inspecting only children castable to any Localizable or _LocalizedProperty. A [ChildViewModel] is neither (there is no Array: Localizable conformance), and so is a single nested ViewModel property. Both are skipped, with no recursion. Encoding does not catch it either: a missing translation resolves to "" rather than throwing.

So a child ViewModel with any localized property gets its own test:

@Test func secretViewModel() throws {
    try expectFullViewModelTests(SecretViewModel.self)   // the child, on its own
}

Testing only the parent leaves every child's YAML unverified in every locale, and it fails silently — the suite stays green while the Spanish build ships English.

Testing Discipline: Contract, Not Representation

The expect* helpers verify behavior the contract guarantees — Codable round-trip, version stability, translations exist. Keep any added assertions at that same altitude. (Background: Architecture Patterns → Encapsulation Is the Precondition; repo CLAUDE.md → Encapsulation Is the Precondition SOLID Assumes.)

• Never assert the encoded representation. Don't inspect the raw JSON for specific keys/shape (obj["someKey"], "encodes as a bare string", exact byte layout, key order). There is no contract that a type encodes a particular way — only that it round-trips. Assert round-trip identity-preservation and behavior, never the shape. A representation assertion freezes an implementation detail and breaks on a harmless format change.
• Construct values the intended way; don't bypass a type's construction contract. Build instances with .stub(), public inits, and the try value.toJSON(encoder:).fromJSON() round-trip. @testable import here exists to see internal ViewModel types and test infrastructure — it is not a license to reach a value's private/internal init or getter to fabricate or inspect state the public contract doesn't offer. @testable/private access is legitimate only for block/arc coverage, never for contract coverage. If a value type seals its backing (no public accessor), assert via == / hashValue / Comparable, not by reading internals.
• expectVersionedViewModel is decode-only — never "regenerate" baselines to make a change pass. It writes a baseline once (if absent), then only re-decodes every committed version to prove old encodings still load; it does not encode-diff, and it skips ClientHostedViewModelFactory types. So a schema change must stay backward-decodable (add fields, don't rename/remove). Deleting the committed .VersionedTestJSON files to "refresh" them destroys the historical versions that are the entire point — don't. New fields are additive; old baselines must keep decoding.
• Date precision gotcha. FOSMVVM's canonical date format is millisecond precision, so a freshly-created Date/timestamp is not equal to itself after a round-trip (sub-ms is truncated). Don't assert in-memory Date equality across encode→decode; compare via behavior/ordering, or start from an already-canonical fixture.

LocalizableTestCase Protocol

Test suites conform to LocalizableTestCase to access testing infrastructure:

import FOSFoundation
@testable import FOSMVVM
import FOSTesting
import Foundation
import Testing
@testable import {ViewModelsTarget}

@Suite("My ViewModel Tests")
struct MyViewModelTests: LocalizableTestCase {
    let locStore: LocalizationStore

    init() throws {
        self.locStore = try Self.loadLocalizationStore(
            bundle: {ViewModelsTarget}.resourceAccess,
            resourceDirectoryName: ""
        )
    }
}

The {ViewModelsTarget}.resourceAccess is the resource accessor defined when creating the ViewModels SPM target (via FOSResourceAccessor build tool plugin).

What LocalizableTestCase Provides

Testing Methods

YAML Requirements

ViewModels with @LocalizedString

Every ViewModel with @LocalizedString properties needs YAML entries:

@ViewModel
public struct DashboardViewModel: RequestableViewModel {
    @LocalizedString public var pageTitle      // Needs YAML entry
    @LocalizedString public var emptyMessage   // Needs YAML entry
    public let itemCount: Int                   // No YAML needed
}

# DashboardViewModel.yml
en:
  DashboardViewModel:
    pageTitle: "Dashboard"
    emptyMessage: "No items yet"

es:
  DashboardViewModel:
    pageTitle: "Tablero"
    emptyMessage: "No hay elementos todavía"

Embedded ViewModels

When a ViewModel contains child ViewModels, all types in the hierarchy need YAML entries:

@ViewModel
public struct BoardViewModel: RequestableViewModel {
    @LocalizedString public var title
    public let cards: [CardViewModel]  // Child ViewModel
}

@ViewModel
public struct CardViewModel {
    @LocalizedString public var cardTitle
}

Both BoardViewModel and CardViewModel need YAML entries (can be in same or separate files).

Private Test ViewModels

When tests define private ViewModel structs for testing specific scenarios, those also need YAML:

// In test file
private struct TestParentViewModel: ViewModel {
    @LocalizedString var title
    let children: [TestChildViewModel]
}

private struct TestChildViewModel: ViewModel {
    @LocalizedString var label
}

Add entries to a test YAML file for these private types.

How to Use This Skill

Invocation: /fosmvvm-viewmodel-test-generator

Prerequisites:

• ViewModel structure understood from conversation context
• Localization properties identified (@LocalizedString, @LocalizedSubs, etc.)
• YAML localization files exist or will be created
• Child ViewModels identified (if any)

Workflow integration: This skill is used when adding test coverage for ViewModels. The skill references conversation context automatically—no file paths or Q&A needed. Typically follows fosmvvm-viewmodel-generator.

Pattern Implementation

This skill references conversation context to determine test structure:

ViewModel Analysis

From conversation context, the skill identifies:

• ViewModels to test (from prior discussion or codebase)
• Localization requirements (@LocalizedString properties)
• Child ViewModels (embedded within parent)
• Substitution behavior (@LocalizedSubs needing specific verification)

YAML Coverage Check

Verifies completeness:

• ViewModel YAML entries (all @LocalizedString properties)
• Child ViewModel entries (nested types)
• Locale coverage (en, es, or project-specific locales)

Test File Generation

Creates test suite with:

• LocalizableTestCase conformance
• Localization store initialization
• expectFullViewModelTests() calls for each ViewModel
• Optional specific formatting tests (substitutions, compound strings)

Context Sources

Skill references information from:

• Prior conversation: ViewModels discussed or recently created
• ViewModel code: If Claude has read ViewModel files into context
• YAML files: From codebase analysis of existing localizations
• Test patterns: From existing test files in project

File Templates

See reference.md for complete file templates.

Common Scenarios

Testing a Single Top-Level ViewModel

@Test func dashboardViewModel() throws {
    try expectFullViewModelTests(DashboardViewModel.self)
}

Testing Multiple Related ViewModels

@Test func boardViewModels() throws {
    try expectFullViewModelTests(BoardViewModel.self)
    try expectFullViewModelTests(ColumnViewModel.self)
    try expectFullViewModelTests(CardViewModel.self)
}

Testing with Custom Locales

var locales: Set<Locale> { [en, es, enGB] }  // Override default

@Test func multiLocaleViewModel() throws {
    try expectFullViewModelTests(MyViewModel.self)
    // Tests en, es, AND en-GB
}

Testing Substitution Behavior

@Test func greetingSubstitutions() throws {
    try expectFullViewModelTests(GreetingViewModel.self)

    let vm: GreetingViewModel = try .stub(userName: "Alice")
        .toJSON(encoder: encoder(locale: en))
        .fromJSON()

    #expect(try vm.welcomeMessage.localizedString == "Welcome, Alice!")
}

Testing Embedded ViewModels

@Test func parentWithChildren() throws {
    // Tests parent AND verifies children can be encoded/decoded
    try expectFullViewModelTests(ParentViewModel.self)

    // Optionally verify specific child values
    let vm: ParentViewModel = try .stub()
        .toJSON(encoder: encoder(locale: en))
        .fromJSON()

    #expect(try vm.children[0].label.localizedString == "Child 1")
}

Troubleshooting

"Missing Translation" Error

FOSLocalizableError: _pageTitle -- Missing Translation -- en

Cause: YAML entry missing for a @LocalizedString property.

Fix: Add the property to the YAML file:

en:
  MyViewModel:
    pageTitle: "Page Title"  # Add this

"Is pending localization" Error

Cause: The ViewModel wasn't encoded with a localizing encoder.

Fix: Ensure using encoder(locale:) or expectFullViewModelTests().

Test Passes But Translations Seem Wrong

Cause: YAML values exist but may have typos or wrong content.

Fix: Add specific assertions to verify exact values:

let vm = try .stub().toJSON(encoder: encoder(locale: en)).fromJSON()
#expect(try vm.title.localizedString == "Expected Value")

Parallelism and Shared State

Swift Testing runs suites — and the tests inside a suite — in parallel by default. A suite whose tests touch shared mutable state (a singleton, a static var, the process environment, a fixed-path fixture) carries .serialized; the classic race symptom is a recorded value asserting 0 because another test cleared the state in between. .serialized protects within the suite only — state spanning multiple suites needs a test-owned gate around the racing window, or dependency injection so the state stops being shared at all.

Naming Conventions

See Also

• FOSMVVMArchitecture.md - Testing Support - Architecture overview
• Architecture Patterns → Encapsulation Is the Precondition — test the contract, not the representation. A ViewModel test asserts behavior the contract guarantees (codable round-trip, version stability, correct localized projection, vmId equality/stability), never an incidental encoded shape, and never reaches into a sealed value's internals to assert them — that's the encapsulation break from the test side. Repo CLAUDE.md → Encapsulation Is the Precondition SOLID Assumes.
• fosmvvm-viewmodel-generator - For creating ViewModels
• fosmvvm-fields-generator - For form validation testing
• reference.md - Complete file templates

Version History