企业官网建设流程全解析

[Feature] Testing Scenarios

【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors

Quick Reference

• Links to reference documents

Testing Environment

• URLs, endpoints, prerequisites

Critical User Flows

Flow N: [Flow Name]

Scenario: Brief description

Prerequisites(if needed): What must be true before testing

Verify:

• Point 1
• Point 2

OR

Test Cases:

TCN.N: [Test Case Name]

Given: Initial conditionsWhen: User actionThen: Expected outcome (high-level)

以 [frontend/docs/testing/INSPECTOR.md](https://link.gitcode.com/i/78d2cccf5db5a99e1fd1a35407c7a8ab) 的实际落地为例，其 Quick Reference 一节即指向四份引用文档： - [Connection States Reference](https://link.gitcode.com/i/b4d2b692776bbbd2dcec5bcfa5bd3f9b) - [Error States Reference](https://link.gitcode.com/i/9c6dfa9e8e7fc07032949ed729e9a66f) - [Actor States Reference](https://link.gitcode.com/i/9ade8dab2e67ee125b50644df2091918) - [UI Components Reference](https://link.gitcode.com/i/0bae698385cd68dd6ba04a6f0b9a2349) Testing Environment 则明确：开发地址 `http://localhost:5173`、生产地址 `https://inspect.rivet.dev`、默认 RivetKit 端点 `http://localhost:6420`。 ### 2.2 引用文档模板 共享概念（如 Actor 状态机、连接状态、错误类型）沉淀为引用文档： ```markdown # [Topic] Reference ## [Category] ### [Item Name] **When**: Condition when this applies **User is informed about**: - Information point 1 - Information point 2 **Available actions**: - Action 1 - Action 2 **Displays** (optional): - UI element 1 - UI element 2

仓库references/目录下现有六份引用文档，正好构成一套完整的领域状态参考：actor-states.md、connection-states.md、error-states.md、integration-form.md、onboarding-states.md、ui-components.md。

三、写作风格：用动词时态与语义精确性提升可测性

规范对语言有四项硬性要求：

1. 使用现在时：写 "User is informed"，不写 "User will be informed"。
2. 保持简洁：避免不必要的词。
3. 精确表达意图：写 "User is informed about connection failure"，不写 "Show error"。
4. 避免实现细节：写 "Rivet Actor can be destroyed"，不写 "Click destroy button and confirm in dialog"。

3.1 三种语义化验证点

文档进一步把验证陈述收敛为三个固定短语，使手工测试与自动化用例能一一对应：

3.2 Scenario 与 Test Case 的选择

• Scenario用于高层用户流程、集成测试、多步骤过程；
• Test Case用于特定条件、边界情况、单个功能验证。

3.3 正反对照：规范中的典型示例

测试状态变化： ✅ 好："Rivet Actor state updates when changed; Events appear in real-time" ❌ 差："When actor state changes from {old} to {new}, the UI updates within 100ms showing the new state in JSON format"

测试错误处理： ✅ 好："When connection fails → User is informed about connection failure & possible reasons → Available actions: Retry connection" ❌ 差："Show red error banner with text 'Connection failed: ERR_CONNECTION_REFUSED...' and a 'Retry' button in blue"

测试用户操作： ✅ 好："Rivet Actor can be created; Rivet Actor appears in list after creation" ❌ 差：逐步点击 "+" 按钮、填写表单字段、等待 toast 的 5 步脚本

规范还给出了完整的 Good/Bad 场景对照：好场景描述"用户访问 inspector URL 而无 RivetKit 服务器时，显示入门卡片、连接表单（默认端点）、可输入自定义端点、提供 Connect 按钮"；坏场景则陷入"白底、蓝色按钮、hover 变深蓝"等样式细节——这些正是最易随 UI 改版而过期的信息。

四、命名约定：让测试 ID 自解释

这些 ID 约定在 frontend/docs/testing/INSPECTOR.md 中得到完整应用：Flow 1 下包含TC1.1（服务器不可用）、TC1.2（非 RivetKit 服务器）、TC1.3（本地网络访问未授权）、TC1.4（连接成功）四个用例，集成测试区则有I1（完整连接流程）、I2（Actor 生命周期）、I3（实时更新）、I4（多 Actor 管理），边界区包括E1（网络中断）、E2（RivetKit 重启）、E3（浏览器刷新）、E4（非法端点格式）、E5（CORS 错误）。

五、E2E 实现：从规范到 Playwright 代码

规范第四章给出了 E2E 自动化实现的具体指引，这也是从"文档规范"走向"可执行测试"的关键桥梁。

5.1 元素选择策略：data-testid 优先

1. 优先使用 test ID：通过data-testid属性做稳定元素选择，避免依赖 UI 文案。
   • ✅page.getByTestId("onboarding-path-agent")
   • ❌page.getByText("Use Coding Agent")
2. 按需为组件补充 test ID：缺失时手动添加，使用描述性 kebab-case 命名，如data-testid="onboarding-path-agent"。
3. 回退层级（无 test ID 时）：
   • getByRole()——面向可访问元素（按钮、链接、标题）
   • getByLabel()——表单输入
   • getByPlaceholder()——带占位符的输入
   • getByText()——最后手段，避免精确匹配

5.2 Test ID 命名约定与源码印证

命名格式为{feature}-{element}-{variant?}，规范示例：

• onboarding-path-agent——onboarding 中的 Agent 路径选项
• onboarding-path-template——模板路径选项
• onboarding-back-button——返回按钮
• template-card-chat-room——聊天室模板卡片

该约定在真实组件中已落地。以 frontend/src/components/onboarding/path-selection.tsx 为例，组件通过集中的TEST_IDS.Onboarding.PathSelection、PathSelectionAgent、PathSelectionManual常量注入data-testid，与规范中"描述性、kebab-case、按 feature 分层"的要求一一对应，保证测试选择器与 UI 文案解耦。

5.3 为组件添加 Test ID

// In the component <Button>await expect(page).toHaveScreenshot("onboarding-path-selection.png");

const card = page.getByTestId("onboarding-path-agent"); await expect(card).toHaveScreenshot("agent-card.png");

pnpm test:e2e --update-snapshots

【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors