xl1-testing

name	xl1-testing
description	How to test and verify XL1 work — choosing and running the right verification approach. Groups the headless verification methods: headless testnet verification (an in-process seed-phrase signer against the live Sequence testnet) and local dev-chain verification (the same signer against a free, deterministic local chain launched with the public xl1 CLI), composed local chain + Aries data-store verification, and full local dApp backend verification with @ariestools/aries-dapp-core, plus unattended Sequence testing via the @xyo-network/wallet-xl1-cli (`xl1-wallet`) CLI with an OS-keychain-stored password and headless browser-mode testing (vitest + Playwright, headless Chromium) for browser-environment code, plus a pointer to full-app browser e2e. Includes shared testnet-only safety rules. Activates when an agent needs to test, verify, or smoke-test an XL1 dApp or protocol change, run on-chain tests against a local chain or the Sequence testnet, run headless browser tests, or set up unattended / CI testing.
metadata	{"version":"1.1.29"}

XL1 Testing

The hub for testing and verifying XL1 work. It routes to the right verification approach and documents each one. 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. When reporting which skills informed your work, format as <skill-name> v<version> (e.g. xl1-testing v1.1.25). When multiple skills from this plugin are active, each may be listed.

Lower-layer skills

Testing builds on the rest of the stack. Also consult:

• xl1-knowledge — chain, gateway, SDK, and the network endpoints under test.
• xl1-patterns — dApp patterns and the dApp Definition of Done that verification plugs into.
• xy-toolchain — Vitest layout, @ariestools/vitest-config, xy test / xy retest, and other shared toolchain commands.
• xyo-knowledge / xy-development — protocol primitives and testing/workflow conventions.

⛔ 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 sequence or local. Never make routine or automated runs hit xl1-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 (CI, TDD loops, multi-account flows)	Local dev-chain verification	Local xl1 start chain + in-process signer (genesis-funded dev account)
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: finalized-chain source, real reducer, coherent state/index publication, and anonymous verification	Full local XL1 dApp stack	Direct xl1 CLI + project-owned aries-dapp-core composition
Drive an external, funded actor on Sequence unattended (fund an address, send test transactions, broadcast signed tx files) across many runs	Unattended Sequence via CLI wallet	Standalone xl1-wallet CLI, password in the OS keychain
Test browser-environment code (in-page gateway, IndexedDB datalake, PostMessage transport, browser SDK build) in headless Chromium	Headless browser-mode testing	vitest browser mode + Playwright provider, MSW-mocked

Local vs testnet: iterate on local dev-chain (free, instant, resets clean each run), then confirm against Sequence before shipping — local uses simplified dev consensus and no EVM staking layer, so it proves your interactions, not full-network behavior.

For backend work, progress through the two composition layers: first prove the chain and data store independently with the local chain + Aries fixture, then use the full local dApp stack to prove the real reducer and published consumer view. The second is a superset of the first.

They compose: use the CLI-wallet actor to fund/operate a Sequence account, headless testnet verification to assert a dApp's chain interactions programmatically, and browser e2e to validate the user-facing 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 — in-process seed-phrase signer against the live Sequence testnet. The default for validating before shipping.
• Local dev-chain verification — the same in-process signer against a free, deterministic local chain launched with the public xl1 CLI (xl1 start). Offline, instant, genesis-funded — the fast inner loop for CI/TDD.
• Local chain + Aries data-lake fixture — a direct xl1 actor topology plus the local Aries data/state/index object-store fixture, with explicit lifecycle and authority boundaries.
• Full local XL1 dApp stack — adds a project-owned finalized-chain source, real DappReducer, head-last publication, durable progress, and browser-neutral consumer verification.

Additional headless verification methods will be documented alongside these here as they are added.

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.