xl1-testing

XL1 テスト

XL1 の作業をテスト・検証するためのハブです。適切な検証方法を案内し、それぞれの方法を説明し、「完了」の条件となる dApp Definition of Done を管理します。この SKILL を読んで方法を選び、手順全体についてはリンク先のサブドキュメントを開いてください。

スキルの識別情報。 このスキルのバージョンは、このファイルのフロントマターにある metadata.version で公開されています。計画、受領確認、完了サマリーを提示する際は、どのスキルを参考にしたかを <skill-name> v<version> の形式で記載してください。バージョンは例ではなく、このファイルのフロントマターから読み取ってください。このプラグインの複数のスキルが有効な場合は、それぞれを記載してもかまいません。

スキルの階層

これは 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）— 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 の完了ゲートを管理します。任意ではなく、「時間があれば」実施するものでもありません。チェックリストに沿って明示的に確認し、完了サマリーでは該当する各セクションの合格・不合格を示してください。チェックリストには、スキルスタック全体で説明されているルールとアンチパターン（ゲートウェイの使用、データレイクの設定、ウォレット統合、SDK ファーストの遵守、ペイロード設計、インデクサーの下限ブロック、高さ、プロバイダーアーキテクチャ、表示規約、コミット・リビールの正確性、決済権限者、複数当事者による共同署名、アーキテクチャ原則、dApp Kit、ヘッドレス検証）がまとめられています。「（該当する場合）」と記されたセクションを省略できるのは、本当に対象外である場合に限られます。どの項目を省略したか、その理由とともに明記してください。これは3つのゲートからなる完了ゲートのゲート2です。ゲート1（xy-development の汎用 DoD）は常に適用され、ゲート3（PRD.md の受け入れ基準）は PRD.md が存在する場合に適用されます。

⛔ デフォルトではテストネットのみ

ここに記載されたすべてのフローは、人間が特定の実行について明示的かつ意図的にメインネットを選択しない限り、テストネット（sequence または local チェーン）を対象とします。

• すべての検証・テストでは、デフォルトで sequence または local を使用してください。定常的な実行や自動実行で xl1-mainnet / 実際の XL1 に接続してはいけません。
• シードとウォレットのパスワードは秘密情報です。コミット、ログへの記録、出力は決してしないでください。
• 無人 CLI ウォレットフローでは、パスワードを OS キーチェーンに保存し、自動でロックを解除します。これはホットウォレットであり、価値のないテストトークンに限って使用できます。詳細な安全上の制約については、説明ドキュメントを参照してください。

アプローチを選ぶ

目的	使用するもの	署名者／アクター
dApp のチェーンとのやり取りが、ライブのテストネットでプロセス内で動作することを検証する（エージェントによるビルド、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 データ／オブジェクトレイクを一緒にテストする	ローカルチェーン＋Aries データレイクフィクスチャ	xl1 CLI と aries dapp CLI を直接使用し、noop アクターと組み合わせる
完全なローカル XL1 dApp バックエンド（従来型 または dapp-kit）をテストする	完全なローカル XL1 dApp スタック	従来型：aries-dapp-core。dapp-kit：xl1-dapp／ローカルホスト＋dapp-kit vitest
Sequence 上の外部の資金調達済みアクターを無人で操作する	CLI ウォレット経由の無人 Sequence	xl1-wallet CLI、パスワードは OS のキーチェーンに保存
ヘッドレス Chromium でブラウザー環境のコードをテストする	ヘッドレスブラウザーモードテスト	vitest のブラウザーモード＋Playwright プロバイダー、MSW でモック
レンダリング済みのアプリ UI 全体を操作する	リポジトリに独自の e2e パッケージ（多くの場合 packages/e2e）があればそれを使用し、なければ アプリ全体の Playwright e2e（xy-toolchain）	実際の UI に対する Playwright Test。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 フィクスチャ（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 ステーキングレイヤーはありません。

アプリケーション構成 — いずれか1つを選択

構成	スタックのドキュメント
従来型の React／サービス ＋ Aries reducer の公開	完全なローカル dApp スタック — 従来型
@xyo-network/dapp-kit* / xl1.dapp.json	完全なローカル dApp スタック — dapp-kit ＋ xl1-dapp-kit

これらを組み合わせることで、CLI ウォレットアクターを使って Sequence アカウントに資金を追加して操作し、ヘッドレスのテストネット検証でチェーンとのやり取りを確認し、ブラウザーの E2E テストで 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 の完了条件 — 検証を必須とする完了基準。