xl1-testing

XL1 测试

用于测试和验证 XL1 工作的中心。它会引导你采用合适的验证方式，记录每种方式，并负责维护 dApp Definition of Done（完成定义），作为判定工作是否“完成”的关卡。请阅读此 SKILL 以选择合适的方式，然后打开链接的子文档，查看完整流程。

技能标识。 此技能的版本记录在本文件的 frontmatter 中的 metadata.version 字段。每当你提供计划、确认或完成摘要时，都要说明参考了哪些技能，格式为 <skill-name> v<version>——版本号须从本文件的 frontmatter 中读取，切勿使用示例中的版本号。如果同时启用了此插件中的多个技能，可以逐一列出。

技能层级

这是 XYO 技能栈的 第 7 层：xy-development（1）→ xy-toolchain（2）→ xyo-knowledge（3）→ xl1-knowledge（4）→ xl1-patterns（5）→ xl1-dapp-kit（6）→ xl1-testing（7）→ xl1-scaffold（8）→ xl1-build（9）。

• 基于： xl1-dapp-kit（6）——当项目使用 @xyo-network/dapp-kit* / xl1.dapp.json 时；xl1-patterns（5）——dApp Definition of Done 所检查的 dApp 模式和架构原则；xl1-knowledge（4）——待测试的链、网关、SDK 和网络端点；xyo-knowledge（3）——协议原语；ariestools-skills 中的 xy-toolchain 和 xy-development（1–2）——Vitest 布局、@ariestools/vitest-config、xy test / xy retest；测试和工作流约定，包括通用 Definition of Done
• 后续交接给： xl1-scaffold（8）——开始新的 XL1 项目时，它会从一开始就接入这些验证路径；xl1-build（9）——构建请求仍不明确时

dApp Definition of Done

在报告任何 XL1 dApp 工作已完成之前，必须执行。 此技能负责 dApp 完成关卡。这不是可选项，也不是“有空再做”——请逐项明确检查，并在完成摘要中针对相关部分注明通过或未通过。此清单列出了技能栈各处记录的规则和反模式（网关使用、datalake 设置、钱包集成、优先使用 SDK、载荷设计、索引器最低区块、提供方架构、显示约定、commit-reveal 正确性、结算权限方、多方共同签名、架构原则、dApp Kit、无头验证）。标记为“（如适用）”的部分，只有在确实不属于范围时才可跳过——请说明跳过了哪些部分以及原因。这是三级完成关卡中的第 2 关；第 1 关（xy-development 中的通用 DoD）始终适用；若存在 PRD.md，则第 3 关（PRD.md 验收标准）也适用。

⛔ 默认仅限测试网

除非有人明确、有意地针对某次运行选择主网，否则此处的所有流程都面向测试网（sequence 或 local 链）。

• 所有验证和测试默认使用 sequence 或 local。常规或自动化运行绝不可访问 xl1-mainnet / 真实 XL1。
• 种子和钱包密码均为机密——绝不可提交、记录或回显。
• 无人值守的 CLI 钱包流程会在操作系统密钥链中存储密码，并自动解锁；这属于热钱包，仅可用于没有价值的测试代币。完整防护措施请参阅其文档。

选择方案

