FOSMVVM ViewModel 测试生成器

依据 FOSMVVM 测试模式，为 ViewModel 生成测试文件。

概念基础

如需完整架构背景，请参阅 FOSMVVMArchitecture.md｜OpenClaw 参考文档

FOSMVVM 中的 ViewModel 测试需验证以下三个关键方面：

1. Codable 往返序列化 — ViewModel 编码与解码过程中不丢失数据
2. 版本稳定性 — ViewModel 结构未发生意外变更
3. 多语言本地化支持 — 所有 @LocalizedString 属性在所有受支持的语言环境中均具备对应值

LocalizableTestCase 协议提供了基础设施，可在单次调用中完成上述三项验证。

何时使用本技能

• 为新 ViewModel 创建测试
• 为已有 ViewModel 补充测试覆盖率
• 校验各语言环境下的本地化完整性
• 测试包含嵌套子 ViewModel 的 ViewModel
• 验证 @LocalizedSubs 替换行为

本技能生成的内容

测试模式

标准模式（适用于大多数测试）

对绝大多数 ViewModel，仅需一行代码即可实现完整覆盖：

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

该调用将验证：

• Codable 编码/解码能力
• 带版本控制的 ViewModel 稳定性
• 所有语言环境（默认为 en、es）均存在对应翻译

该方式足以满足绝大多数 ViewModel 测试需求。

扩展模式（用于特定格式行为验证）

当需测试特定格式行为（如替换、复合字符串）时，可添加语言环境专属断言：

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

    // 验证特定替换行为
    let vm: GreetingViewModel = try .stub()
        .toJSON(encoder: encoder(locale: en))
        .fromJSON()

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

此为可选操作，仅在需要验证特定格式技术时使用。

LocalizableTestCase 协议

测试套件需遵循 LocalizableTestCase 协议以接入测试基础设施：

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: ""
        )
    }
}

{ViewModelsTarget}.resourceAccess 是在创建 ViewModels SPM target 时（通过 FOSResourceAccessor 构建工具插件）定义的资源访问器。

LocalizableTestCase 提供的能力

测试方法

YAML 要求

含 @LocalizedString 的 ViewModel

每个含 @LocalizedString 属性的 ViewModel 均需提供 YAML 条目：

@ViewModel
public struct DashboardViewModel: RequestableViewModel {
    @LocalizedString public var pageTitle      // 需要 YAML 条目
    @LocalizedString public var emptyMessage   // 需要 YAML 条目
    public let itemCount: Int                   // 无需 YAML
}

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

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

嵌套 ViewModel

当 ViewModel 包含子 ViewModel 时，整个层级中的所有类型均需提供 YAML 条目：

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

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

BoardViewModel 与 CardViewModel 均需 YAML 条目（可置于同一文件或独立文件中）。

私有测试 ViewModel

若测试文件中定义了用于特定场景的私有 ViewModel 结构体，则这些类型同样需要 YAML 条目：

// 在测试文件中
private struct TestParentViewModel: ViewModel {
    @LocalizedString var title
    let children: [TestChildViewModel]
}

private struct TestChildViewModel: ViewModel {
    @LocalizedString var label
}

请为这些私有类型在测试专用 YAML 文件中添加对应条目。

如何使用本技能

调用方式：
/fosmvvm-viewmodel-test-generator

前置条件：

• 已从对话上下文中理解 ViewModel 结构
• 已识别本地化属性（@LocalizedString、@LocalizedSubs 等）
• YAML 本地化文件已存在或即将创建
• 已识别子 ViewModel（如有）

工作流集成：
本技能在为 ViewModel 补充测试覆盖率时使用。技能会自动引用对话上下文 —— 无需提供文件路径或问答交互。通常紧随 fosmvvm-viewmodel-generator 使用。

模式实现

本技能通过引用对话上下文确定测试结构：

ViewModel 分析

根据对话上下文，技能识别出：

• 待测试的 ViewModel（来自先前讨论或代码库）
• 本地化需求（@LocalizedString 属性）
• 子 ViewModel（嵌套于父 ViewModel 内）
• 替换行为（需特别验证的 @LocalizedSubs）

YAML 覆盖度检查

校验完整性：

• ViewModel YAML 条目（所有 @LocalizedString 属性）
• 子 ViewModel 条目（嵌套类型）
• 语言环境覆盖度（en、es 或项目指定语言环境）

测试文件生成

生成包含以下内容的测试套件：

• 遵循 LocalizableTestCase 协议
• 初始化本地化存储对象
• 为每个 ViewModel 调用 expectFullViewModelTests()
• 可选：针对特定格式（替换、复合字符串）的专项测试

上下文来源

技能参考的信息来源包括：

• 先前对话：已讨论或近期创建的 ViewModel
• ViewModel 代码：若 Claude 已将 ViewModel 文件载入上下文
• YAML 文件：基于代码库中现有本地化文件的分析结果
• 测试模式：基于项目中现有测试文件的分析结果

文件模板

完整文件模板详见 reference.md。

常见场景

测试单一顶层 ViewModel

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

测试多个关联 ViewModel

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

使用自定义语言环境测试

var locales: Set { [en, es, enGB] }  // 覆盖默认设置

@Test func multiLocaleViewModel() throws {
    try expectFullViewModelTests(MyViewModel.self)
    // 将测试 en、es 和 en-GB
}

测试替换行为

@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!")
}

测试嵌套 ViewModel

@Test func parentWithChildren() throws {
    // 测试父 ViewModel 并验证子 ViewModel 可被编码/解码
    try expectFullViewModelTests(ParentViewModel.self)

    // 可选：验证特定子项值
    let vm: ParentViewModel = try .stub()
        .toJSON(encoder: encoder(locale: en))
        .fromJSON()

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

故障排查

“缺少翻译”错误

FOSLocalizableError: _pageTitle -- Missing Translation -- en

原因：@LocalizedString 属性缺失 YAML 条目。

修复：在 YAML 文件中添加该属性：

en:
  MyViewModel:
    pageTitle: "Page Title"  # 添加此项

“正在等待本地化”错误

原因：ViewModel 未使用支持本地化的 encoder 进行编码。

修复：确保使用 encoder(locale:) 或 expectFullViewModelTests()。

测试通过但翻译内容异常

原因：YAML 值虽存在，但可能存在拼写错误或内容错误。

修复：添加精确值断言进行校验：

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

命名规范

另请参阅

• FOSMVVMArchitecture.md — 测试支持 — 架构概览
• fosmvvm-viewmodel-generator — 用于创建 ViewModel
• fosmvvm-fields-generator — 用于表单验证测试
• reference.md — 完整文件模板

版本历史