sorcha-ui

用途

Sorcha UI 开发技能面向 Sorcha.UI 的测试驱动式 UI 开发。其核心约定是：每一次页面构建或修改，都必须配套编写 Playwright 端到端测试，测试运行在 Docker 环境之上，并自动校验控制台错误、网络失败、MudBlazor CSS 健康状态，同时在失败时截图。

前置条件

需要 Docker 处于运行状态并启动全部服务：

docker-compose up -d

UI 位于 http://localhost:5400 | API Gateway 位于 http://localhost:80

登录：admin@sorcha.local / Dev_Pass_2025!

主要能力与工作流

构建页面的标准流程按顺序分为五步。

第 1 步：创建 Page Object

在 tests/Sorcha.UI.E2E.Tests/PageObjects/{PageName}Page.cs 创建页面对象，封装选择器与操作。示例中定义了 WalletListPage 类，使用 data-testid 作为首选选择器策略，并以 MudBlazor 类选择器作为回退，提供 NavigateAsync、GetWalletCountAsync、IsEmptyStateVisibleAsync 等方法。

第 2 步：编写 Playwright 测试（测试先行）

在 tests/Sorcha.UI.E2E.Tests/Docker/{Feature}Tests.cs 创建测试。示例 WalletListTests 继承 AuthenticatedDockerTestBase，使用 [Parallelizable(ParallelScope.Self)]、[TestFixture] 及 Category 标签（Docker、Wallets、Authenticated），包含加载无错误、显示空状态或钱包列表等测试用例，基类会自动检查控制台错误、网络 5xx 与 CSS 健康状态。

第 3 步：构建 Blazor 页面

编辑 src/Apps/Sorcha.UI/Sorcha.UI.Web.Client/Pages/{Page}.razor。示例展示了带 @page、@layout、@rendermode、@attribute [Authorize]、@inject HttpClient 的 Razor 页面，使用 MudProgressCircular、MudAlert、MudCard、MudButton 等 MudBlazor 组件，并为关键元素添加 data-testid。

第 4 步：运行测试

运行刚构建功能的测试

dotnet test tests/Sorcha.UI.E2E.Tests --filter "Category=Wallets"

运行全部冒烟测试（快速 CI 门禁）

dotnet test tests/Sorcha.UI.E2E.Tests --filter "Category=Smoke"

运行全部 Docker 测试

dotnet test tests/Sorcha.UI.E2E.Tests --filter "Category=Docker"

第 5 步：失败时检查产物

任何测试失败时，截图保存到 tests/Sorcha.UI.E2E.Tests/bin/Debug/net10.0/screenshots/。控制台错误与网络失败会在测试输出中报告。

关键概念

DockerTestBase：未认证测试，自动捕获错误，位于 Infrastructure/DockerTestBase.cs。
AuthenticatedDockerTestBase：登录一次，跨测试复用认证状态，位于 Infrastructure/AuthenticatedDockerTestBase.cs。
TestConstants：URL、凭据、路由、超时，位于 Infrastructure/TestConstants.cs。
Page Objects：按页面封装选择器与操作，位于 PageObjects/*.cs。
MudBlazorHelpers：共享 MudBlazor 定位器与布局校验，位于 PageObjects/Shared/MudBlazorHelpers.cs。
data-testid：首选选择器策略，用于提升测试韧性，添加在 Razor 组件中。
Categories：按功能或关注点过滤测试，如测试类上的 [Category("Wallets")]。

测试继承结构

PageTest (Playwright NUnit) └── DockerTestBase (控制台错误、网络失败、截图) ├── ComponentHealthTests, LoginTests (未认证) └── AuthenticatedDockerTestBase (登录一次、复用状态、布局健康) ├── DashboardTests ├── NavigationTests ├── WalletTests └── ... (每个功能区域一个)

测试分类

Smoke：所有页面加载、无 JS 错误，用于 CI 门禁。
Docker：所有针对 Docker 的测试，用于完整 Docker 套件。
Auth：登录、登出、重定向，用于认证功能。
Authenticated：所有需要登录的测试，用于登录后功能。
Dashboard：仪表盘页面。
Navigation：抽屉、应用栏、路由，用于布局变更。
Components：CSS、MudBlazor、响应式，用于样式/组件变更。
Wallets：钱包页面。
Blueprints：蓝图页面。
Registers：注册表页面。
Schemas：Schema 库。
Admin：管理页面。

文件位置

Blazor 页面：src/Apps/Sorcha.UI/Sorcha.UI.Web.Client/Pages/
共享组件：src/Apps/Sorcha.UI/Sorcha.UI.Core/
布局：src/Apps/Sorcha.UI/Sorcha.UI.Web.Client/Components/Layout/
测试基础设施：tests/Sorcha.UI.E2E.Tests/Infrastructure/
页面对象：tests/Sorcha.UI.E2E.Tests/PageObjects/
Docker 测试：tests/Sorcha.UI.E2E.Tests/Docker/
MudBlazor 辅助：tests/Sorcha.UI.E2E.Tests/PageObjects/Shared/MudBlazorHelpers.cs

文档资源

可使用 Context7 获取最新的 Playwright .NET 与 MudBlazor 文档。库 ID：/websites/playwright_dev_dotnet（Playwright .NET）、/websites/mudblazor（MudBlazor 组件库）。推荐查询："Locators selectors data-testid"、"NUnit test fixtures parallel"、"MudBlazor card table dialog"、"MudBlazor form validation"、"Browser storage state authentication"。

限制

资料未提供该技能的收费、价格、平台支持范围或性能效果等信息。

技能介绍

用途