你想要……	使用	签名者 / 执行者
在进程内证明 dApp 的链上交互在实时测试网上正常运行（Agent 式构建、CI 冒烟测试、回归测试）	无头测试网验证	通过 GatewayBuilder.buildRunner() 使用进程内助记词签名者
在免费、确定性的本地区块链上验证（离线、无需充值、速度快）	本地开发链验证	本地 xl1 start 链 + 进程内签名者（由创世区块注资的开发账户）
同上，但由 vitest 管理区块链（公共软件包）——适用于新的 dapp-kit / 公共使用者	通过 dApp Kit Vitest 使用本地区块链	@xyo-network/dapp-kit-vitest-config local-xl1（或供现有 spec/api-local 规范使用的公共 api-local 项目）+ 进程内签名者
使用同一个由 vitest 管理的区块链，但采用 XYO 内部受限测试框架	通过 apiLocal 使用本地区块链	@xyo-network/xl1-vitest-config apiLocal（受限）
同时测试本地 XL1 链和独立托管的 Aries 数据/对象湖，暂不运行真实 reducer	本地链 + Aries 数据湖测试夹具	直接使用 xl1 CLI + aries dapp CLI 和 noop 执行者
测试完整的本地 XL1 dApp 后端（classic 或 dapp-kit）	完整的本地 XL1 dApp 技术栈	Classic：aries-dapp-core。dapp-kit：xl1-dapp / 本地主机 + dapp-kit vitest
无人值守驱动 Sequence 上已注资的外部执行者	通过 CLI 钱包无人值守使用 Sequence	xl1-wallet CLI，密码存储在操作系统钥匙串中
在无头 Chromium 中测试浏览器环境代码	无头浏览器模式测试	vitest 浏览器模式 + Playwright provider，使用 MSW 模拟
驱动完整渲染的应用 UI	如果仓库有自己的 e2e 软件包（通常是 packages/e2e），则使用该软件包；否则使用 全应用 Playwright e2e（xy-toolchain）	使用 Playwright Test 测试真实 UI，通过 pnpm --filter <e2e-package> test 运行
在该 e2e 中驱动真实的 XL1 Wallet 扩展——XYO 内部	@xyo-network/wallet-xl1-harness-playwright + @xyo-network/wallet-xl1-harness-core（受限；未登录时执行 npm view 会返回 E404）。walletLocalChainEndpoint / walletLocalOnly 选项会让钱包使用本地发布链	Playwright Test walletTest fixtures（wallet、dappPage），运行于真实扩展之上

本地链启动方式——任选其一

方式	适用场景
xl1 start	手动 / 会话调试；尚无 vitest 预设
dapp-kit-vitest-config local-xl1	当你可以添加已发布的预设时，适用于 CI/TDD 的公共首选方案（其 api-local 项目会为 spec/api-local 规范启动同一个公共链）
xl1-vitest-config apiLocal	仅供 XYO 内部使用（受限软件包）

本地链与测试网：先在本地链上迭代，然后在发布前通过 Sequence 确认。本地链使用 简化的开发共识，且没有 EVM 质押层。

应用组合方式 — 二选一

形式	技术栈文档
经典 React/service + Aries reducer 发布	完整本地 dApp 技术栈 — 经典版
@xyo-network/dapp-kit* / xl1.dapp.json	完整本地 dApp 技术栈 — dapp-kit + xl1-dapp-kit

它们可以组合使用：使用 CLI 钱包执行者为 Sequence 账户注资并进行操作，通过无头测试网验证断言链上交互，再通过浏览器端到端测试验证 UI。无头测试通过能证明“链上部分正常运行”，但不能证明“UI 正常运行”。

无头验证方法

“无头验证”指在没有浏览器或钱包扩展的情况下证明链上行为。此汇总页列出了各种方式：

• 无头测试网验证 — Sequence。
• 本地开发链验证 — 公共 xl1 start。
• 通过 dApp Kit Vitest 验证本地链 — 由公共 vitest 管理的链。
• 通过 apiLocal 验证本地链 — 由 XYO 内部 vitest 管理的链（受限的 @xyo-network/xl1-vitest-config）。
• 本地链 + Aries 数据湖固定装置 — 链 + Aries 存储。
• 完整本地 XL1 dApp 技术栈 — 经典 Aries 或 dapp-kit 组合方式。

交叉引用

• Node Gateway — GatewayBuilder、REST/S3 网关，以及进程内方式使用的网络端点。
• Gateway — 查看器 API、交易方法、网络和 AttoXL1 单位。
• dApp 完成定义 — 要求进行验证的完成门槛。