NextUI 跨平台基础层 - 测试指南

测试环境准备

1. 构建项目

cd /Users/xuesong/work/Projects/nextui
dotnet build

2. 运行单元测试

dotnet test src/NextUI.Core.Tests/NextUI.Core.Tests.csproj --verbosity normal

预期结果: 24 个测试全部通过 ✅

测试场景

场景 1：纯 HTML 页面测试

1.1 打开示例页面

  1. 在浏览器中打开 docs/examples/standalone-html-example.html
  2. 如果路径问题，可以：
    • 使用本地服务器（如 python3 -m http.server）
    • 或调整 HTML 中的 CSS/JS 路径

1.2 验证功能

主题色测试:

  • 改变颜色选择器，调色板（P50-P900）应该立即更新
  • 选择预设颜色，调色板应该更新
  • 刷新页面，颜色应该从 localStorage 恢复

字体缩放测试:

  • 拖动滑块，所有文本大小应该按比例变化
  • 点击预设按钮（Small/Normal/Large），字体应该相应变化
  • 刷新页面，字体缩放应该从 localStorage 恢复

主题模式测试:

  • 点击 "Light" 按钮，页面应该切换到浅色主题
  • 点击 "Dark" 按钮，页面应该切换到深色主题
  • 点击 "System" 按钮，页面应该跟随系统主题
  • 刷新页面，主题模式应该从 localStorage 恢复

语言测试:

  • 选择不同语言，document.documentElement.lang 应该更新
  • 刷新页面，语言应该从 localStorage 恢复

跨标签页同步测试:

  • 在一个标签页修改主题色
  • 在另一个标签页打开相同页面
  • 两个标签页的主题应该同步（通过 localStorage 事件）

场景 2：Blazor 应用测试（Workbench）

2.1 集成 SxThemeProvider

在 workbench/NextUI.Workbench/App.razor 中添加：

@namespace NextUI.Workbench

<SxThemeProvider />
<SxErrorBoundary>
    <Router AppAssembly="@typeof(App).Assembly" NotFoundPage="typeof(Pages.NotFound)">
        <Found Context="routeData">
            <RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)"/>
            <FocusOnNavigate RouteData="@routeData" Selector="h1" />
        </Found>
    </Router>
</SxErrorBoundary>

2.2 验证功能

基础功能:

  • 应用启动时，主题应该从 localStorage 加载并应用
  • 检查浏览器控制台，不应该有 JS 错误
  • 检查 DevTools -> Elements -> :root，应该看到 CSS 变量被注入：
    • --sx-primary-50 到 --sx-primary-900
    • --sx-font-scale
    • --sx-locale

与 C# 状态同步（如果提供了 ThemeState/LocaleState）:

  • 在 C# 代码中调用 ThemeState.SetPrimarySeedHex("#FF5733")
  • CSS 变量应该立即更新
  • 在 C# 代码中调用 ThemeState.SetFontScale(1.2)
  • 页面字体应该立即放大

跨平台一致性:

  • 在 Blazor 应用中修改主题色
  • 在纯 HTML 页面中打开，应该看到相同的主题色
  • 反之亦然（通过 localStorage 同步）

场景 3：单元测试验证

运行测试套件：

dotnet test src/NextUI.Core.Tests/NextUI.Core.Tests.csproj --verbosity normal

验证点:

  • 所有 24 个测试通过
  • ThemeState 颜色算法测试通过
  • CSS 变量语法验证测试通过

已知问题与限制

当前限制

  1. JS 模块路径: theme-runtime.js 当前从 wwwroot/js/ 加载，生产环境可能需要调整路径
  2. 服务注册: IThemeState 和 ILocaleState 如果未注册为服务，SxThemeProvider 仍可工作，但不会同步 C# 状态变化
  3. 静态资源分发: NextUI.Tokens/Exports/ 中的文件在生产环境（NuGet 包）中的访问路径需要确认

待验证

  • 在 Workbench 中实际运行并测试 SxThemeProvider
  • 验证 JS 模块导入路径是否正确
  • 验证 C# 状态同步是否正常工作（如果提供了服务）

故障排查

问题 1: JS 模块加载失败

症状: 控制台错误 "Failed to load ThemeRuntime"

解决方案:

  1. 检查 theme-runtime.js 文件是否存在
  2. 检查路径是否正确（开发环境 vs 生产环境）
  3. 检查浏览器控制台的网络请求，确认文件是否被正确加载

问题 2: CSS 变量未更新

症状: 修改主题色后，页面颜色不变

解决方案:

  1. 检查浏览器 DevTools -> Elements -> :root，查看 CSS 变量是否被注入
  2. 检查控制台是否有 JS 错误
  3. 检查 localStorage 中是否有对应的键值

问题 3: C# 状态不同步

症状: 在 C# 中修改 ThemeState，CSS 未更新

解决方案:

  1. 确认 SxThemeProvider 的 ThemeState 参数是否提供
  2. 确认 ThemeState.Changed 事件是否触发
  3. 检查控制台是否有 JSInterop 错误

测试检查清单

功能完整性

  • CSS 变量扩展完成
  • JS 运行时实现完成
  • Blazor 桥接组件完成
  • 单元测试全部通过
  • HTML 示例页面创建
  • Workbench 集成测试（待实际运行）
  • 跨平台一致性验证（待实际测试）

文档完整性

  • 方案文档更新
  • DesignTokens.md 同步更新
  • SxThemeProvider 组件文档
  • HTML 示例页面
  • 测试指南（本文档）

测试完成后，请更新本文档，标记已完成的测试项。