The hub for testing and verifying XL1 work. It routes to the right verification approach, documents each one, and owns the dApp Definition of Done that gates "done". Read this SKILL to choose an approach, then open the linked sub-doc for the full procedure.
Skill identity. This skill's version is exposed in this file's frontmatter under metadata.version. Whenever you present a plan, an acknowledgement, or a completion summary, state which skills informed it, formatted as <skill-name> v<version> — read the version from this file's frontmatter, never from an example. When multiple skills from this plugin are active, each may be listed.
Skill layers
This is Layer 7 of the XYO skill stack: 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).
- Builds on: xl1-dapp-kit (6) — when the project uses
@xyo-network/dapp-kit*/xl1.dapp.json; xl1-patterns (5) — the dApp patterns and architecture principles the Definition of Done checks; xl1-knowledge (4) — chain, gateway, SDK, and the network endpoints under test; xyo-knowledge (3) — protocol primitives;xy-toolchainandxy-developmentfrom ariestools-skills (1–2) — Vitest layout,@ariestools/vitest-config,xy test/xy retest; testing and workflow conventions, including the generic Definition of Done - Hands off to: xl1-scaffold (8) — when starting a new XL1 project, which wires these verification paths in from the start; xl1-build (9) — when the build request is still vague
dApp Definition of Done
REQUIRED before reporting any XL1 dApp work as complete. This skill owns the dApp completion gate. Not optional, not "if you have time" — walk it explicitly and call out pass/fail per relevant section in your completion summary. The checklist enumerates the rules and anti-patterns documented across the skill stack (gateway usage, datalake setup, wallet integration, SDK-first compliance, payload design, indexer floor block, provider architecture, display conventions, commit-reveal correctness, settlement authorities, multi-party co-signing, architecture principles, dApp Kit, headless verification). Sections marked "(if applicable)" can be skipped only when truly out of scope — state which and why. It is Gate 2 of a three-gate completion gate; Gate 1 (the generic DoD from xy-development) always applies, and Gate 3 (PRD.md acceptance criteria) applies when a PRD.md exists.
⛔ Testnet-only by default
All flows here target testnets (sequence, or a local chain) unless a human
explicitly and deliberately opts into mainnet for a specific run.
- Default every verification/test to
sequenceorlocal. Never make routine or automated runs hitxl1-mainnet/ real XL1. - Seeds and wallet passwords are secrets — never commit, log, or echo them.
- The unattended CLI-wallet flow stores a password in the OS keychain and auto-unlocks; that is a hot wallet and is acceptable only for valueless test tokens. See its doc for the full guardrails.
Choose an approach
| You want to… | Use | Signer / actor |
|---|---|---|
| Prove a dApp's chain interactions work against a live testnet, in-process (agentic build, CI smoke test, regression) | Headless testnet verification | In-process seed-phrase signer via GatewayBuilder.buildRunner() |
| Prove them against a free, deterministic local chain — offline, no funding step, fast | Local dev-chain verification | Local xl1 start chain + in-process signer (genesis-funded dev account) |
| Same, but let vitest own the chain (public packages) — default for new dapp-kit / public consumers | Local chain via dApp Kit Vitest | @xyo-network/dapp-kit-vitest-config local-xl1 (or its public api-local project for existing spec/api-local specs) + in-process signer |
| Same vitest-owned chain, but XYO-internal restricted harness | Local chain via apiLocal | @xyo-network/xl1-vitest-config apiLocal (restricted) |
| Test a local XL1 chain and an independently hosted Aries data/object lake together, without yet running a real reducer | Local chain + Aries data-lake fixture | Direct xl1 CLI + aries dapp CLI with the noop actor |
| Test a complete local XL1 dApp backend (classic or dapp-kit) | Full local XL1 dApp stack | Classic: aries-dapp-core. dapp-kit: xl1-dapp / local hosts + dapp-kit vitest |
| Drive an external, funded actor on Sequence unattended | Unattended Sequence via CLI wallet | xl1-wallet CLI, password in the OS keychain |
| Test browser-environment code in headless Chromium | Headless browser-mode testing | vitest browser mode + Playwright provider, MSW-mocked |
| Drive the fully rendered app UI | The repo's own e2e package (often packages/e2e) if it has one; otherwise Full-app Playwright e2e (xy-toolchain) |
Playwright Test against the real UI, run with pnpm --filter <e2e-package> test |
| Drive the real XL1 Wallet extension in that e2e — XYO-internal | @xyo-network/wallet-xl1-harness-playwright + @xyo-network/wallet-xl1-harness-core (restricted; E404 to a logged-out npm view). The walletLocalChainEndpoint / walletLocalOnly options keep the wallet on a local published chain |
Playwright Test walletTest fixtures (wallet, dappPage) over the real extension |
Local chain boot — pick one
| Route | When |
|---|---|
xl1 start |
Manual/session debugging; no vitest preset yet |
dapp-kit-vitest-config local-xl1 |
Preferred public CI/TDD when you can add the published preset (its api-local project boots the same public chain for spec/api-local specs) |
xl1-vitest-config apiLocal |
XYO-internal only (restricted packages) |
Local vs testnet: iterate on a local chain, then confirm against Sequence before shipping. Local uses simplified dev consensus and no EVM staking layer.
Application composition — pick one
| Shape | Stack doc |
|---|---|
| Classic React/service + Aries reducer publication | Full local dApp stack — classic |
@xyo-network/dapp-kit* / xl1.dapp.json |
Full local dApp stack — dapp-kit + xl1-dapp-kit |
They compose: use the CLI-wallet actor to fund/operate a Sequence account, headless testnet verification to assert chain interactions, and browser e2e for UI. A passing headless run proves "the chain side works"; it does not prove "the UI works."
Headless verification methods
"Headless verification" means proving on-chain behavior without a browser or the wallet extension. This barrel groups the variants:
- Headless testnet verification — Sequence.
- Local dev-chain verification — public
xl1 start. - Local chain via dApp Kit Vitest — public vitest-owned chain.
- Local chain via apiLocal — XYO-internal vitest-owned chain (restricted
@xyo-network/xl1-vitest-config). - Local chain + Aries data-lake fixture — chain + Aries stores.
- Full local XL1 dApp stack — classic aries or dapp-kit composition.
Cross-References
- Node Gateway —
GatewayBuilder, REST/S3 gateway, and network endpoints used by the in-process approach. - Gateway — viewer API, transaction methods, networks, and AttoXL1 units.
- dApp Definition of Done — the completion gate that requires verification.